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.
<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 aCheckbox,Radio, orFormSwitchis a direct child. The control sits in the first column while its label, description, and feedback stack in the second. - Overhead label — when a
FormLabelis present alongside a check, radio, or switch, it spans both columns and sits above the control row. - Grouped controls — nest multiple
FormFieldcomponents inside an outerFormFieldto 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.
<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.
<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.
<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.
<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.
<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.
<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.
<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.
<>
<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>
</>