field

Make accessible forms with Field components.

Philosophy

Fields are the structural glue between form controls and their metadata — labels, descriptions, error messages. Rather than baking this structure into every input component, Field composes around any control. This means the same label/error pattern works for Input, Select, Textarea, or your custom components.

Installation

npx @gentleduck/cli add field

npx @gentleduck/cli add field

Usage

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
  FieldTitle,
} from "@/components/ui/field"

import {
  Field,
  FieldContent,
  FieldDescription,
  FieldError,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSeparator,
  FieldSet,
  FieldTitle,
} from "@/components/ui/field"

<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>

<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>

Anatomy

The Field family is designed for composing accessible forms. A typical field is structured as follows:

<Field>
  <FieldLabel htmlFor="input-id">Label</FieldLabel>
  {/* Input, Select, Switch, etc. */}
  <FieldDescription>Optional helper text.</FieldDescription>
  <FieldError>Validation message.</FieldError>
</Field>

<Field>
  <FieldLabel htmlFor="input-id">Label</FieldLabel>
  {/* Input, Select, Switch, etc. */}
  <FieldDescription>Optional helper text.</FieldDescription>
  <FieldError>Validation message.</FieldError>
</Field>

Field is the core wrapper for a single field.
FieldContent is a flex column that groups label and description. Not required if you have no description.
Wrap related fields with FieldGroup, and use FieldSet with FieldLegend for semantic grouping.

Examples

Input

Textarea

Select

Slider

Fieldset

Checkbox

Radio

Switch

Choice Card

Wrap Field components inside FieldLabel to create selectable field groups. This works with RadioItem, Checkbox and Switch components.

Field Group

Stack Field components with FieldGroup. Add FieldSeparator to divide them.

Responsive Layout

Vertical fields: Default orientation stacks label, control, and helper text — ideal for mobile-first layouts.
Horizontal fields: Set orientation="horizontal" on Field to align the label and control side-by-side. Pair with FieldContent to keep descriptions aligned.
Responsive fields: Set orientation="responsive" for automatic column layouts inside container-aware parents. Apply @container/field-group classes on FieldGroup to switch orientations at specific breakpoints.

Validation and Errors

Add data-invalid to Field to switch the entire block into an error state.
Add aria-invalid on the input itself for assistive technologies.
Render FieldError immediately after the control or inside FieldContent to keep error messages aligned with the field.

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

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

Accessibility

FieldSet and FieldLegend keep related controls grouped for keyboard and assistive tech users.
Field outputs role="group" so nested controls inherit labeling from FieldLabel and FieldLegend when combined.
Apply FieldSeparator sparingly to ensure screen readers encounter clear section boundaries.

Component Composition

Loading diagram...

API Reference

FieldSet

Container that renders a semantic fieldset with spacing presets.

Prop	Type	Default	Description
`dir`	`'ltr' \| 'rtl'`	--	Text direction override. Resolved via `useDirection` (`dir` prop -> `DirectionProvider` -> `'ltr'`).
`className`	`string`	`--`	Additional CSS classes
`children`	`React.ReactNode`	`--`	Fieldset content
`...props`	`React.HTMLProps<HTMLFieldSetElement>`	--	Additional props to spread to the fieldset element

FieldLegend

Legend element for a FieldSet. Switch to the label variant to align with label sizing.

Prop	Type	Default	Description
`variant`	`'legend' \| 'label'`	`'legend'`	Visual variant controlling text size
`className`	`string`	`--`	Additional CSS classes
`...props`	`React.HTMLProps<HTMLLegendElement>`	--	Additional props to spread to the legend element

FieldGroup

Layout wrapper that stacks Field components and enables container queries for responsive orientations.

Prop	Type	Default	Description
`className`	`string`	`--`	Additional CSS classes
`children`	`React.ReactNode`	`--`	Field components
`...props`	`React.HTMLProps<HTMLDivElement>`	--	Additional props to spread to the content div

Field

The core wrapper for a single field. Provides orientation control, invalid state styling, and spacing.

Prop	Type	Default	Description
`orientation`	`'vertical' \| 'horizontal' \| 'responsive'`	`'vertical'`	Layout orientation of the field
`className`	`string`	`--`	Additional CSS classes
`children`	`React.ReactNode`	`--`	Field content
`...props`	`React.HTMLProps<HTMLDivElement>`	--	Additional props to spread to the content div; set `data-invalid` to render in an error state

FieldContent

Flex column that groups control and descriptions when the label sits beside the control. Not required if you have no description.

Prop	Type	Default	Description
`className`	`string`	`--`	Additional CSS classes
`children`	`React.ReactNode`	`--`	Label, description, and control content
`...props`	`React.HTMLProps<HTMLDivElement>`	--	Additional props to spread to the content div

FieldLabel

Label styled for both direct inputs and nested Field children.

Prop	Type	Default	Description
`className`	`string`	`--`	Additional CSS classes
`children`	`React.ReactNode`	`--`	Label text or nested field content
`...props`	`React.ComponentPropsWithoutRef<typeof Label>`	--	Additional props inherited from `Label`.

FieldTitle

Renders a title with label styling inside FieldContent.

Prop	Type	Default	Description
`className`	`string`	`--`	Additional CSS classes
`children`	`React.ReactNode`	`--`	Title text
`...props`	`React.HTMLProps<HTMLDivElement>`	--	Additional props to spread to the content div

FieldDescription

Helper text slot that automatically balances long lines in horizontal layouts.

Prop	Type	Default	Description
`className`	`string`	`--`	Additional CSS classes
`children`	`React.ReactNode`	`--`	Description text
`...props`	`React.HTMLProps<HTMLParagraphElement>`	--	Additional props to spread to the p element

FieldSeparator

Visual divider to separate sections inside a FieldGroup. Accepts optional inline content.

Prop	Type	Default	Description
`children`	`React.ReactNode`	`--`	Optional inline content displayed over the separator
`className`	`string`	`--`	Additional CSS classes
`...props`	`React.HTMLProps<HTMLDivElement>`	--	Additional props to spread to the content div

FieldError

Accessible error container that accepts children or an errors array (e.g., from react-hook-form).

Prop	Type	Default	Description
`errors`	`Array<{ message?: string } \| undefined>`	`--`	Array of error objects from a form library
`children`	`React.ReactNode`	`--`	Custom error content (takes precedence over `errors`)
`className`	`string`	`--`	Additional CSS classes
`...props`	`React.HTMLProps<HTMLDivElement>`	--	Additional props to spread to the content div

When the errors array contains multiple messages, the component renders a list automatically.

FieldError also accepts issues produced by any validator that implements Standard Schema, including Zod, Valibot, and ArkType. Pass the issues array from the schema result directly to render a unified error list across libraries.

RTL Support

Direction is resolved through the shared primitives direction module. Use a local dir="rtl" override when the component exposes it, or set DirectionProvider at app/root level for global RTL/LTR behavior.

Empty Navigation Menu

On This Page

Edit this page on GitHub Scroll to top Scroll to bottom