Field
Combine labels, controls, and help text to compose accessible form fields and grouped inputs.
Installation
Needs the arene setup first. Also adds Label, Separator and Stack.
Install the packages it imports:
Set up the token layer and the StyleX compiler, if you have not already. See
Installation, and paste states.ts from the same page,
which is where a choice card's focus ring comes from. The field builds on
Label, Separator and
Stack, so paste those first. It also needs interop.css, which styles a link inside a
description.
Paste field-state.ts and state-styles.ts from the same installation page.
The choice card's ring also needs the lib/focus-visible.ts helper, which
tells it whether its focus came from the keyboard.
Paste the focus-visible helper and the component into your project.
Change the @/ imports if your project uses different aliases.
Use Fieldset to group related fields.
Usage
Use arene controls inside Field to inherit labels, descriptions, validation and disabled state.
Composition
Field
A single control with a label, helper text and validation.
FieldGroup
Groups related fields. Put a FieldSeparator between sections that need one.
Fieldset
A fieldset element with a legend and a description. It usually holds a
FieldGroup.
Anatomy
Fieldis the wrapper for a single field. It publishes itsorientation,invalidanddisabledstate to the parts inside it.FieldContentis a column that groups the label and description beside a control. You do not need it if there is no description.- Wrap related fields with
FieldGroup, and useFieldsetwithFieldsetLegendfor semantic grouping.
Form
See React Hook Form for building a form with
Field, schema validation and per-field errors.
Input
Fieldset
Use Fieldset and FieldsetLegend to group fields under a heading. FieldsetLegend
takes variant="label" to size the heading like a label, for a fieldset nested
inside a form.
Checkbox
Use orientation="horizontal" to put the control before the label. Wrap the
label and a description in FieldContent when a row has both.
Each export is also saved to the lab archive, where the whole team can open it later.
Choice card
Wrap a Field inside a FieldLabel to make the whole card select the control.
Pass checked to the label as well as the control.
Field group
Stack fields with FieldGroup. Use FieldSeparator to divide them, and gap
to tighten a list of checkboxes.
Responsive layout
- Vertical fields. The default stacks the label, the control and the helper text.
- Horizontal fields. Set
orientation="horizontal"to put the label and control side by side. Pair it withFieldContentto keep a description aligned under the label. - Responsive fields. Set
orientation="responsive"to stack on a narrowFieldGroupand form a row once the group is28remwide. Give a control that stretches, such asInput,xstyle={fieldStyles.control}so its width becomesautowhen the row forms.
Validation and errors
- Set
invalidonFieldto turn the label and error red. - Controls inherit validation and disabled state from
Field. - Render
FieldErrorafter the control, or insideFieldContent, so the message lines up with the field. Base UI shows it when the field is invalid.
We only use it to send your receipt.
FieldError also takes an errors array, the shape a form library produces.
One message renders as text and several as a list, with duplicates removed.
Inherited state
Set invalid and disabled on Field to style and disable its control.
Invalid
Disabled and invalid
Native validation
Use validate or native attributes such as required, then render FieldError.
Accessibility
FieldsetandFieldsetLegendkeep related controls grouped for keyboard and assistive tech users.FieldLabelandFieldDescriptionassociate automatically with the control.FieldErrorrendersrole="alert", so a message that appears is announced.- Apply
FieldSeparatorsparingly. Each one is a section boundary a screen reader stops at.
Grouped choices
Wrap each checkbox or radio and its label in FieldItem to give it a separate label association within one field. See Checkbox Group.
API reference
Pass render to replace a part's element or compose it with another component.
Field, FieldLabel, FieldDescription and FieldError wrap the corresponding Base UI Field parts. Styled parts accept xstyle, className, inline style and render. Layout parts keep their native attributes.
Field
| Prop | Type | Default |
|---|---|---|
orientation | "vertical" | "horizontal" | "responsive" | "vertical" |
invalid | boolean | — |
disabled | boolean | false |
Field passes disabled to the control and dims the label and title. It passes invalid, name, validate, validationMode, dirty and touched to Base UI.
See Fieldset for Fieldset and FieldsetLegend.
FieldGroup
| Prop | Type | Default |
|---|---|---|
gap | SpacingStep | 5 |
FieldLabel
| Prop | Type | Default |
|---|---|---|
checked | boolean | — |
disabled | boolean | — |
checked draws the choice-card frame and only applies when the label wraps a
Field. disabled falls back to the enclosing field's value.
FieldError
| Prop | Type | Default |
|---|---|---|
errors | Array<{ message?: string } | undefined> | — |
match | boolean | keyof ValidityState | — |
Children take precedence over errors. With neither, Base UI displays the validation message. Pass match to select a validity condition. FieldValidity exposes Base UI validity through a render function.
fieldStyles
The style maps behind the component. Spread them onto any element.
| Key | What it is |
|---|---|
field | The row or column: flex, full width, the gap between parts |
orientations | vertical, horizontal and responsive direction maps |
invalid | The destructive text colour |
control | Full width that becomes auto once a responsive row forms |
card | The choice-card panel: raised surface, radius, inset |
cardChecked | The card's selected edge |
cardFocused | The card's focus ring, painted without a pseudo-class |
description | Muted small text |
error | Destructive small text |
card is the panel alone. Merge cardChecked and cardFocused over it for the
selected edge and the focus ring. cardFocused is states.ring from
theme/states.ts with the card's lift kept under it, and has no pseudo-class:
the card tracks focus itself, from a focus event that bubbles up from the
control inside it.
FieldItem
FieldItem accepts Base UI Field.Item props, including disabled and render, plus xstyle, className, and inline style. It adds no layout styles.
Data attributes
| Attribute | On | Effect |
|---|---|---|
data-slot="field-item" | individual choice | Label and description scope |
data-slot="field" | the field | Targets the field from a parent |
data-orientation | the field | Mirrors orientation |
data-valid, data-invalid, data-disabled, data-dirty, data-touched, data-filled, data-focused | the field | Base UI validity and disabled state |
data-slot="field-group" | the group | The container a responsive field queries |
data-slot="field-content" | the text column | |
data-slot="field-label" | the label | data-checked present on a selected card |
data-slot="field-title" | the title | |
data-slot="field-description" | the description | Where interop.css styles a link inside it |
data-slot="field-separator" | the separator | data-content present when it carries text |
data-slot="field-separator-line" | the rule | Renders role="separator" |
data-slot="field-separator-content" | the text on a rule | |
data-slot="field-error" | the error | Renders role="alert" |