For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Field

A layout primitive for form fields — label, description, and inputs.

Payment Method

All transactions are secure and encrypted

Enter your 16-digit card number

Billing Address

The billing address associated with your payment method

field.tsx
"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

Usage

field.tsx
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";
<DocsBaseSwitcher base="web" component="field" className="mb-6" />
tsx
<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
└── FieldContent

Examples

Input

Choose a unique username for your account.

Must be at least 8 characters long.

field-input.tsx
"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>
  );
}
tsx
<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

Share your thoughts about our service.

field-textarea.tsx
"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>
  );
}
tsx
<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.

field-invalid.tsx
"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>
  );
}
tsx
<Field data-invalid>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" aria-invalid />
  <FieldDescription>This field contains validation errors.</FieldDescription>
</Field>

With FieldError

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

tsx
<Field orientation="horizontal">
  <Checkbox id="terms" />
  <FieldLabel htmlFor="terms">Accept terms and conditions</FieldLabel>
</Field>
tsx
<Field orientation="horizontal">
  <FieldContent>
    <FieldTitle>Share across devices</FieldTitle>
    <FieldDescription>Focused settings sync between devices.</FieldDescription>
  </FieldContent>
  <Switch id="sync" />
</Field>

Separator with label

tsx
<FieldSeparator>Or continue with</FieldSeparator>

Checkbox in horizontal Field

Combine orientation="horizontal" with Checkbox and FieldLabel for an inline consent row.

field-checkbox.tsx
"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>
  );
}
tsx
<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.

Share across devices

Focused settings sync between devices.

field-switch.tsx
"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>
  );
}
tsx
<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.

field-select.tsx
"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>
  );
}
tsx
<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.

field-login.tsx
"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

PropTypeDefaultDescription
orientation
"vertical""horizontal"
—Stack label above the control, or place it beside the control.
data-invalidboolean—Propagates invalid styling to the label and any descendant with data-slot=input.
data-disabledboolean—Grays out label and description.

FieldSet / FieldLegend / FieldGroup / FieldLabel / FieldDescription / FieldContent / FieldTitle

Extend native <fieldset>, <legend>, <div>, <label>, and <p>.

FieldError

PropTypeDefaultDescription
childrenReactNode—Single error message to render.
errorsArray<{ 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

VariableDefaultPurpose
--field-gaptheme spacingGap between label, control, description

States

StateHow
Default—
Invaliddata-invalid="true" on Field
Disableddata-disabled="true"

Data Attributes

AttributeValues
data-slotfield-set, field-group, field, field-label, field-description, field-error, field-content
data-invalidtrue
data-disabledtrue
data-orientationvertical | horizontal

Accessibility

  • Field does not add roles. It is a layout primitive that groups FieldLabel with its control.
  • Use htmlFor on FieldLabel and id on the control.
  • FieldError is linked automatically when the parent Field has data-invalid.

Best Practices

  • One Field per control. Do not nest fields.
  • Use FieldGroup for multiple fields. It normalizes vertical spacing.
  • Horizontal orientation works for Checkbox and Switch. Not for inputs.
  • Pair label with description, not placeholder. Placeholders disappear.