- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
"use client";
import { cva, type VariantProps } from "class-variance-authority";
import { useMemo } from "react";
import { Label } from "@/components/ui/label";
import { Separator } from "@/components/ui/separator";
import { cn } from "@/lib/utils";
function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
return (
<fieldset
className={cn(
"flex flex-col gap-4 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
className
)}
data-slot="field-set"
{...props}
/>
);
}
function FieldLegend({
className,
variant = "legend",
...props
}: React.ComponentProps<"legend"> & { variant?: "legend" | "label" }) {
return (
<legend
className={cn(
"mb-1.5 font-medium data-[variant=label]:text-sm data-[variant=legend]:text-base",
className
)}
data-slot="field-legend"
data-variant={variant}
{...props}
/>
);
}
function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"group/field-group @container/field-group flex w-full flex-col gap-5 data-[slot=checkbox-group]:gap-3 *:data-[slot=field-group]:gap-4",
className
)}
data-slot="field-group"
{...props}
/>
);
}
const fieldVariants = cva(
"group/field data-[invalid=true]:text-destructive flex w-full gap-2",
{
defaultVariants: {
orientation: "vertical",
},
variants: {
orientation: {
horizontal:
"flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
responsive:
"flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
vertical: "flex-col *:w-full [&>.sr-only]:w-auto",
},
},
}
);
function Field({
className,
orientation = "vertical",
...props
}: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
return (
<div
className={cn(fieldVariants({ orientation }), className)}
data-orientation={orientation}
data-slot="field"
role="group"
{...props}
/>
);
}
function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"group/field-content flex flex-1 flex-col gap-0.5 leading-snug",
className
)}
data-slot="field-content"
{...props}
/>
);
}
function FieldLabel({
className,
...props
}: React.ComponentProps<typeof Label>) {
return (
<Label
className={cn(
"group/field-label peer/field-label has-data-checked:border-primary/30 has-data-checked:bg-primary/5 has-[>[data-slot=field]]:not-has-[:disabled,[data-disabled]]:hover:bg-muted/50 has-[>[data-slot=field]]:has-[:focus-visible]:border-ring has-[>[data-slot=field]]:has-[:focus-visible]:ring-ring/50 dark:has-data-checked:border-primary/20 dark:has-data-checked:bg-primary/10 flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50 has-[>[data-slot=field]]:rounded-lg has-[>[data-slot=field]]:border has-[>[data-slot=field]]:has-[:focus-visible]:ring-3 *:data-[slot=field]:p-2.5",
"has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col",
className
)}
data-slot="field-label"
{...props}
/>
);
}
function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"flex w-fit items-center gap-2 text-sm font-medium group-data-[disabled=true]/field:opacity-50",
className
)}
data-slot="field-label"
{...props}
/>
);
}
function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
return (
<p
className={cn(
"text-muted-foreground text-left text-sm leading-normal font-normal group-has-data-horizontal/field:text-balance [[data-variant=legend]+&]:-mt-1.5",
"last:mt-0 nth-last-2:-mt-1",
"[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4",
className
)}
data-slot="field-description"
{...props}
/>
);
}
function FieldSeparator({
children,
className,
...props
}: React.ComponentProps<"div"> & {
children?: React.ReactNode;
}) {
return (
<div
className={cn(
"relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2",
className
)}
data-content={!!children}
data-slot="field-separator"
{...props}
>
<Separator className="absolute inset-0 top-1/2" />
{children && (
<span
className="bg-background text-muted-foreground relative mx-auto block w-fit px-2"
data-slot="field-separator-content"
>
{children}
</span>
)}
</div>
);
}
function FieldError({
className,
children,
errors,
...props
}: React.ComponentProps<"div"> & {
errors?: Array<{ message?: string } | undefined>;
}) {
const content = useMemo(() => {
if (children) {
return children;
}
if (!errors?.length) {
return null;
}
const uniqueErrors = [
...new Map(errors.map((error) => [error?.message, error])).values(),
];
if (uniqueErrors?.length === 1) {
return uniqueErrors[0]?.message;
}
return (
<ul className="ml-4 flex list-disc flex-col gap-1">
{uniqueErrors.map(
(error, index) =>
error?.message && <li key={index}>{error.message}</li>
)}
</ul>
);
}, [children, errors]);
if (!content) {
return null;
}
return (
<div
className={cn("text-destructive text-sm font-normal", className)}
data-slot="field-error"
role="alert"
{...props}
>
{content}
</div>
);
}
export {
Field,
FieldContent,
FieldDescription,
FieldError,
FieldGroup,
FieldLabel,
FieldLegend,
FieldSeparator,
FieldSet,
FieldTitle,
};Field wraps a form control with its label, description, and error message. It handles vertical and horizontal orientation, works with FieldSet and FieldGroup for multi-field forms, and surfaces validation state through data-invalid on the wrapper.
Installation
$ bunx --bun frakment add field$ npx frakment add field$ pnpm dlx frakment add field$ yarn dlx frakment add field
The CLI installs the registry dependencies: label and separator.
Install the following dependencies:
$ bun add class-variance-authority$ npm install class-variance-authority$ pnpm add class-variance-authority$ yarn add class-variance-authority
Copy and paste the following code into your project.
"use client";
import { cva, type VariantProps } from "class-variance-authority";
import { useMemo } from "react";
import { Label } from "@/components/ui/label";
import { Separator } from "@/components/ui/separator";
import { cn } from "@/lib/utils";
function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
return (
<fieldset
className={cn(
"flex flex-col gap-4 has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
className
)}
data-slot="field-set"
{...props}
/>
);
}
function FieldLegend({
className,
variant = "legend",
...props
}: React.ComponentProps<"legend"> & { variant?: "legend" | "label" }) {
return (
<legend
className={cn(
"mb-1.5 font-medium data-[variant=label]:text-sm data-[variant=legend]:text-base",
className
)}
data-slot="field-legend"
data-variant={variant}
{...props}
/>
);
}
function FieldGroup({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"group/field-group @container/field-group flex w-full flex-col gap-5 data-[slot=checkbox-group]:gap-3 *:data-[slot=field-group]:gap-4",
className
)}
data-slot="field-group"
{...props}
/>
);
}
const fieldVariants = cva(
"group/field data-[invalid=true]:text-destructive flex w-full gap-2",
{
defaultVariants: {
orientation: "vertical",
},
variants: {
orientation: {
horizontal:
"flex-row items-center has-[>[data-slot=field-content]]:items-start *:data-[slot=field-label]:flex-auto has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
responsive:
"flex-col *:w-full @md/field-group:flex-row @md/field-group:items-center @md/field-group:*:w-auto @md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:*:data-[slot=field-label]:flex-auto [&>.sr-only]:w-auto @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px",
vertical: "flex-col *:w-full [&>.sr-only]:w-auto",
},
},
}
);
function Field({
className,
orientation = "vertical",
...props
}: React.ComponentProps<"div"> & VariantProps<typeof fieldVariants>) {
return (
<div
className={cn(fieldVariants({ orientation }), className)}
data-orientation={orientation}
data-slot="field"
role="group"
{...props}
/>
);
}
function FieldContent({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"group/field-content flex flex-1 flex-col gap-0.5 leading-snug",
className
)}
data-slot="field-content"
{...props}
/>
);
}
function FieldLabel({
className,
...props
}: React.ComponentProps<typeof Label>) {
return (
<Label
className={cn(
"group/field-label peer/field-label has-data-checked:border-primary/30 has-data-checked:bg-primary/5 has-[>[data-slot=field]]:not-has-[:disabled,[data-disabled]]:hover:bg-muted/50 has-[>[data-slot=field]]:has-[:focus-visible]:border-ring has-[>[data-slot=field]]:has-[:focus-visible]:ring-ring/50 dark:has-data-checked:border-primary/20 dark:has-data-checked:bg-primary/10 flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50 has-[>[data-slot=field]]:rounded-lg has-[>[data-slot=field]]:border has-[>[data-slot=field]]:has-[:focus-visible]:ring-3 *:data-[slot=field]:p-2.5",
"has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col",
className
)}
data-slot="field-label"
{...props}
/>
);
}
function FieldTitle({ className, ...props }: React.ComponentProps<"div">) {
return (
<div
className={cn(
"flex w-fit items-center gap-2 text-sm font-medium group-data-[disabled=true]/field:opacity-50",
className
)}
data-slot="field-label"
{...props}
/>
);
}
function FieldDescription({ className, ...props }: React.ComponentProps<"p">) {
return (
<p
className={cn(
"text-muted-foreground text-left text-sm leading-normal font-normal group-has-data-horizontal/field:text-balance [[data-variant=legend]+&]:-mt-1.5",
"last:mt-0 nth-last-2:-mt-1",
"[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4",
className
)}
data-slot="field-description"
{...props}
/>
);
}
function FieldSeparator({
children,
className,
...props
}: React.ComponentProps<"div"> & {
children?: React.ReactNode;
}) {
return (
<div
className={cn(
"relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2",
className
)}
data-content={!!children}
data-slot="field-separator"
{...props}
>
<Separator className="absolute inset-0 top-1/2" />
{children && (
<span
className="bg-background text-muted-foreground relative mx-auto block w-fit px-2"
data-slot="field-separator-content"
>
{children}
</span>
)}
</div>
);
}
function FieldError({
className,
children,
errors,
...props
}: React.ComponentProps<"div"> & {
errors?: Array<{ message?: string } | undefined>;
}) {
const content = useMemo(() => {
if (children) {
return children;
}
if (!errors?.length) {
return null;
}
const uniqueErrors = [
...new Map(errors.map((error) => [error?.message, error])).values(),
];
if (uniqueErrors?.length === 1) {
return uniqueErrors[0]?.message;
}
return (
<ul className="ml-4 flex list-disc flex-col gap-1">
{uniqueErrors.map(
(error, index) =>
error?.message && <li key={index}>{error.message}</li>
)}
</ul>
);
}, [children, errors]);
if (!content) {
return null;
}
return (
<div
className={cn("text-destructive text-sm font-normal", className)}
data-slot="field-error"
role="alert"
{...props}
>
{content}
</div>
);
}
export {
Field,
FieldContent,
FieldDescription,
FieldError,
FieldGroup,
FieldLabel,
FieldLegend,
FieldSeparator,
FieldSet,
FieldTitle,
};Update the import paths to match your project setup.
Usage
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";
<DocsBaseSwitcher base="web" component="field" className="mb-6" /><Field>
<FieldLabel htmlFor="email">Email</FieldLabel>
<Input id="email" type="email" placeholder="name@example.com" />
<FieldDescription>We'll send updates to this address.</FieldDescription>
</Field>Composition
Field
├── FieldLabel
├── FieldDescription
├── FieldError
└── FieldContentExamples
Input
"use client";
import {
Field,
FieldDescription,
FieldGroup,
FieldLabel,
FieldSet,
} from "@/components/ui/field";
import { Input } from "@/components/ui/input";
export function FieldInput() {
return (
<FieldSet className="w-full max-w-xs">
<FieldGroup>
<Field>
<FieldLabel htmlFor="username">Username</FieldLabel>
<Input id="username" placeholder="Max Leiter" type="text" />
<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" placeholder="••••••••" type="password" />
</Field>
</FieldGroup>
</FieldSet>
);
}<FieldSet>
<FieldGroup>
<Field>
<FieldLabel htmlFor="username">Username</FieldLabel>
<Input id="username" 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.</FieldDescription>
<Input id="password" type="password" />
</Field>
</FieldGroup>
</FieldSet>Textarea
"use client";
import {
Field,
FieldDescription,
FieldGroup,
FieldLabel,
FieldSet,
} from "@/components/ui/field";
import { Textarea } from "@/components/ui/textarea";
export 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>
);
}<Field>
<FieldLabel htmlFor="feedback">Feedback</FieldLabel>
<Textarea id="feedback" rows={4} />
<FieldDescription>Share your thoughts.</FieldDescription>
</Field>Invalid
Set data-invalid on Field (or aria-invalid on the control) to trigger destructive styling on the label and control ring.
This field contains validation errors.
"use client";
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";
export function FieldInvalid() {
return (
<Field className="w-full max-w-xs" data-invalid>
<FieldLabel htmlFor="invalid-input">Invalid Input</FieldLabel>
<Input aria-invalid id="invalid-input" placeholder="Error" />
<FieldDescription>
This field contains validation errors.
</FieldDescription>
</Field>
);
}<Field data-invalid>
<FieldLabel htmlFor="email">Email</FieldLabel>
<Input id="email" aria-invalid />
<FieldDescription>This field contains validation errors.</FieldDescription>
</Field>With FieldError
<Field data-invalid>
<FieldLabel htmlFor="email">Email</FieldLabel>
<Input id="email" aria-invalid />
<FieldError>Email is required.</FieldError>
</Field>Horizontal with FieldContent
orientation="horizontal" places the label and control side by side. Use FieldContent to stack a title and description beside the control.
<Field orientation="horizontal">
<Checkbox id="terms" />
<FieldLabel htmlFor="terms">Accept terms and conditions</FieldLabel>
</Field><Field orientation="horizontal">
<FieldContent>
<FieldTitle>Share across devices</FieldTitle>
<FieldDescription>Focused settings sync between devices.</FieldDescription>
</FieldContent>
<Switch id="sync" />
</Field>Separator with label
<FieldSeparator>Or continue with</FieldSeparator>Checkbox in horizontal Field
Combine orientation="horizontal" with Checkbox and FieldLabel for an inline consent row.
"use client";
import { Checkbox } from "@/components/ui/checkbox";
import { Field, FieldLabel } from "@/components/ui/field";
export function FieldCheckbox() {
return (
<div className="w-full max-w-sm">
<Field className="mx-auto w-fit" orientation="horizontal">
<Checkbox id="terms" />
<FieldLabel className="h-4 items-center" htmlFor="terms">
Accept terms and conditions
</FieldLabel>
</Field>
</div>
);
}<Field orientation="horizontal">
<Checkbox id="terms" />
<FieldLabel htmlFor="terms">Accept terms and conditions</FieldLabel>
</Field>Switch with FieldContent
Use FieldContent to stack a FieldTitle and FieldDescription beside the Switch.
Focused settings sync between devices.
"use client";
import {
Field,
FieldContent,
FieldDescription,
FieldTitle,
} from "@/components/ui/field";
import { Switch } from "@/components/ui/switch";
export function FieldSwitch() {
return (
<div className="w-full max-w-sm">
<Field orientation="horizontal">
<FieldContent>
<FieldTitle>Share across devices</FieldTitle>
<FieldDescription>
Focused settings sync between devices.
</FieldDescription>
</FieldContent>
<Switch id="sync" />
</Field>
</div>
);
}<Field orientation="horizontal">
<FieldContent>
<FieldTitle>Share across devices</FieldTitle>
<FieldDescription>Focused settings sync between devices.</FieldDescription>
</FieldContent>
<Switch id="sync" />
</Field>Select
Compose Field with Select for a labelled dropdown with a description.
Choose one from the list.
"use client";
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from "@/components/ui/select";
export function FieldSelect() {
return (
<div className="w-full max-w-sm">
<Field>
<FieldLabel htmlFor="fruit">Favorite fruit</FieldLabel>
<Select>
<SelectTrigger id="fruit">
<SelectValue placeholder="Select a fruit" />
</SelectTrigger>
<SelectContent>
<SelectItem value="apple">Apple</SelectItem>
<SelectItem value="banana">Banana</SelectItem>
<SelectItem value="cherry">Cherry</SelectItem>
</SelectContent>
</Select>
<FieldDescription>Choose one from the list.</FieldDescription>
</Field>
</div>
);
}<Field>
<FieldLabel htmlFor="fruit">Favorite fruit</FieldLabel>
<Select>
<SelectTrigger id="fruit">
<SelectValue placeholder="Select a fruit" />
</SelectTrigger>
<SelectContent>
<SelectItem value="apple">Apple</SelectItem>
<SelectItem value="banana">Banana</SelectItem>
<SelectItem value="cherry">Cherry</SelectItem>
</SelectContent>
</Select>
<FieldDescription>Choose one from the list.</FieldDescription>
</Field>In Context
Login form
At least 8 characters.
"use client";
import {
Field,
FieldDescription,
FieldGroup,
FieldLabel,
} from "@/components/ui/field";
import { Input } from "@/components/ui/input";
export function FieldLogin() {
return (
<div className="mx-auto w-full max-w-sm">
<FieldGroup>
<Field>
<FieldLabel htmlFor="email">Email</FieldLabel>
<Input id="email" type="email" />
</Field>
<Field>
<FieldLabel htmlFor="password">Password</FieldLabel>
<Input id="password" type="password" />
<FieldDescription>At least 8 characters.</FieldDescription>
</Field>
</FieldGroup>
</div>
);
}API Reference
Field
| Prop | Type | Default | Description |
|---|---|---|---|
orientation | "vertical""horizontal" | — | Stack label above the control, or place it beside the control. |
data-invalid | boolean | — | Propagates invalid styling to the label and any descendant with data-slot=input. |
data-disabled | boolean | — | Grays out label and description. |
FieldSet / FieldLegend / FieldGroup / FieldLabel / FieldDescription / FieldContent / FieldTitle
Extend native <fieldset>, <legend>, <div>, <label>, and <p>.
FieldError
| Prop | Type | Default | Description |
|---|---|---|---|
children | ReactNode | — | Single error message to render. |
errors | Array<{ message?: string } | undefined> | — | Array of field errors; renders unique messages joined. Children take priority. |
FieldSeparator
Renders Frakment Separator. Accepts an optional children that renders as a centered label between two divider lines.
CSS Variables
| Variable | Default | Purpose |
|---|---|---|
--field-gap | theme spacing | Gap between label, control, description |
States
| State | How |
|---|---|
| Default | — |
| Invalid | data-invalid="true" on Field |
| Disabled | data-disabled="true" |
Data Attributes
| Attribute | Values |
|---|---|
data-slot | field-set, field-group, field, field-label, field-description, field-error, field-content |
data-invalid | true |
data-disabled | true |
data-orientation | vertical | horizontal |
Accessibility
Fielddoes not add roles. It is a layout primitive that groupsFieldLabelwith its control.- Use
htmlForonFieldLabelandidon the control. FieldErroris linked automatically when the parentFieldhasdata-invalid.
Best Practices
- One Field per control. Do not nest fields.
- Use
FieldGroupfor multiple fields. It normalizes vertical spacing. - Horizontal orientation works for Checkbox and Switch. Not for inputs.
- Pair label with description, not placeholder. Placeholders disappear.
Related Components
On This Page
InstallationUsageCompositionExamplesInputTextareaInvalidWith FieldErrorHorizontal with FieldContentSeparator with labelCheckbox in horizontal FieldSwitch with FieldContentSelectIn ContextLogin formAPI ReferenceFieldFieldSet / FieldLegend / FieldGroup / FieldLabel / FieldDescription / FieldContent / FieldTitleFieldErrorFieldSeparatorCSS VariablesStatesData AttributesAccessibilityBest PracticesRelated Components