Form

Import

import { useForm } from "react-hook-form"
import { zodResolver } from "@hookform/resolvers/zod"
import {
  Form,
  FormControl,
  FormDescription,
  FormField,
  FormItem,
  FormLabel,
  FormMessage,
} from "@timelycare/helix-ui"

Props

interface FormFieldProps {
  name: string
  control: Control<any>
  render: ({ field }) => React.ReactNode
}

interface FormItemProps {
  className?: string
  children: React.ReactNode
}

Form Layouts

Choosing a Layout

• Use single column for 1-4 fields or mobile views
• Use two column for 5+ fields on desktop
• Always wrap in Card for visual grouping

Field Spacing

Card Constraints

Supported Field Types

Forms commonly include these field components:

• Input — text fields with label and optional description
• Select — dropdown selection
• Combobox — searchable dropdown with optional avatar
• Textarea — multi-line text input
• Switch — toggle with label and description
• Radio Group — single selection from options
• Checkbox — boolean selection with label and description
• Date Picker — date selection trigger

Common Patterns

Basic Form

<Card>
  <CardHeader>
    <CardTitle>Sign up</CardTitle>
    <CardDescription>Create your new account.</CardDescription>
  </CardHeader>
  <CardContent className="space-y-4">
    <FormField
      control={form.control}
      name="email"
      render={({ field }) => (
        <FormItem>
          <FormLabel>Email</FormLabel>
          <FormControl>
            <Input placeholder="name@example.com" {...field} />
          </FormControl>
          <FormMessage />
        </FormItem>
      )}
    />
  </CardContent>
  <CardFooter>
    <Button type="submit" className="w-full">Create account</Button>
  </CardFooter>
</Card>

Two Column Form

<CardContent>
  <div className="flex gap-4">
    <div className="flex-1 space-y-4">
      <FormField name="firstName" /* ... */ />
      <FormField name="email" /* ... */ />
    </div>
    <div className="flex-1 space-y-4">
      <FormField name="lastName" /* ... */ />
      <FormField name="phone" /* ... */ />
    </div>
  </div>
</CardContent>

Responsive Two Column

<CardContent>
  <div className="flex flex-col md:flex-row gap-4">
    <div className="flex-1 space-y-4">
      {/* Left column fields */}
    </div>
    <div className="flex-1 space-y-4">
      {/* Right column fields */}
    </div>
  </div>
</CardContent>

With Multiple Actions

<CardFooter className="flex justify-between">
  <Button variant="outline" type="button">Cancel</Button>
  <Button type="submit">Submit</Button>
</CardFooter>

Field with Description

<FormItem>
  <FormLabel>Bio</FormLabel>
  <FormControl>
    <Textarea placeholder="Tell us about yourself" {...field} />
  </FormControl>
  <FormDescription>Max 500 characters.</FormDescription>
  <FormMessage />
</FormItem>

With Switch Field

<FormField
  control={form.control}
  name="notifications"
  render={({ field }) => (
    <FormItem className="flex gap-3 items-start">
      <FormControl>
        <Switch checked={field.value} onCheckedChange={field.onChange} />
      </FormControl>
      <div className="space-y-1.5">
        <FormLabel>Enable notifications</FormLabel>
        <FormDescription>Receive email notifications.</FormDescription>
      </div>
    </FormItem>
  )}
/>

With Checkbox Field

<FormField
  control={form.control}
  name="terms"
  render={({ field }) => (
    <FormItem className="flex gap-2 items-start">
      <FormControl>
        <Checkbox checked={field.value} onCheckedChange={field.onChange} />
      </FormControl>
      <div className="space-y-1.5">
        <FormLabel>Accept terms</FormLabel>
        <FormDescription>I agree to the terms and conditions.</FormDescription>
      </div>
    </FormItem>
  )}
/>

With Radio Group

<FormField
  control={form.control}
  name="type"
  render={({ field }) => (
    <FormItem className="space-y-2">
      <FormLabel>Select type</FormLabel>
      <FormControl>
        <RadioGroup onValueChange={field.onChange} defaultValue={field.value}>
          <div className="flex items-center gap-3">
            <RadioGroupItem value="option1" id="option1" />
            <Label htmlFor="option1">Option 1</Label>
          </div>
          <div className="flex items-center gap-3">
            <RadioGroupItem value="option2" id="option2" />
            <Label htmlFor="option2">Option 2</Label>
          </div>
        </RadioGroup>
      </FormControl>
    </FormItem>
  )}
/>

Accessibility

• Built on React Hook Form + Radix Form primitives
• Automatically manages aria-describedby linking fields to error/description
• Sets aria-invalid on fields with validation errors
• Screen reader: announces validation errors via FormMessage, which takes role="alert" while an error is present (plain hint content passed as children is not announced)
• Label association automatic via FormLabel and FormControl

FormMessage owns the announcement

role="alert" is assertive — it interrupts the screen reader. Since every erroring FormMessage takes it, a form with three invalid fields already has three assertive regions firing on one submit. Adding a form-level Alert error summary at its default role makes four, and simultaneous assertive regions are queued or dropped depending on the screen reader.

If you render a summary, hand it a quieter role — Alert spreads props after its own role, so this works:

<Alert variant="destructive" role="status">
  <CircleX />
  <AlertTitle>Could not save</AlertTitle>
  <AlertDescription>Fix the 3 highlighted fields and try again.</AlertDescription>
</Alert>

Use role="status" when the summary adds something the field messages don't (a server-side failure reason), and role={undefined} when it only repeats them.

Worth knowing: react-hook-form's shouldFocusError defaults to true, so a failed submit focuses the first invalid field. That message is read via aria-describedby on focus and fires as an alert, so the first error is announced twice. That is inherent to the fix that makes on-submit errors audible at all, and is preferable to the previous behaviour, where an error appearing while focus sat on the submit button was announced by nothing.

Gotchas

See Also

• Accessibility: Form Accessibility Requirements - Error handling, label associations, screen reader behavior
• Related Components: Input, Select, Checkbox, Radio Group
• Patterns: Card with Form (see Card component page)

Last updated: February 9, 2026