Keyboard accessible by default with semantic markup, visible focus treatment, and tokenized states. Add descriptive labels for icon-only or decorative usage.
Dependency notes
Check Installation for shared peers. This component keeps styling in Tailwind classes and the --zui-* token contract.
Forms
Form / Field for accessible input layouts
Compose existing inputs, textareas, checkboxes, and selects with connected labels, descriptions, and error messages. Keep validation and submission in your application while Field handles consistent layout and accessibility attributes.
Responsive orientation stacks the label above the control below 640px. Horizontal keeps both side by side. Field size changes spacing and text; Input size is configured separately.
A short name makes your workspace easier to find.
Appearance gallery
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Your project home.
Form and field recipes
A connected label and description
We will only use this for account updates.
Validation with focus and a submission result
Responsive fields with Grid
Grouped checkbox choices
A custom Select with a shared trigger ID
A custom Select uses the Field control ID on its root.
Composition and accessibility
Field owns a single control’s label, description, and error through its label, description, and error props. Connections exist in server markup and update with the content. Its generated control ID is independent of the wrapper id; use controlId when you need an explicit ID. Each ID must be unique in the document.
FieldControl accepts exactly one element that forwards attributes to its focusable control. It assigns the Field ID, combines description IDs, and retains the child’s ref, event handlers, value, and native attributes. A field label names the control; an explicit aria-label or aria-labelledby on the child takes precedence. Native disabled/required on the child are retained. For custom composition use the render function or useFieldControl; merge any existing aria-describedby when spreading attributes yourself.
Use FieldControl with Input without Input’s own label or errorMessage to avoid duplicated labels and messages. Native inputs, textareas, selects, and Checkbox work with the default native mode. For Select, share the Field ID with Select’s triggerId, wrap SelectTrigger with FieldControl native=false, and provide role=combobox. Other custom widgets must implement their own disabled and required behavior; aria-required does not validate or block submission. A hidden input can carry a custom selection into FormData.
Form preserves native form props and browser validation. Field error implies invalid, with an explicit invalid override available. Field never runs validation, submits data, or focuses controls automatically. The validation recipe uses noValidate intentionally, reads native validity, and focuses the failed control. Keep visible error messages clear and connect them to their controls. Render errors after validation. Inline Field errors are passive descriptions, read with the control when focused. Standalone FieldError supports an explicit role=alert for consumer-owned notifications; avoid announcing the same message through both a live region and a focused description.
FieldGroup renders a native fieldset with an optional legend and connected description. Its disabled prop uses browser semantics, including the first-legend exception. FieldLegend, FieldLabel, FieldDescription, and FieldError can be used independently with caller-owned IDs. When composing these primitives manually, explicitly wire htmlFor and aria-describedby; only Field’s description/error props are connected automatically.
Vertical is the default. Responsive places the label beside the control from 640px and stacks below it; horizontal keeps columns at all widths. Grid can arrange multiple Field components and stacks them on mobile by default. Form and Field add no validation or animation dependencies.
pnpm add @zentauri-ui/zentauri-components
# Or vendor source, including the Input used in these recipes:pnpm dlx @zentauri-ui/zentauri-components add field inputs
Add the package to Tailwind v4 scanning and adjust the source path for your stylesheet location. Vendored files also need to be in scan scope.
Apply className="profile-form" to Form or a surrounding container. Field controls use their own Input, Checkbox, or Select tokens. Field sizes change label typography and spacing independently of the control size.
Theme field surfaces, labels, instructions, error indicators, and form/group spacing. Each token has a paired dark override; control styling remains owned by Input, Checkbox, or Select.
Consistent form and field layouts with native semantics, stable accessibility connections, 26 appearances, and paired light/dark theme tokens.
Common use cases
Account and profile forms.
Settings with grouped checkbox choices.
Responsive multi-column forms using Grid.
Custom controls with explicit accessibility connections.
Accessibility
Labels identify controls, description/error IDs are connected with aria-describedby, and native fieldset/legend semantics name groups. Required markers are decorative; native required and aria-required convey the state. Apps own validation and focus management.
FAQ
Does Field manage form state or validation?
No. Form is a native form wrapper. Field presents labels, instructions, and errors; you own values, validation, submission, and focus. It requires no form-state library.
How do labels and errors connect to the control?
Pass label, description, and error to Field, then wrap one control in FieldControl. IDs and aria-describedby are created during rendering, including on the server. Use controlId to provide a unique explicit ID.
Can I use custom controls?
Yes. FieldControl needs a child that forwards ID and ARIA props to its focusable element. Alternatively use the Field render function or useFieldControl. For Select, set triggerId to the Field ID and wrap SelectTrigger with native=false and role=combobox.
How do required and disabled work?
FieldControl applies native required and disabled by default. Custom mode uses aria-required; the custom widget must implement validation itself. FieldGroup uses native disabled fieldset semantics.
How do fields respond to mobile widths?
Fields stack vertically by default. Responsive orientation adds label/control columns at 640px. Horizontal forces columns at every width. Grid arranges multiple fields and stacks them on mobile by default.
Can I use the individual primitives?
Yes. Use FieldLabel, FieldDescription, FieldError, FieldGroup, and FieldLegend independently. Supply and connect IDs yourself; automatic descriptions and errors come from the Field props.
