Field

Installation

npx shadcn@latest add @kanpeki/field

Anatomy

import { Field } from "~/components/ui/field";

<Field.Set>
  <Field.Legend>Profile</Field.Legend>
  <Field.Group>
    <Field.Root>
      <Field.Label>Label</Field.Label>
      {/* Input, Select, Switch, etc. */}
      <Field.Description>Optional helper text.</Field.Description>
      <Field.Error>Validation message.</Field.Error>
    </Field.Root>
  </Field.Group>
</Field.Set>;

Structure

• <Field.Root> is the core wrapper for a single field.
• <Field.Content> is a flex column that groups label and description. Not required if you have no description.
• Wrap related fields with <Field.Group>, and use <Field.Set> with <Field.Legend> for semantic grouping.

Form

See the Forms documentation for building forms with the Field component and TanStack Form or React Hook Form.

Examples

Input

Use <Field.Root> with the render prop to compose with <TextField> for automatic accessibility wiring.

Without TextField

You can use <Field.Root> with <Input> directly, but you must provide htmlFor on the label and id on the input manually.

<Field.Root>
  <Field.Label htmlFor="email">Email</Field.Label>
  <Input id="email" placeholder="Email" />
</Field.Root>

Textarea

Select

Checkbox

Radio Group

Switch

Fieldset

Use <Field.Set> and <Field.Legend> for semantic grouping of related fields.

Field Group

Stack <Field.Root> components with <Field.Group>. Add <Field.Separator> 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.Root> to align the label and control side-by-side. Pair with <Field.Content> to keep descriptions aligned.
• Responsive fields: Set orientation="responsive" for automatic column layouts inside container-aware parents.

Validation and Errors

When using <Field.Root> with React Aria field components like <TextField>, <NumberField>, <DateField>, <ColorField>, or <Select>, pass isInvalid to the field component—it handles the invalid state automatically:

<Field.Root render={<TextField isInvalid />}>
  <Field.Label>Email</Field.Label>
  <Input />
  <Field.Error>Enter a valid email address.</Field.Error>
</Field.Root>

If you're not using React Aria field components, you must handle validation state manually:

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

<Field.Root data-invalid>
  <Field.Label>Email</Field.Label>
  <Input aria-invalid />
  <Field.Error>Enter a valid email address.</Field.Error>
</Field.Root>

Accessibility

• <Field.Set> and <Field.Legend> keep related controls grouped for keyboard and assistive tech users.
• <Field.Root> outputs role="group" so nested controls inherit labeling from <Field.Label> and <Field.Legend> when combined.
• When using <Field.Root> with render={<TextField />}, React Aria automatically associates label, description, and error elements via aria-labelledby and aria-describedby.

API Reference

Field.Set

Container that renders a semantic fieldset with spacing presets.

Field.Legend

Legend element for a <Field.Set>. Switch to the label variant to align with label sizing.

Field.Group

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

Field.Root

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

Use the render prop to compose with React Aria components like <TextField>:

<Field.Root render={<TextField type="email" isRequired />}>
  <Field.Label>Email</Field.Label>
  <Input />
</Field.Root>

Field.Content

Flex column that groups control and descriptions when the label sits beside the control.

Field.Label

Label styled for both direct inputs and nested Field.Root children.

Field.Title

Renders a title with label styling inside <Field.Content>.

Field.Description

Helper text slot. Uses React Aria's <Text> component with slot="description".

Field.Separator

Visual divider to separate sections inside a <Field.Group>. Accepts optional inline content.

<Field.Separator>Or continue with</Field.Separator>

Field.Error

Accessible error container that accepts children or an errors array.

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

<Field.Error
  errors={[{ message: "Required" }, { message: "Invalid format" }]}
/>