Field

Import

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
  FieldTitle,
  RequiredFieldsNote,
} from "@timelycare/helix-ui"

Styling

Typography

Spacing

Orientation

Sub-Components

Common Patterns

Basic Input Field

<Field>
  <FieldLabel htmlFor="username">Username</FieldLabel>
  <Input id="username" placeholder="Enter username" />
  <FieldDescription>Choose a unique username for your account.</FieldDescription>
</Field>

With Validation Error

<Field>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input
    id="email"
    placeholder="m@example.com"
    className="border-destructive focus-visible:ring-destructive/50"
  />
  <FieldError>Please enter a valid email address.</FieldError>
</Field>

Grouped Fields with FieldSet

<FieldSet>
  <FieldLegend>Address Information</FieldLegend>
  <FieldDescription>We need your address to deliver your order.</FieldDescription>
  <FieldGroup>
    <Field>
      <FieldLabel htmlFor="street">Street Address</FieldLabel>
      <Input id="street" placeholder="123 Main St" />
    </Field>
    <div className="grid grid-cols-2 gap-4">
      <Field>
        <FieldLabel htmlFor="city">City</FieldLabel>
        <Input id="city" placeholder="New York" />
      </Field>
      <Field>
        <FieldLabel htmlFor="zip">Postal Code</FieldLabel>
        <Input id="zip" placeholder="90502" />
      </Field>
    </div>
  </FieldGroup>
</FieldSet>

Horizontal Checkbox

<Field orientation="horizontal">
  <Checkbox id="terms" />
  <FieldLabel htmlFor="terms" className="font-normal">
    I agree to the terms and conditions
  </FieldLabel>
</Field>

Checkbox Group with FieldSet

<FieldSet>
  <FieldLegend variant="label">Notification Preferences</FieldLegend>
  <FieldDescription>Select how you'd like to be notified.</FieldDescription>
  <FieldGroup className="gap-3">
    <Field orientation="horizontal">
      <Checkbox id="email-notif" />
      <FieldLabel htmlFor="email-notif" className="font-normal">Email</FieldLabel>
    </Field>
    <Field orientation="horizontal">
      <Checkbox id="sms-notif" />
      <FieldLabel htmlFor="sms-notif" className="font-normal">SMS</FieldLabel>
    </Field>
  </FieldGroup>
</FieldSet>

Responsive Layout

<FieldSet>
  <FieldLegend>Profile</FieldLegend>
  <FieldDescription>Fill in your profile information.</FieldDescription>
  <FieldSeparator />
  <FieldGroup>
    <Field orientation="responsive">
      <FieldContent>
        <FieldLabel htmlFor="name">Name</FieldLabel>
        <FieldDescription>Provide your full name</FieldDescription>
      </FieldContent>
      <Input id="name" placeholder="Jane Doe" required />
    </Field>
    <FieldSeparator />
    <Field orientation="responsive">
      <FieldContent>
        <FieldLabel htmlFor="bio">Bio</FieldLabel>
        <FieldDescription>Keep it under 100 characters.</FieldDescription>
      </FieldContent>
      <Textarea id="bio" placeholder="Tell us about yourself" className="resize-none" />
    </Field>
  </FieldGroup>
</FieldSet>

Required Field

<RequiredFieldsNote variant="marked" />

<Field required>
  <FieldLabel htmlFor="last-name">Last name</FieldLabel>
  <Input id="last-name" />
</Field>
<Field>
  <FieldLabel htmlFor="middle-name">Middle name</FieldLabel>
  <Input id="middle-name" />
</Field>

Selectable Radio Card

<FieldSet>
  <FieldLabel htmlFor="plan">Choose a Plan</FieldLabel>
  <RadioGroup defaultValue="basic">
    <FieldLabel htmlFor="basic">
      <Field orientation="horizontal" className="rounded-lg bg-input-bg">
        <FieldContent>
          <FieldTitle>Basic</FieldTitle>
          <FieldDescription>Great for getting started.</FieldDescription>
        </FieldContent>
        <RadioGroupItem value="basic" id="basic" />
      </Field>
    </FieldLabel>
    <FieldLabel htmlFor="pro">
      <Field orientation="horizontal" className="rounded-lg bg-input-bg">
        <FieldContent>
          <FieldTitle>Pro</FieldTitle>
          <FieldDescription>For power users and teams.</FieldDescription>
        </FieldContent>
        <RadioGroupItem value="pro" id="pro" />
      </Field>
    </FieldLabel>
  </RadioGroup>
</FieldSet>

Required Fields

required on Field renders an aria-hidden asterisk through FieldLabel and sets aria-required on the control. Both halves come from the one prop, so the visible marker and the announced state cannot drift apart.

Pair it with <RequiredFieldsNote /> above the FieldGroup — variant="marked" for the asterisk legend, variant="all" when every field is required and none is marked. The note is self-hiding, so it renders nothing on a form that turns out to have no required fields.

Anti-pattern: a label reading Middle name (optional). Marking the optional fields instead of the required ones is the rejected convention, and mixing the two leaves an unmarked label meaning nothing at all. It logs a dev warning.

See Decision: Marking Required Fields for the reasoning and the all-required refinement.

Accessibility

• Field required marks the label with an aria-hidden asterisk and sets aria-required on the control
• FieldLabel renders a <label> with htmlFor association to the input
• FieldSet renders a semantic <fieldset> element
• FieldLegend renders a <legend> for the fieldset
• FieldDescription should be linked via aria-describedby on the input
• FieldError should be linked via aria-describedby and the input should have aria-invalid="true"
• Keyboard: Tab moves between fields; Space/Enter activates checkboxes and radios

Gotchas

See Also

• Related Components: Form (React Hook Form integration), Input, Checkbox, Radio Group, Select, Label
• Decisions: Marking Required Fields — the asterisk convention and why "(optional)" labels are rejected
• Tokens: Colors — Destructive color for errors, muted-foreground for descriptions

Last updated: September 9, 2026