Field

Layout & Orientation

Use orientation="vertical" (default) for text inputs, textareas, and selects where the label sits above the control. Use orientation="horizontal" for checkboxes, radios, and switches where label and control sit side-by-side. Use orientation="responsive" to auto-switch between vertical on narrow containers and horizontal on wider ones.

Grouping & Structure

Wrap related fields in a FieldSet with a FieldLegend to create semantic groups. Use FieldGroup to stack multiple fields with consistent gap-7 spacing. Nest FieldGroup components for sub-sections with tighter gap-4 spacing.

Error Handling

Add data-invalid to the Field wrapper to activate error styling. Always pair with aria-invalid on the form control and a FieldError message. Multiple errors are automatically rendered as a bulleted list via the errors prop.

Color & Tokens

Labels use text-foreground for primary readability. Descriptions use text-muted-foreground for secondary emphasis. Error states apply text-destructive automatically via data-[invalid=true]. Disabled fields reduce opacity to 50% through group-data-[disabled=true]/field:opacity-50.

Keyboard Navigation

• Tab -- Move focus between form controls within the field
• Space -- Toggle checkboxes and switches
• Arrow Up / Arrow Down -- Navigate between radio options in a group
• Enter -- Submit the form when focused on any control

Screen Reader Support

• FieldLabel uses the htmlFor attribute to associate labels with controls
• FieldError uses role="alert" so errors are announced immediately
• Field outputs role="group" to group label, control, and description
• FieldSet and FieldLegend provide native fieldset/legend semantics for assistive tech

Error Announcements

When data-invalid is set, FieldError renders with role="alert", which triggers an immediate announcement by screen readers. Always add aria-invalid on the input and connect via aria-describedby for full association.

Focus Management

Labels with htmlFor clicking the label focuses the associated control. Disabled fields apply opacity-50 and prevent interaction. Focus indicators follow the design system ring styles for consistent visual feedback.

ARIA Attributes

{/* Field with label association */}
<Field>
  <FieldLabel htmlFor="name">Full Name</FieldLabel>
  <Input id="name" placeholder="Enter your name" />
  <FieldDescription>Your legal name as it appears on documents.</FieldDescription>
</Field>

{/* Field with error state - uses role="alert" */}
<Field data-invalid>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" aria-invalid aria-describedby="email-error" />
  <FieldError id="email-error">Enter a valid email address.</FieldError>
</Field>

{/* FieldSet groups related controls with legend */}
<FieldSet>
  <FieldLegend>Notification Preferences</FieldLegend>
  <FieldGroup>
    <Field orientation="horizontal">
      <Checkbox id="email-notify" />
      <FieldLabel htmlFor="email-notify">Email notifications</FieldLabel>
    </Field>
  </FieldGroup>
</FieldSet>

{/* Switch with FieldContent for accessible description */}
<Field orientation="horizontal">
  <FieldContent>
    <FieldLabel htmlFor="dark-mode">Dark Mode</FieldLabel>
    <FieldDescription>Toggle between light and dark themes.</FieldDescription>
  </FieldContent>
  <Switch id="dark-mode" />
</Field>