Field
Combine labels, controls, and help text to compose accessible form fields and grouped inputs.
"use client"
import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import {
Field,
FieldDescription,
FieldGroup,
FieldLabel,
FieldLegend,
FieldSeparator,
FieldSet,
} from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import {
Select,
SelectContent,
SelectGroup,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select"
import { Textarea } from "@/components/ui/textarea"
const months = [
"01",
"02",
"03",
"04",
"05",
"06",
"07",
"08",
"09",
"10",
"11",
"12",
]
const years = ["2024", "2025", "2026", "2027", "2028", "2029"]
const monthItems = [
{ label: "MM", value: null },
...months.map((month) => ({ label: month, value: month })),
]
const yearItems = [
{ label: "YYYY", value: null },
...years.map((year) => ({ label: year, value: year })),
]
export default function FieldDemo() {
return (
<div className="w-full max-w-md">
<form>
<FieldGroup>
<FieldSet>
<FieldLegend>Payment Method</FieldLegend>
<FieldDescription>
All transactions are secure and encrypted
</FieldDescription>
<FieldGroup>
<Field>
<FieldLabel htmlFor="card-name">Name on Card</FieldLabel>
<Input id="card-name" placeholder="Ada Lovelace" required />
</Field>
<Field>
<FieldLabel htmlFor="card-number">Card Number</FieldLabel>
<Input
id="card-number"
placeholder="1234 5678 9012 3456"
required
/>
<FieldDescription>
Enter your 16-digit card number
</FieldDescription>
</Field>
<FieldGroup className="grid grid-cols-3 gap-4">
<Field>
<FieldLabel htmlFor="exp-month">Month</FieldLabel>
<Select items={monthItems}>
<SelectTrigger id="exp-month" className="w-full">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectGroup>
{months.map((month) => (
<SelectItem key={month} value={month}>
{month}
</SelectItem>
))}
</SelectGroup>
</SelectContent>
</Select>
</Field>
<Field>
<FieldLabel htmlFor="exp-year">Year</FieldLabel>
<Select items={yearItems}>
<SelectTrigger id="exp-year" className="w-full">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectGroup>
{years.map((year) => (
<SelectItem key={year} value={year}>
{year}
</SelectItem>
))}
</SelectGroup>
</SelectContent>
</Select>
</Field>
<Field>
<FieldLabel htmlFor="cvv">CVV</FieldLabel>
<Input id="cvv" placeholder="123" required />
</Field>
</FieldGroup>
</FieldGroup>
</FieldSet>
<FieldSeparator />
<FieldSet>
<FieldLegend>Billing Address</FieldLegend>
<FieldDescription>
The billing address associated with your payment method
</FieldDescription>
<FieldGroup>
<Field orientation="horizontal">
<Checkbox id="same-as-shipping" defaultChecked />
<FieldLabel htmlFor="same-as-shipping" className="font-normal">
Same as shipping address
</FieldLabel>
</Field>
</FieldGroup>
</FieldSet>
<FieldSet>
<FieldGroup>
<Field>
<FieldLabel htmlFor="comments">Comments</FieldLabel>
<Textarea
id="comments"
placeholder="Add any additional comments"
className="resize-none"
/>
</Field>
</FieldGroup>
</FieldSet>
<Field orientation="horizontal">
<Button type="submit">Submit</Button>
<Button variant="outline" type="button">
Cancel
</Button>
</Field>
</FieldGroup>
</form>
</div>
)
}Installation
pnpm dlx shadcn@latest add @kickresume/fieldUsage
import { Field, FieldLabel, FieldDescription, FieldError, FieldGroup, FieldLegend, FieldSeparator, FieldSet, FieldContent, FieldTitle } from "@/components/ui/field"<div className="w-full max-w-md">
<form>
<FieldGroup>
<FieldSet>
<FieldLegend>Payment Method</FieldLegend>
<FieldDescription>
All transactions are secure and encrypted
</FieldDescription>
<FieldGroup>
<Field>
<FieldLabel htmlFor="card-name">Name on Card</FieldLabel>
<Input id="card-name" placeholder="Ada Lovelace" required />
</Field>
<Field>
<FieldLabel htmlFor="card-number">Card Number</FieldLabel>
<Input
id="card-number"
placeholder="1234 5678 9012 3456"
required
/>
<FieldDescription>
Enter your 16-digit card number
</FieldDescription>
</Field>
<FieldGroup className="grid grid-cols-3 gap-4">
<Field>
<FieldLabel htmlFor="exp-month">Month</FieldLabel>
<Select items={monthItems}>
<SelectTrigger id="exp-month" className="w-full">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectGroup>
{months.map((month) => (
<SelectItem key={month} value={month}>
{month}
</SelectItem>
))}
</SelectGroup>
</SelectContent>
</Select>
</Field>
<Field>
<FieldLabel htmlFor="exp-year">Year</FieldLabel>
<Select items={yearItems}>
<SelectTrigger id="exp-year" className="w-full">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectGroup>
{years.map((year) => (
<SelectItem key={year} value={year}>
{year}
</SelectItem>
))}
</SelectGroup>
</SelectContent>
</Select>
</Field>
<Field>
<FieldLabel htmlFor="cvv">CVV</FieldLabel>
<Input id="cvv" placeholder="123" required />
</Field>
</FieldGroup>
</FieldGroup>
</FieldSet>
<FieldSeparator />
<FieldSet>
<FieldLegend>Billing Address</FieldLegend>
<FieldDescription>
The billing address associated with your payment method
</FieldDescription>
<FieldGroup>
<Field orientation="horizontal">
<Checkbox id="same-as-shipping" defaultChecked />
<FieldLabel htmlFor="same-as-shipping" className="font-normal">
Same as shipping address
</FieldLabel>
</Field>
</FieldGroup>
</FieldSet>
<FieldSet>
<FieldGroup>
<Field>
<FieldLabel htmlFor="comments">Comments</FieldLabel>
<Textarea
id="comments"
placeholder="Add any additional comments"
className="resize-none"
/>
</Field>
</FieldGroup>
</FieldSet>
<Field orientation="horizontal">
<Button type="submit">Submit</Button>
<Button variant="outline" type="button">
Cancel
</Button>
</Field>
</FieldGroup>
</form>
</div>Composition
Field
A single control with label, helper text, and validation.
Field
├── FieldLabel
├── Input / Textarea / Switch / Select
├── FieldDescription
└── FieldErrorFieldGroup
Related fields in one group. Use FieldSeparator between sections when needed.
FieldGroup
├── Field
│ ├── FieldLabel
│ ├── Input / Textarea / Switch / Select
│ ├── FieldDescription
│ └── FieldError
├── FieldSeparator
└── Field
├── FieldLabel
└── Input / Textarea / Switch / SelectFieldSet
Semantic grouping with a legend and description, usually containing a FieldGroup.
FieldSet
├── FieldLegend
├── FieldDescription
└── FieldGroup
├── Field
│ ├── FieldLabel
│ ├── Input / Textarea / Switch / Select
│ ├── FieldDescription
│ └── FieldError
└── Field
├── FieldLabel
└── Input / Textarea / Switch / SelectAnatomy
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>Fieldis the core wrapper for a single field.FieldContentis a flex column that groups label and description. Not required if you have no description.- Wrap related fields with
FieldGroup, and useFieldSetwithFieldLegendfor semantic grouping.
Form
See the Form documentation for building forms with the Field component and React Hook Form, Tanstack Form, or Formisch.
Examples
Input
"use client"
import {
Field,
FieldDescription,
FieldGroup,
FieldLabel,
FieldSet,
} from "@/components/ui/field"
import { Input } from "@/components/ui/input"
export default function FieldInput() {
return (
<FieldSet className="w-full max-w-xs">
<FieldGroup>
<Field>
<FieldLabel htmlFor="username">Username</FieldLabel>
<Input id="username" type="text" placeholder="Max Leiter" />
<FieldDescription>
Choose a unique username for your account.
</FieldDescription>
</Field>
<Field>
<FieldLabel htmlFor="password">Password</FieldLabel>
<FieldDescription>
Must be at least 8 characters long.
</FieldDescription>
<Input id="password" type="password" placeholder="••••••••" />
</Field>
</FieldGroup>
</FieldSet>
)
}Textarea
"use client"
import {
Field,
FieldDescription,
FieldGroup,
FieldLabel,
FieldSet,
} from "@/components/ui/field"
import { Textarea } from "@/components/ui/textarea"
export default function FieldTextarea() {
return (
<FieldSet className="w-full max-w-xs">
<FieldGroup>
<Field>
<FieldLabel htmlFor="feedback">Feedback</FieldLabel>
<Textarea
id="feedback"
placeholder="Your feedback helps us improve..."
rows={4}
/>
<FieldDescription>
Share your thoughts about our service.
</FieldDescription>
</Field>
</FieldGroup>
</FieldSet>
)
}Select
"use client"
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import {
Select,
SelectContent,
SelectGroup,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select"
const departments = [
{ label: "Engineering", value: "engineering" },
{ label: "Design", value: "design" },
{ label: "Marketing", value: "marketing" },
{ label: "Sales", value: "sales" },
{ label: "Customer Support", value: "support" },
{ label: "Human Resources", value: "hr" },
{ label: "Finance", value: "finance" },
{ label: "Operations", value: "operations" },
]
const departmentItems = [
{ label: "Choose department", value: null },
...departments,
]
export default function FieldSelect() {
return (
<Field className="w-full max-w-xs">
<FieldLabel htmlFor="department">Department</FieldLabel>
<Select items={departmentItems}>
<SelectTrigger id="department" className="w-full">
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectGroup>
{departments.map((item) => (
<SelectItem key={item.value} value={item.value}>
{item.label}
</SelectItem>
))}
</SelectGroup>
</SelectContent>
</Select>
<FieldDescription>
Select your department or area of work.
</FieldDescription>
</Field>
)
}Slider
"use client"
import * as React from "react"
import { Field, FieldDescription, FieldTitle } from "@/components/ui/field"
import { Slider } from "@/components/ui/slider"
export default function FieldSlider() {
const [value, setValue] = React.useState([200, 800])
return (
<Field className="w-full max-w-xs">
<FieldTitle>Price Range</FieldTitle>
<FieldDescription>
Set your budget range ($
<span className="font-medium tabular-nums">{value[0]}</span> -{" "}
<span className="font-medium tabular-nums">{value[1]}</span>).
</FieldDescription>
<Slider
value={value}
getAriaLabel={(index) =>
index === 0 ? "Minimum price" : "Maximum price"
}
onValueChange={(value) => setValue(value as number[])}
max={1000}
min={0}
step={10}
className="mt-2 w-full"
aria-label="Price Range"
/>
</Field>
)
}Fieldset
"use client"
import {
Field,
FieldDescription,
FieldGroup,
FieldLabel,
FieldLegend,
FieldSet,
} from "@/components/ui/field"
import { Input } from "@/components/ui/input"
export default function FieldFieldset() {
return (
<FieldSet className="w-full max-w-sm">
<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" type="text" placeholder="123 Main St" />
</Field>
<FieldGroup className="grid grid-cols-2 gap-4">
<Field>
<FieldLabel htmlFor="city">City</FieldLabel>
<Input id="city" type="text" placeholder="New York" />
</Field>
<Field>
<FieldLabel htmlFor="zip">Postal Code</FieldLabel>
<Input id="zip" type="text" placeholder="90502" />
</Field>
</FieldGroup>
</FieldGroup>
</FieldSet>
)
}Checkbox
"use client"
import { Checkbox } from "@/components/ui/checkbox"
import {
Field,
FieldContent,
FieldDescription,
FieldGroup,
FieldLabel,
FieldLegend,
FieldSeparator,
FieldSet,
} from "@/components/ui/field"
export default function FieldCheckbox() {
return (
<FieldGroup className="w-full max-w-xs">
<FieldSet>
<FieldLegend variant="label">
Show these items on the desktop
</FieldLegend>
<FieldDescription>
Select the items you want to show on the desktop.
</FieldDescription>
<FieldGroup className="gap-3">
<Field orientation="horizontal">
<Checkbox id="hard-disks" />
<FieldLabel htmlFor="hard-disks" className="font-normal">
Hard disks
</FieldLabel>
</Field>
<Field orientation="horizontal">
<Checkbox id="external-disks" />
<FieldLabel htmlFor="external-disks" className="font-normal">
External disks
</FieldLabel>
</Field>
<Field orientation="horizontal">
<Checkbox id="cds-dvds" />
<FieldLabel htmlFor="cds-dvds" className="font-normal">
CDs, DVDs, and iPods
</FieldLabel>
</Field>
<Field orientation="horizontal">
<Checkbox id="connected-servers" />
<FieldLabel htmlFor="connected-servers" className="font-normal">
Connected servers
</FieldLabel>
</Field>
</FieldGroup>
</FieldSet>
<FieldSeparator />
<Field orientation="horizontal">
<Checkbox id="sync-folders" defaultChecked />
<FieldContent>
<FieldLabel htmlFor="sync-folders">
Sync Desktop & Documents folders
</FieldLabel>
<FieldDescription>
Your Desktop & Documents folders are being synced with iCloud Drive.
You can access them from other devices.
</FieldDescription>
</FieldContent>
</Field>
</FieldGroup>
)
}Radio
"use client"
import {
Field,
FieldDescription,
FieldLabel,
FieldLegend,
FieldSet,
} from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
export default function FieldRadio() {
return (
<FieldSet className="w-full max-w-xs">
<FieldLegend id="field-radio-plan-legend" variant="label">
Subscription Plan
</FieldLegend>
<FieldDescription>
Yearly and lifetime plans offer significant savings.
</FieldDescription>
<RadioGroup
aria-labelledby="field-radio-plan-legend"
defaultValue="monthly"
>
<Field orientation="horizontal" className="gap-2.5">
<RadioGroupItem value="monthly" id="plan-monthly" />
<FieldLabel htmlFor="plan-monthly" className="font-normal">
Monthly ($9.99/month)
</FieldLabel>
</Field>
<Field orientation="horizontal" className="gap-2.5">
<RadioGroupItem value="yearly" id="plan-yearly" />
<FieldLabel htmlFor="plan-yearly" className="font-normal">
Yearly ($99.99/year)
</FieldLabel>
</Field>
<Field orientation="horizontal" className="gap-2.5">
<RadioGroupItem value="lifetime" id="plan-lifetime" />
<FieldLabel htmlFor="plan-lifetime" className="font-normal">
Lifetime ($299.99)
</FieldLabel>
</Field>
</RadioGroup>
</FieldSet>
)
}Switch
"use client"
import { Field, FieldLabel } from "@/components/ui/field"
import { Switch } from "@/components/ui/switch"
export default function FieldSwitch() {
return (
<Field orientation="horizontal" className="w-fit">
<FieldLabel htmlFor="2fa">Multi-factor authentication</FieldLabel>
<Switch id="2fa" />
</Field>
)
}Choice Card
Wrap Field components inside FieldLabel to create selectable field groups. This works with RadioItem, Checkbox and Switch components.
"use client"
import {
Field,
FieldContent,
FieldDescription,
FieldGroup,
FieldLabel,
FieldLegend,
FieldSet,
FieldTitle,
} from "@/components/ui/field"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
export default function FieldChoiceCard() {
return (
<FieldGroup className="w-full max-w-xs">
<FieldSet>
<FieldLegend id="compute-environment-legend" variant="label">
Compute Environment
</FieldLegend>
<FieldDescription>
Select the compute environment for your cluster.
</FieldDescription>
<RadioGroup
aria-labelledby="compute-environment-legend"
defaultValue="kubernetes"
>
<FieldLabel htmlFor="kubernetes-r2h">
<Field orientation="horizontal">
<FieldContent>
<FieldTitle>Kubernetes</FieldTitle>
<FieldDescription>
Run GPU workloads on a K8s cluster.
</FieldDescription>
</FieldContent>
<RadioGroupItem value="kubernetes" id="kubernetes-r2h" />
</Field>
</FieldLabel>
<FieldLabel htmlFor="vm-z4k">
<Field orientation="horizontal">
<FieldContent>
<FieldTitle>Virtual Machine</FieldTitle>
<FieldDescription>
Access a cluster to run GPU workloads.
</FieldDescription>
</FieldContent>
<RadioGroupItem value="vm" id="vm-z4k" />
</Field>
</FieldLabel>
</RadioGroup>
</FieldSet>
</FieldGroup>
)
}Field Group
Stack Field components with FieldGroup. Add FieldSeparator to divide them.
"use client"
import { Checkbox } from "@/components/ui/checkbox"
import {
Field,
FieldDescription,
FieldGroup,
FieldLabel,
FieldLegend,
FieldSeparator,
FieldSet,
} from "@/components/ui/field"
export default function FieldGroupExample() {
return (
<FieldGroup className="w-full max-w-xs">
<FieldSet>
<FieldLegend variant="label">Responses</FieldLegend>
<FieldDescription>
Get notified when the AI assistant responds to requests that take
time, like research or image generation.
</FieldDescription>
<FieldGroup data-slot="checkbox-group">
<Field orientation="horizontal">
<Checkbox id="push" defaultChecked disabled />
<FieldLabel htmlFor="push" className="font-normal">
Push notifications
</FieldLabel>
</Field>
</FieldGroup>
</FieldSet>
<FieldSeparator />
<FieldSet>
<FieldLegend variant="label">Tasks</FieldLegend>
<FieldDescription>
Get notified when tasks you've created have updates.{" "}
<a href="#">Manage tasks</a>
</FieldDescription>
<FieldGroup data-slot="checkbox-group">
<Field orientation="horizontal">
<Checkbox id="push-tasks" />
<FieldLabel htmlFor="push-tasks" className="font-normal">
Push notifications
</FieldLabel>
</Field>
<Field orientation="horizontal">
<Checkbox id="email-tasks" />
<FieldLabel htmlFor="email-tasks" className="font-normal">
Email notifications
</FieldLabel>
</Field>
</FieldGroup>
</FieldSet>
</FieldGroup>
)
}Responsive Layout
- Vertical fields: Default orientation stacks label, control, and helper text—ideal for mobile-first layouts.
- Horizontal fields: Set
orientation="horizontal"onFieldto align the label and control side-by-side. Pair withFieldContentto keep descriptions aligned. - Responsive fields: Set
orientation="responsive"for automatic column layouts inside container-aware parents. Apply@container/field-groupclasses onFieldGroupto switch orientations at specific breakpoints.
"use client"
import { Button } from "@/components/ui/button"
import {
Field,
FieldContent,
FieldDescription,
FieldGroup,
FieldLabel,
FieldLegend,
FieldSet,
} from "@/components/ui/field"
import { Input } from "@/components/ui/input"
export default function FieldResponsive() {
return (
<div className="w-full max-w-lg">
<form>
<FieldSet>
<FieldLegend>Profile</FieldLegend>
<FieldDescription>Fill in your profile information.</FieldDescription>
<FieldGroup>
<Field orientation="responsive">
<FieldContent>
<FieldLabel htmlFor="name">Name</FieldLabel>
<FieldDescription>
Provide your full name for identification
</FieldDescription>
</FieldContent>
<Input id="name" placeholder="Ada Lovelace" required />
</Field>
<Field orientation="responsive">
<Button type="submit">Submit</Button>
<Button type="button" variant="outline">
Cancel
</Button>
</Field>
</FieldGroup>
</FieldSet>
</form>
</div>
)
}Validation and Errors
- Add
data-invalidtoFieldto switch the entire block into an error state. - Add
aria-invalidon the input itself for assistive technologies. - Render
FieldErrorimmediately after the control or insideFieldContentto 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>Accessibility
FieldSetandFieldLegendkeep related controls grouped for keyboard and assistive tech users.Fieldoutputsrole="group"so nested controls inherit labeling fromFieldLabelandFieldLegendwhen combined.- Apply
FieldSeparatorsparingly to ensure screen readers encounter clear section boundaries.
API Reference
FieldSet
Container that renders a semantic fieldset with spacing presets.
| Prop | Type | Default |
|---|---|---|
className | string |
<FieldSet>
<FieldLegend>Delivery</FieldLegend>
<FieldGroup>{/* Fields */}</FieldGroup>
</FieldSet>FieldLegend
Legend element for a FieldSet. Switch to the label variant to align with label sizing.
| Prop | Type | Default |
|---|---|---|
variant | "legend" | "label" | "legend" |
className | string |
<FieldLegend variant="label">Notification Preferences</FieldLegend>The FieldLegend has two variants: legend and label. The label variant applies label sizing and alignment. Handy if you have nested FieldSet.
FieldGroup
Layout wrapper that stacks Field components and enables container queries for responsive orientations.
| Prop | Type | Default |
|---|---|---|
className | string |
<FieldGroup className="@container/field-group flex flex-col gap-6">
<Field>{/* ... */}</Field>
<Field>{/* ... */}</Field>
</FieldGroup>Field
The core wrapper for a single field. Provides orientation control, invalid state styling, and spacing.
| Prop | Type | Default |
|---|---|---|
orientation | "vertical" | "horizontal" | "responsive" | "vertical" |
className | string | |
data-invalid | boolean |
<Field orientation="horizontal">
<FieldLabel htmlFor="remember">Remember me</FieldLabel>
<Switch id="remember" />
</Field>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 |
|---|---|---|
className | string |
<Field>
<Checkbox id="notifications" />
<FieldContent>
<FieldLabel htmlFor="notifications">Notifications</FieldLabel>
<FieldDescription>Email, SMS, and push options.</FieldDescription>
</FieldContent>
</Field>FieldLabel
Label styled for both direct inputs and nested Field children.
| Prop | Type | Default |
|---|---|---|
className | string |
<FieldLabel htmlFor="email">Email</FieldLabel>FieldTitle
Renders a title with label styling inside FieldContent.
| Prop | Type | Default |
|---|---|---|
className | string |
<FieldContent>
<FieldTitle>Enable Touch ID</FieldTitle>
<FieldDescription>Unlock your device faster.</FieldDescription>
</FieldContent>FieldDescription
Helper text slot that automatically balances long lines in horizontal layouts.
| Prop | Type | Default |
|---|---|---|
className | string |
<FieldDescription>We never share your email with anyone.</FieldDescription>FieldSeparator
Visual divider to separate sections inside a FieldGroup. Accepts optional inline content.
| Prop | Type | Default |
|---|---|---|
className | string |
<FieldSeparator>Or continue with</FieldSeparator>FieldError
Accessible error container that accepts children or an errors array (e.g., from react-hook-form).
| Prop | Type | Default |
|---|---|---|
errors | Array<{ message?: string } | undefined> | |
className | string |
<FieldError errors={errors.username} />When the errors array contains multiple messages, the component renders a list automatically.