Form Field

Ties label + control + error + description together with full ARIA wiring and stack / inline / floating layouts — pairs with react-hook-form/zod, no bundled validation engine.

Group: Form Controls · Import path: @orionshub/lucent/form-field · Server-safe — renders on the server without a client bundle.

Import

import { FormField } from '@orionshub/lucent'
import '@orionshub/lucent/styles.css' // once, at your app root

Examples

Layouts & validation

Layouts & validation

Show source

export function FormFieldBasic() {
  return (
    <div style={stack}>
      <FormField label="Name" id="ff-name" description="As it appears on your card.">
        <Input id="ff-name" placeholder="Ada Lovelace" />
      </FormField>
      <FormField label="Email" id="ff-email" error="Enter a valid email" isInvalid>
        <Input id="ff-email" placeholder="you@example.com" />
      </FormField>
      <FormField layout="floating" label="Full name" id="ff-float">
        <Input id="ff-float" placeholder=" " />
      </FormField>
    </div>
  )
}

Props

Prop	Type	Default	Description
children*	React.ReactNode	—
className	string | undefined	—
description	string | undefined	—	Helper text shown below the control.
error	string | undefined	—	Error message shown below the control (overrides validate() result).
id	string | undefined	—	The id to use for ARIA wiring (htmlFor on Label, aria-describedby on control). When omitted, ARIA auto-wiring is skipped (document this constraint in usage).
isInvalid	boolean | undefined	—	Whether the control is in an invalid state.
label	React.ReactNode	—	Label text rendered above/beside the control.
layout	FormFieldLayout | undefined	—	Layout variant. Defaults to 'stack'.
validate	((value: unknown) => string | null) | undefined	—	Lightweight inline validator. Called with the child control's value prop. Returns an error string (shown) or null (no error). For production forms, use react…

Guidance

One-time CSS import

Import the compiled stylesheet once at your app root: import '@orionshub/lucent/styles.css'. Components ship stable class names and read design tokens from CSS custom properties — there is no style runtime. See CSS Import.

Transparency & solid mode

Every glass surface reads --lucent-glass-opacity (0.60–1.0). Dial it at runtime with setGlassOpacity(), or switch to setContrast('solid') for a fully opaque, high-contrast rendering. See Transparency & Solid Mode.

RTL

Authored with CSS logical properties — set dir="rtl" on a parent (or the document) and layout mirrors with no JS. Toggle RTL from the glass-controls panel to preview. See RTL Support.

SSR / Next.js

Server-safe — renders on the server without a client bundle. All components are safe to import in a Server Component tree; interactive ones carry their own "use client" boundary. See SSR & Next.js.