Loading...
Skip to main content

Field

A universal layout wrapper for form controls that handles label, description, and validation feedback placement with CSS grid.

The Field component provides essential layout, spacing, and functionality for your form input or component of choice. They even scale to support laying out checkboxes, radios, and switches in a two-column layout.

We’ll never share your email with anyone else.
<FormField>
<FormLabel htmlFor="fieldText">
Email address
</FormLabel>
<FormControl
id="fieldText"
placeholder="name@example.com"
type="email"
/>
<FormText>
{' '}We’ll never share your email with anyone else.{' '}
</FormText>
</FormField>

How it works

FormField uses CSS grid to lay out a form control alongside its label, description, and validation feedback.

  • Default layout is a single-column grid where everything stacks vertically. Use this for text inputs, selects, textareas, ranges, input groups, and adorned inputs.
  • Two-column layout activates automatically via :has() when a Checkbox, Radio, or FormSwitch is a direct child. The control sits in the first column while its label, description, and feedback stack in the second.
  • Overhead label — when a FormLabel is present alongside a check, radio, or switch, it spans both columns and sits above the control row.
  • Grouped controls — nest multiple FormField components inside an outer FormField to group radios, checkboxes, or switches under a shared label with shared description and validation feedback.

Examples

Select

Use FormSelect for select controls.

<FormField>
<FormLabel htmlFor="fieldSelect">
Country
</FormLabel>
<FormSelect
defaultValue="Choose one…"
id="fieldSelect"
>
<option>
Choose one…
</option>
<option value="1">
United States
</option>
<option value="2">
Canada
</option>
<option value="3">
United Kingdom
</option>
</FormSelect>
</FormField>

Textarea

Use FormTextArea for multi-line text controls. Descriptions are optional.

Be sure to include relevant details.
<FormField>
<FormLabel htmlFor="fieldTextarea">
Message
</FormLabel>
<FormTextArea
id="fieldTextarea"
rows={3}
/>
<FormText>
{' '}Be sure to include relevant details.{' '}
</FormText>
</FormField>

Checkbox

When a Checkbox is a direct child, the grid switches to a two-column layout with the checkbox in the first column and its label in the second.

<FormField>
<Checkbox id="fieldCheck" />
<FormLabel
htmlFor="fieldCheck"
plain
>
Remember me
</FormLabel>
</FormField>

Radio

Radios use the same two-column layout. Wrap each Radio and its label in its own FormField.

<div className="d-flex flex-column gap-2">
<FormField>
<Radio
id="fieldRadio1"
name="fieldRadioGroup"
/>
<FormLabel
htmlFor="fieldRadio1"
plain
>
Option one
</FormLabel>
</FormField>
<FormField>
<Radio
id="fieldRadio2"
name="fieldRadioGroup"
/>
<FormLabel
htmlFor="fieldRadio2"
plain
>
Option two
</FormLabel>
</FormField>
</div>

Grouped

Wrap multiple FormField components in FormGroup to group related controls under a shared label. The group provides consistent spacing while each inner field keeps its own layout.

Choose your preferred shipping speed.
<FormGroup>
<FormLabel>
Shipping method
</FormLabel>
<FormField>
<Radio
id="fieldGroupRadio1"
name="fieldGroupRadio"
required
/>
<FormLabel
htmlFor="fieldGroupRadio1"
plain
>
Standard
</FormLabel>
</FormField>
<FormField>
<Radio
id="fieldGroupRadio2"
name="fieldGroupRadio"
required
/>
<FormLabel
htmlFor="fieldGroupRadio2"
plain
>
Express
</FormLabel>
</FormField>
<FormText>
Choose your preferred shipping speed.
</FormText>
</FormGroup>

Group cards

Set the card prop on each FormField for a card-style treatment that highlights the selected option. Wrap the inner fields in FormGroup with tighter spacing for a more compact look.

$9/month — For individuals.
$29/month — For teams.
<FormGroup>
<FormLabel>
Select a plan
</FormLabel>
<Stack gap={1}>
<FormField card>
<Radio
defaultChecked
id="fieldRadioGroup1"
name="fieldRadioGrouped"
/>
<FormFieldContent>
<FormLabel
htmlFor="fieldRadioGroup1"
plain
>
Basic
</FormLabel>
<FormText>
$9/month — For individuals.
</FormText>
</FormFieldContent>
</FormField>
<FormField card>
<Radio
id="fieldRadioGroup2"
name="fieldRadioGrouped"
/>
<FormFieldContent>
<FormLabel
htmlFor="fieldRadioGroup2"
plain
>
Pro
</FormLabel>
<FormText>
$29/month — For teams.
</FormText>
</FormFieldContent>
</FormField>
</Stack>
</FormGroup>

Switch

Switches also trigger the two-column grid.

<FormField>
<FormSwitch id="fieldSwitch" />
<FormLabel
htmlFor="fieldSwitch"
plain
>
Enable notifications
</FormLabel>
</FormField>

Combobox

Comboboxes—as well as datepickers, OTPs, and any other form component—are support as well.

Choose an item from the menu above.
<FormField>
<FormLabel plain>
Combobox
</FormLabel>
<Combobox
name="option"
placeholder="Select an item…"
>
<ComboboxOption value="1">
Option one
</ComboboxOption>
<ComboboxOption value="2">
Option two
</ComboboxOption>
<ComboboxOption value="3">
Option three
</ComboboxOption>
</Combobox>
<FormText>
Choose an item from the menu above.
</FormText>
</FormField>

Overhead label

When a check, radio, or switch needs a field title above it, add a FormLabel. It automatically spans both columns and sits on its own row above the control.

Please read before agreeing.
<FormField>
<FormLabel>
Terms and conditions
</FormLabel>
<Checkbox
id="fieldOverheadCheck"
required
/>
<FormFieldContent>
<FormLabel
htmlFor="fieldOverheadCheck"
plain
>
I agree to the terms
</FormLabel>
<FormText>
Please read before agreeing.
</FormText>
</FormFieldContent>
</FormField>

Descriptions

Add FormText after the label and wrap it in FormFieldContent to ensure appropriate spacing and alignment.

We’ll send you a weekly digest of what’s new.
Arrives in 5-7 business days.
Must be 3-20 characters, letters and numbers only.
<div className="d-flex flex-column gap-3">
<FormField>
<Checkbox id="fieldCheckDesc" />
<FormFieldContent>
<FormLabel
htmlFor="fieldCheckDesc"
plain
>
Subscribe to updates
</FormLabel>
<FormText>
We’ll send you a weekly digest of what’s new.
</FormText>
</FormFieldContent>
</FormField>
<FormField>
<Radio
id="fieldRadioDesc"
name="fieldRadioDesc"
/>
<FormFieldContent>
<FormLabel
htmlFor="fieldRadioDesc"
plain
>
Standard shipping
</FormLabel>
<FormText>
Arrives in 5-7 business days.
</FormText>
</FormFieldContent>
</FormField>
<FormField>
<FormLabel htmlFor="fieldTextDesc">
Username
</FormLabel>
<FormControl
id="fieldTextDesc"
type="text"
/>
<FormText>
Must be 3-20 characters, letters and numbers only.
</FormText>
</FormField>
</div>

Validation

FormFeedback stacks correctly inside FormField for all control types. Set its type prop to valid for success feedback; it defaults to invalid feedback.

Client-side

Pass data-bs-validate to ValidationForm to opt in to :user-invalid styling. These pseudo-classes activate after the user interacts with a control. To also show success styling on valid fields, use data-bs-validate="valid". Set noValidate to suppress native browser validation tooltips while keeping the constraint validation API available.

Please enter a valid email address.
Looks good!
You must agree before submitting.
<Stack
as={function ve(){}}
data-bs-validate=""
gap={3}
noValidate
>
<FormField className="flex-1">
<FormLabel htmlFor="fieldValidateEmail">
Email address
</FormLabel>
<FormControl
id="fieldValidateEmail"
required
type="email"
/>
<FormFeedback>
Please enter a valid email address.
</FormFeedback>
<FormFeedback type="valid">
Looks good!
</FormFeedback>
</FormField>
<FormField>
<Checkbox
id="fieldValidateCheck"
required
/>
<FormFieldContent>
<FormLabel
htmlFor="fieldValidateCheck"
plain
>
Agree to terms and conditions
</FormLabel>
<FormFeedback>
You must agree before submitting.
</FormFeedback>
</FormFieldContent>
</FormField>
<Button
className="align-self-start"
theme="primary"
type="submit"
variant="solid"
>
Submit
</Button>
</Stack>

Server-side

Set the control's validation prop to invalid or valid for server-side validation. Feedback is visible immediately on page load.

Please enter a valid email address.
Looks good!
You must agree before submitting.
This field is required.
<>
<FormField className="mb-3">
<FormLabel htmlFor="fieldServerEmail">
Email address
</FormLabel>
<FormControl
defaultValue="not-an-email"
id="fieldServerEmail"
required
type="email"
validation="invalid"
/>
<FormFeedback>
Please enter a valid email address.
</FormFeedback>
</FormField>
<FormField className="mb-3">
<FormLabel htmlFor="fieldServerName">
Full name
</FormLabel>
<FormControl
defaultValue="Mark Otto"
id="fieldServerName"
required
type="text"
validation="valid"
/>
<FormFeedback type="valid">
Looks good!
</FormFeedback>
</FormField>
<FormField className="mb-3">
<Checkbox
id="fieldServerCheck"
required
validation="invalid"
/>
<FormLabel
htmlFor="fieldServerCheck"
plain
>
Agree to terms and conditions
</FormLabel>
<FormFeedback>
You must agree before submitting.
</FormFeedback>
</FormField>
<FormField className="mb-3">
<FormSwitch
id="fieldServerSwitch"
validation="invalid"
/>
<FormLabel
htmlFor="fieldServerSwitch"
plain
>
Accept marketing emails
</FormLabel>
<FormFeedback>
This field is required.
</FormFeedback>
</FormField>
</>
Documentation navigation
On this page
On this page