Field

Combine labels, controls, and help text to compose accessible form fields and grouped inputs.

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

Installation

pnpm dlx cubix@latest add field --base aria

Usage

Import

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

Example

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

Composition

Field

A single control with label, helper text, and validation.

Field
├── FieldLabel
├── Input / Textarea / Switch / Select
├── FieldDescription
└── FieldError

FieldGroup

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

FieldSet

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

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

Input

<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

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

Select

<Field className="w-full max-w-xs">
  <FieldLabel>Department</FieldLabel>
  <Select>
    <SelectTrigger>
      <SelectValue placeholder="Choose department" />
    </SelectTrigger>
    <SelectContent>
      <SelectGroup>
        <SelectItem value="engineering">Engineering</SelectItem>
        <SelectItem value="design">Design</SelectItem>
        <SelectItem value="marketing">Marketing</SelectItem>
      </SelectGroup>
    </SelectContent>
  </Select>
  <FieldDescription>
    Select your department or area of work.
  </FieldDescription>
</Field>

Fieldset

Address Information

We need your address to deliver your order.

<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>
    <div 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>
    </div>
  </FieldGroup>
</FieldSet>

Checkbox

Show these items on the desktop

Select the items you want to show on the desktop.

Hard disks

External disks

CDs, DVDs, and iPods

Connected servers

Sync Desktop & Documents folders

Your Desktop & Documents folders are being synced with iCloud Drive. You can access them from other devices.

<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="finder-hard-disks" defaultChecked />
        <FieldLabel htmlFor="finder-hard-disks" className="font-normal">
          Hard disks
        </FieldLabel>
      </Field>
    </FieldGroup>
  </FieldSet>
  <FieldSeparator />
  <Field orientation="horizontal">
    <Checkbox id="finder-sync-folders" defaultChecked />
    <FieldContent>
      <FieldLabel htmlFor="finder-sync-folders">
        Sync Desktop & Documents folders
      </FieldLabel>
      <FieldDescription>
        Your Desktop & Documents folders are being synced with iCloud Drive.
      </FieldDescription>
    </FieldContent>
  </Field>
</FieldGroup>

Radio

Subscription Plan

Yearly and lifetime plans offer significant savings.

Monthly ($9.99/month)

Yearly ($99.99/year)

Lifetime ($299.99)

<FieldSet className="w-full max-w-xs">
  <FieldLegend variant="label">Subscription Plan</FieldLegend>
  <FieldDescription>
    Yearly and lifetime plans offer significant savings.
  </FieldDescription>
  <RadioGroup defaultValue="monthly">
    <Field orientation="horizontal">
      <RadioGroupItem value="monthly" id="plan-monthly" />
      <FieldLabel htmlFor="plan-monthly" className="font-normal">
        Monthly ($9.99/month)
      </FieldLabel>
    </Field>
    <Field orientation="horizontal">
      <RadioGroupItem value="yearly" id="plan-yearly" />
      <FieldLabel htmlFor="plan-yearly" className="font-normal">
        Yearly ($99.99/year)
      </FieldLabel>
    </Field>
  </RadioGroup>
</FieldSet>

Switch

Multi-factor authentication

<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 radio, checkbox, and switch controls.

Compute Environment

Select the compute environment for your cluster.

Kubernetes

Run GPU workloads on a K8s cluster.

Virtual Machine

Access a cluster to run GPU workloads.

<FieldGroup className="w-full max-w-xs">
  <FieldSet>
    <FieldLegend variant="label">Compute Environment</FieldLegend>
    <FieldDescription>
      Select the compute environment for your cluster.
    </FieldDescription>
    <RadioGroup 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>
    </RadioGroup>
  </FieldSet>
</FieldGroup>

Field Group

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

Responses

Get notified when an assistant responds to requests that take time, like research or image generation.

Push notifications

Tasks

Get notified when tasks you've created have updates. Manage tasks

Push notifications

Email notifications

<FieldGroup className="w-full max-w-xs">
  <FieldSet>
    <FieldLabel>Responses</FieldLabel>
    <FieldDescription>
      Get notified when requests take time.
    </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>
    <FieldLabel>Tasks</FieldLabel>
    <FieldDescription>
      Get notified when tasks you&apos;ve created have updates.{" "}
      <a href="#">Manage tasks</a>
    </FieldDescription>
  </FieldSet>
</FieldGroup>

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.

<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="Evil Rabbit" required />
    </Field>
    <Field orientation="responsive">
      <Button type="submit">Submit</Button>
      <Button type="button" variant="outline">Cancel</Button>
    </Field>
  </FieldGroup>
</FieldSet>

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>

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.

API Reference

FieldSet

Container that renders a semantic fieldset with spacing presets.

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

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 size of the legend. Use label for nested fieldsets that should match FieldLabel.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

FieldGroup

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

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

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 of the label and control. responsive switches at the FieldGroup container breakpoint.
data-invalid	boolean	-	Marks the field as invalid and applies destructive text color.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

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 Tailwind classes merged with the component styles (last one wins).

FieldLabel

Label styled for both direct inputs and nested Field children.

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

FieldTitle

Renders a title with label styling inside FieldContent.

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

FieldDescription

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

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).

FieldSeparator

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

Prop	Type	Default	Description
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).
children	React.ReactNode	-	Optional label rendered over the separator line.

FieldError

Accessible error container that accepts children or an errors array.

Prop	Type	Default	Description
errors	Array<{ message?: string } \| undefined>	-	Validation messages to render. Multiple unique messages become a list.
className	string	-	Additional Tailwind classes merged with the component styles (last one wins).
children	React.ReactNode	-	Custom error content. When set, errors is ignored.