Field

Core Idea

Field is the composable primitive family for building accessible forms: it combines labels, controls (Input/Select/Switch/Checkbox/Slider/Textarea), help text, and validation errors into consistent, groupable units, replacing ad-hoc label+input markup.

Key Concepts

• Field: core wrapper for a single control; controls orientation (vertical | horizontal | responsive) and invalid state via data-invalid. Renders role="group".
• FieldGroup: layout wrapper that stacks Fields and enables container queries for responsive orientation switching.
• FieldSet + FieldLegend: semantic <fieldset>/<legend> grouping for a whole section (e.g. "Payment Method"); FieldLegend has legend (default) and label (smaller, for nested fieldsets) variants.
• FieldContent: flex-column grouping label+description when the label sits beside the control (horizontal orientation); skip if there's no description.
• FieldLabel / FieldTitle / FieldDescription: label, title (styled like a label, used inside FieldContent for non-form contexts like a Slider), and helper text.
• FieldSeparator: visual divider between sections inside a FieldGroup, optionally with inline text (e.g. "Or continue with").
• FieldError: accessible error container; accepts children, an errors array (react-hook-form shape {message?: string}[]), or Standard Schema issues (Zod/Valibot/ArkType) — renders a list automatically for multiple messages.

Code Examples

<FieldSet>
  <FieldLegend>Profile</FieldLegend>
  <FieldDescription>This appears on invoices and emails.</FieldDescription>
  <FieldGroup>
    <Field>
      <FieldLabel htmlFor="name">Full name</FieldLabel>
      <Input id="name" autoComplete="off" placeholder="Evil Rabbit" />
      <FieldDescription>This appears on invoices and emails.</FieldDescription>
    </Field>
    <Field>
      <FieldLabel htmlFor="username">Username</FieldLabel>
      <Input id="username" autoComplete="off" aria-invalid />
      <FieldError>Choose another username.</FieldError>
    </Field>
    <Field orientation="horizontal">
      <Switch id="newsletter" />
      <FieldLabel htmlFor="newsletter">Subscribe to the newsletter</FieldLabel>
    </Field>
  </FieldGroup>
</FieldSet>

• O que demonstra: composição completa (FieldSet > FieldGroup > Field) com label, descrição, erro, e orientação horizontal para um switch.

<Field data-invalid>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" type="email" aria-invalid />
  <FieldError>Enter a valid email address.</FieldError>
</Field>

• O que demonstra: padrão de estado de erro: data-invalid no Field + aria-invalid no input + FieldError logo depois.

Reference Tables

Component	Key Props	Notes
Field	orientation: "vertical"|"horizontal"|"responsive" (default vertical), data-invalid: boolean	core single-field wrapper, role="group"
FieldGroup	className	stacks Fields, enables @container queries
FieldSet	className	renders <fieldset>
FieldLegend	variant: "legend"|"label" (default legend)	label variant for nested fieldsets
FieldContent	className	groups label+description beside control
FieldLabel	className	works for direct inputs and nested Field children
FieldTitle	className	label-styled title inside FieldContent
FieldDescription	className	auto-balances long lines in horizontal layouts
FieldSeparator	className	divider, accepts inline content
FieldError	errors: Array<{message?:string}|undefined>, className	accepts children, errors, or Standard Schema issues

Anti-patterns

• Skipping FieldContent when combining a control + description in horizontal orientation: description/label won't group correctly beside the control.
• Putting FieldError far from the control: render it immediately after the control (or inside FieldContent) to keep it visually and semantically aligned.
• Overusing FieldSeparator: apply sparingly, screen reader users need clear, not excessive, section boundaries.

Key Takeaways

1. Field supports Input, Textarea, Select, Slider, Checkbox, Radio, Switch, and "Choice Card" controls — it's control-agnostic, not just for text inputs.
2. FieldError is validator-agnostic: works with plain children, react-hook-form's errors, or any Standard Schema (Zod/Valibot/ArkType) issues array.
3. Use orientation="horizontal" for checkbox/switch + label pairs; "responsive" lets FieldGroup's container queries switch orientation based on available width.
4. RTL support and responsive layout are both handled by the component (see full docs sections "RTL" and "Responsive Layout" for detail beyond this reference).

Connects To

• components-input: Input is the most common control placed inside Field.
• components-input-otp: OTP input also composes with Field/FieldLabel patterns.
• Forms (react-hook-form/tanstack-form/formisch): /docs/forms/* docs show Field wired to real form libraries.