Form Components Accessibility

[!CAUTION] BASED ON STANDARD RADIX/SHADCN PATTERNS — VERIFY AGAINST YOUR IMPLEMENTATION These accessibility patterns are derived from Radix UI primitive documentation and WAI-ARIA best practices. Your actual component implementations may differ. Test with a screen reader before relying on this guidance.

Applies To

• Form — wrapper component (react-hook-form + Radix Form)
• Input — text input fields
• Textarea — multi-line text input
• Select — dropdown selection (Radix Select primitive)
• Checkbox — toggle check (Radix Checkbox primitive)
• Radio Group — exclusive option selection (Radix RadioGroup primitive)
• Switch — toggle on/off (Radix Switch primitive)
• Combobox — autocomplete/search select (Radix Popover + Command)
• Date Picker — calendar-based date selection

General Form Accessibility

Label Association

Every form control must have a programmatically associated label. There are no exceptions.

Never use placeholder as the sole label — it disappears when the user starts typing.

Error Messages and Descriptions

Link hints and error messages to their fields via aria-describedby:

<div>
  <Label htmlFor="email">Email</Label>
  <Input
    id="email"
    aria-describedby="email-hint email-error"
    aria-invalid={!!errors.email}
  />
  <p id="email-hint" className="text-sm text-muted-foreground">
    We'll never share your email.
  </p>
  {errors.email && (
    <p id="email-error" role="alert" className="text-sm text-destructive">
      {errors.email.message}
    </p>
  )}
</div>

Key points:

• aria-describedby can reference multiple IDs (space-separated) — the hint and error are both announced
• aria-invalid="true" tells screen readers the field has an error
• Use role="alert" on dynamically appearing error messages so they're announced immediately
• The error message element should only be in the DOM when there's an error (or use aria-live="assertive" on a container)

Required Fields

The convention is a visible asterisk on required labels plus a form-level note explaining it — RequiredFieldsNote. It is not one option among several; see Decision: Marking Required Fields for why mixing it with "(optional)" labels leaves an unmarked field meaning nothing. Use required on FormItem or Field and the mechanics below are applied for you. What follows is what that prop produces, and what to check when you are hand-rolling a field outside those wrappers.

<RequiredFieldsNote variant="marked" />

<Label htmlFor="name">
  Name <span aria-hidden="true">*</span>
</Label>
<Input id="name" required aria-required="true" />

• Use the native required attribute AND/OR aria-required="true" — this is what actually communicates requiredness to assistive technology. The asterisk is the visible half only.
• The asterisk is hidden from screen readers with aria-hidden="true". Without it the character is announced ("Name star, required") or, on some screen readers, read as "asterisk" — noise on top of the state aria-required already conveys.
• If you want the requiredness in the label's own text rather than in the control's ARIA state, sr-only "(required)" inside the label is the way to do it — but it is an implementation detail of the asterisk, not a replacement for it. On its own it leaves sighted users with no indicator at all, and paired with aria-required it stutters: "Name, required, required, edit text". Prefer the asterisk + aria-required pairing above.
• When every field is required, mark none of them and use <RequiredFieldsNote variant="all" /> instead. An asterisk on every label distinguishes nothing. aria-required still goes on every control.
• Never ship a label reading "Name (optional)". That is the rejected convention, and it logs a dev warning.

Component-Specific Patterns

Input

Based on standard HTML <input> — no Radix primitive.

ARIA attributes:

Keyboard:

Screen reader announcement on focus:

"Email, required, edit text, We'll never share your email" (label + required + role + description)

If invalid:

"Email, required, invalid, edit text, Please enter a valid email" (adds invalid state + error message)

Textarea

Identical to Input for accessibility. Same ARIA attributes and keyboard patterns apply.

Additionally:

• If there's a character count, announce it: aria-describedby pointing to the counter
• Auto-expanding textareas should not interfere with screen reader operation

Select (Radix)

Built on Radix Select primitive — a custom dropdown that replaces native <select>.

ARIA attributes (handled by Radix):

Keyboard interactions:

Grouped options:

• Radix SelectGroup renders role="group" with aria-labelledby pointing to the SelectLabel
• Screen readers announce group label before options in that group

Screen reader announcement on focus:

"Country, combo box, collapsed, United States" (label + role + state + current value)

On open:

"listbox, 5 items" + focused option announced

Checkbox (Radix)

Built on Radix Checkbox primitive.

ARIA attributes (handled by Radix):

Keyboard interactions:

Do NOT use Enter to toggle — this is the standard behavior per WAI-ARIA. Radix enforces this.

Implementation pattern:

<div className="flex items-center gap-2">
  <Checkbox
    id="terms"
    checked={checked}
    onCheckedChange={setChecked}
    aria-describedby="terms-desc"
  />
  <Label htmlFor="terms">Accept terms and conditions</Label>
  <p id="terms-desc" className="sr-only">
    You must accept the terms to continue.
  </p>
</div>

Indeterminate state (e.g., "select all" when some items are selected):

• Pass checked="indeterminate" to Radix Checkbox
• Screen reader announces: "Accept all, checkbox, mixed"

Screen reader announcement:

"Accept terms and conditions, checkbox, not checked" → (press Space) → "checked"

Radio Group (Radix)

Built on Radix RadioGroup primitive.

ARIA attributes (handled by Radix):

Keyboard interactions:

Important: Arrow keys both move focus AND select the option — this is the standard radio group behavior per WAI-ARIA. Individual radios are NOT separately tab-focusable.

Implementation pattern:

<RadioGroup value={value} onValueChange={setValue} aria-label="Notification preference">
  <div className="flex items-center gap-2">
    <RadioGroupItem value="all" id="all" />
    <Label htmlFor="all">All notifications</Label>
  </div>
  <div className="flex items-center gap-2">
    <RadioGroupItem value="mentions" id="mentions" />
    <Label htmlFor="mentions">Mentions only</Label>
  </div>
  <div className="flex items-center gap-2">
    <RadioGroupItem value="none" id="none" />
    <Label htmlFor="none">None</Label>
  </div>
</RadioGroup>

Screen reader announcement:

"Notification preference, radio group" → "All notifications, radio, 1 of 3, selected"

Switch (Radix)

Built on Radix Switch primitive. Visually a toggle, semantically a switch.

ARIA attributes (handled by Radix):

Keyboard interactions:

Implementation pattern:

<div className="flex items-center gap-2">
  <Switch
    id="airplane"
    checked={enabled}
    onCheckedChange={setEnabled}
  />
  <Label htmlFor="airplane">Airplane mode</Label>
</div>

Screen reader announcement:

"Airplane mode, switch, off" → (press Space) → "on"

Note: role="switch" is distinct from role="checkbox". Use Switch when the control represents an immediate on/off state (like a light switch). Use Checkbox when the value is submitted as part of a form.

Combobox (Autocomplete)

Typically built with Radix Popover + Command (cmdk) — not a single Radix primitive.

ARIA attributes:

Keyboard interactions:

Implementation pattern:

<Popover open={open} onOpenChange={setOpen}>
  <PopoverTrigger asChild>
    <Button
      variant="outline"
      role="combobox"
      aria-expanded={open}
      aria-label="Select framework"
    >
      {selectedValue || "Select framework..."}
      <ChevronsUpDown className="size-4" aria-hidden="true" />
    </Button>
  </PopoverTrigger>
  <PopoverContent>
    <Command>
      <CommandInput placeholder="Search framework..." aria-label="Search frameworks" />
      <CommandEmpty>No framework found.</CommandEmpty>
      <CommandGroup>
        <CommandItem onSelect={handleSelect}>React</CommandItem>
        <CommandItem onSelect={handleSelect}>Vue</CommandItem>
      </CommandGroup>
    </Command>
  </PopoverContent>
</Popover>

Key points:

• The "No results found" state (CommandEmpty) must be announced — aria-live="polite" on the container or use the cmdk built-in announcements
• Consider announcing the result count: "5 options available" when the listbox opens or filters change
• aria-activedescendant on the input tracks which option is highlighted — this allows the input to keep DOM focus while the listbox item is virtually focused

Screen reader announcement:

"Select framework, combo box, expanded" → "React, option, 1 of 5"

Date Picker

Typically built with a text input + Radix Popover containing a calendar grid. This is one of the most complex form widgets for accessibility.

ARIA for the calendar grid:

Keyboard interactions:

Key points:

• Each date cell must have a full accessible label ("January 15, 2026"), not just the day number
• The month/year navigation buttons need aria-label (e.g., "Go to previous month", "Go to next month")
• Disabled dates should have aria-disabled="true" — explain why if possible (e.g., "January 10, 2026, not available")
• When the calendar opens, focus should move to the currently selected date (or today if no selection)
• When a date is selected, announce it: "January 15, 2026, selected" and close the popup

Form Validation Patterns

Inline Validation (On Blur)

<FormField
  control={form.control}
  name="email"
  render={({ field, fieldState }) => (
    <FormItem>
      <FormLabel>Email</FormLabel>
      <FormControl>
        <Input
          {...field}
          aria-invalid={!!fieldState.error}
          aria-describedby={fieldState.error ? "email-error" : "email-hint"}
        />
      </FormControl>
      <FormDescription id="email-hint">Enter your work email.</FormDescription>
      {fieldState.error && (
        <FormMessage id="email-error" role="alert">
          {fieldState.error.message}
        </FormMessage>
      )}
    </FormItem>
  )}
/>

Key points:

• Set aria-invalid="true" when the field has an error
• Error message appears with role="alert" so it's immediately announced
• When the error is corrected, remove aria-invalid and the error message — the screen reader won't announce the removal (which is the correct behavior)

Submit Validation (Error Summary)

When a form is submitted with errors:

1. Move focus to the first field with an error (or to an error summary at the top of the form)
2. If using an error summary:

   <div role="alert" aria-label="Form errors">
     <h2>Please correct the following errors:</h2>
     <ul>
       <li><a href="#email">Email is required</a></li>
       <li><a href="#password">Password must be at least 8 characters</a></li>
     </ul>
   </div>
   

3. Each error in the summary should link to the corresponding field (via anchor to the field's id)
4. Screen reader will announce: "Form errors, alert, Please correct the following errors: ..."

Live Region for Validation State

For real-time validation feedback (e.g., password strength):

<div aria-live="polite" aria-atomic="true" className="sr-only">
  {passwordStrength} {/* e.g., "Password strength: strong" */}
</div>

Debounce updates (300–500ms) to avoid excessive announcements while typing.

Common Mistakes

Testing Checklist

Screen Reader Testing

• All labels announced correctly on focus
• Required state announced ("required") — once, not twice, and the asterisk itself not announced
• Error messages announced when they appear (role="alert")
• aria-invalid state announced on errored fields
• Hint/description text announced via aria-describedby
• Select: options and groups announced, selected value announced
• Checkbox: checked/unchecked/mixed state announced
• Radio: group label, selected option, "X of Y" position announced
• Switch: "on"/"off" state announced
• Combobox: filtered options and selection announced
• Date picker: full date labels and navigation announced

Keyboard Testing

• All form fields reachable via Tab
• Select: Space/Enter opens, arrows navigate, Escape closes, typeahead works
• Checkbox: Space toggles
• Radio Group: Tab enters, arrows navigate AND select, Tab exits
• Switch: Space toggles
• Combobox: type to filter, arrows to navigate, Enter to select, Escape to close
• Date Picker: arrows navigate days, Page Up/Down for months, Enter selects
• Form: Enter submits from text inputs (when appropriate)
• Focus visible on all fields and controls

Visual Testing

• Error states visible beyond color alone (icon, border, text)
• Focus ring visible on all form controls
• Required indicator visible — asterisk on required labels, or "All fields are required" when every field is
• The form carries a RequiredFieldsNote whenever any label shows an asterisk
• Disabled state visually distinct

References

• WAI-ARIA Forms Pattern
• WAI-ARIA Combobox Pattern
• WAI-ARIA Checkbox Pattern
• WAI-ARIA Radio Group Pattern
• WAI-ARIA Switch Pattern
• Radix Select Primitive
• Radix Checkbox Primitive
• Radix RadioGroup Primitive
• Radix Switch Primitive

Last updated: September 9, 2026