Field
FreeJoin a control to its label, hint and error message, so a screen reader reads them together and the state reaches every part.
npx wunderui-cli add fieldPlayground
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
Installation
npx wunderui-cli add fieldWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Field,
FieldControl,
FieldDescription,
FieldError,
FieldLabel,
} from "@/components/ui/field"Then use it:
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
export function Email() {
return (
<Field>
<FieldLabel>Work email</FieldLabel>
<Input type="email" placeholder="name@company.com" />
<FieldDescription>We send receipts to this address.</FieldDescription>
</Field>
)
}Expected result: You see the label Work email above a white field with a grey placeholder, and the hint below it. A click on the label focuses the field, and the border turns indigo.
When to use
Use Field for
- A control that needs a label, a hint or an error message
- A form where the state (invalid, disabled) must reach the label and the messages
- A control that is not an Input, such as a Textarea, that should join a label and a hint
Use something else for
- Fieldset for a group of related controls that share one legend, such as an address or a set of checkboxes
- Textarea for a Textarea that brings its own label, helper line and error
- Checkbox for one checkbox with its label and description in a single row
- Form for the form that holds the Fields: submit, validation mode and server errors
Layout
Stacked puts the label above the control. Inline puts label and hint in a column beside it, and falls back to stacked in a container narrower than 512 px.
We send receipts to this address.
We send receipts to this address.
Label and hint
The label names the control and the hint states the rule. A note like Optional or a link like Forgot password sits on the label row, on the right.
Control
An Input joins its Field by itself, also inside an Input Group. Any other control joins through FieldControl.
We send receipts to this address.
We send receipts to this address.
Tell us what you are working on.
States
Invalid and disabled belong to the Field and reach the label, control and messages. Read-only belongs to the control, and the error replaces the hint while the control stays white.
We send receipts to this address.
We send receipts to this address.
We send receipts to this address.
Behavior and motion
What Field does itself, and what it leaves to the page.
- Label wiring
- The label is linked to the control with generated ids, so you never write htmlFor. An Input inside an Input Group is still found, so the label points to the input and not the group.
- Description and error wiring
- The description and error register with the Field, and the control gets them as its description. A screen reader reads the label, the control, then the hint, and the error while it shows.
- Invalid
- Marking the Field invalid sets the invalid state on the Input, turns the border and focus ring red, and shows the error. The fill of the control stays white.
- FieldError
- The error shows only while the field is invalid, unless a match setting shows it at once or for one rule. Without children it prints the failed check's message.
- Disabled
- Disabled reaches the control, dims the label and hint to 40% and skips the control in the tab order. A Field inside a disabled Fieldset is disabled too.
- Form
- Inside a Form, give the Field a name. Errors passed to the Form by that name make the Field invalid and stay until you pass new ones, so clear them after the next submit.
- Read-only
- Read-only belongs to the control: set it on the Input. The control stays readable, focusable and copyable, and is filled with the subtle tone.
- Motion
- The Field adds no motion of its own. The control fades its border colour on the fast duration, and messages appear without moving the controls around them when you keep a line of room.
- Reduced motion
- Nothing moves, so there is nothing to reduce. The colour change of the control stays: it is a short fade, not movement.
Anatomy
Field is the wrapper of one control. It carries the state and gives the label, hint and error to the control, so you write no ids and no aria attributes.
We send receipts to this address.
- data-slot="field"
The wrapper of one control: a column with 4 px between its parts. It owns the name, invalid, disabled and validation state, and every part inside reads them.
- 1data-slot="field-label"
The visible name of the control, in 14 px medium text with 4 px below it. It is linked to the control, so a click on it focuses the control, and it dims with a disabled field.
- 2data-slot="field-control"
The control itself. An Input joins the Field by itself, any other control such as a Textarea joins through FieldControl, and the Field passes it the invalid and described-by attributes.
- 3data-slot="field-description"Optional
The hint under the control in 12 px tertiary text. It is linked to the control, so a screen reader reads it after the label, and it dims with a disabled field.
- data-slot="field-error"Optional
The error message in 12 px error text. It shows only while the field is invalid, is linked to the control and is left out while the field is disabled, so hide the hint while it shows.
Best practices
- Do
Put the label first, then the control, then the hint or the error. A label is a noun (Work email) and a hint is a full sentence.
- Do
Give each Field a name when it sits in a Form. The name is how an error you pass to the Form finds its field.
- Do
Write the error as an instruction: Enter an email address like name@company.com, not Invalid. Show it after the person leaves the field or sends the form, and keep what they typed.
- Do
Render the hint only while there is no error, so the error takes its place. Keep a line of room for the message so the controls below do not jump.
- Do
Mark an exception on the label row (Optional), not in the placeholder. A placeholder is gone once the person starts to type.
- Don’t
Don't build the label, hint and error by hand with label, p and ids. You lose the links that Field sets and the state that reaches every part.
- Don’t
Don't put two controls in one Field. The label names one control; two controls need a Fieldset with a legend.
- Don’t
Don't disable only the control and leave the Field enabled. The label and hint then stay at full strength next to a dimmed control.
API reference
Field and its parts are the Base UI field parts with WunderUI styling, so every part also takes the props of its element, a render prop and a ref. The tables list the props that matter for the field.
The wrapper of one control: a column with 4 px between its parts. It owns the name, invalid, disabled and validation state, and every part inside reads them.
| Prop | Type | Default | Description |
|---|---|---|---|
| name | string | — | Identifies the field in a form. In a it is the key that the object uses to find this field, and the name of the value that receives. |
| invalid | boolean | — | Marks the field invalid. The control gets , the border and the ring turn red, and shows. Use it when you decide the state yourself; a Form's set it for you. |
| disabled | boolean | false | Disables the control, dims the label and the hint to 40 % and skips the control in the tab order. It also takes the place of on the control. |
| validate | (value, formValues) => string | string[] | null | void | Promise<string | string[] | null | void> | — | A function for a check of your own. It gets the value and the form values and returns a message (or an array of messages) when the value is wrong, and when it is fine. |
| validationMode | "onBlur" | "onChange" | "onSubmit" | "onSubmit" | When runs: (the default) checks on submit and again on every change after that, checks when the control loses focus, checks on every change. It takes precedence over the same prop on the Form. |
| validationDebounceTime | number | 0 | How long to wait between callbacks if is used. Specified in milliseconds. |
| dirty | boolean | — | Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library. |
| touched | boolean | — | Whether the field has been touched. Useful when the field state is controlled by an external library. |
| actionsRef | RefObject<FieldRoot.Actions | null> | — | A ref to imperative actions. - : Validates the field when called. |
| className | string | (state) => string | undefined | — | CSS class applied to the element, or a function that returns a class based on the component's state. |
The visible name of the control, in 14 px medium text with 4 px below it. It is linked to the control, so a click on it focuses the control, and it dims with a disabled field.
| Prop | Type | Default | Description |
|---|---|---|---|
| nativeLabel | boolean | true | Whether the label is a native element. It is by default. Set it to when you replace the element through with something that is not a label, such as a , so it does not inherit label behaviour. |
| className | string | (state) => string | undefined | — | CSS class applied to the element, or a function that returns a class based on the component's state. |
The control itself. An Input joins the Field by itself, any other control such as a Textarea joins through FieldControl, and the Field passes it the invalid and described-by attributes.
| Prop | Type | Default | Description |
|---|---|---|---|
| render | ReactElement | (props, state) => ReactElement | — | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render. |
| defaultValue | ComponentProps<"input">["defaultValue"] | — | The value the control starts with when it keeps its own value. A plain takes itself. |
| onValueChange | (value, eventDetails) => void | — | Callback fired when the changes. Use when controlled. |
The hint under the control in 12 px tertiary text. It is linked to the control, so a screen reader reads it after the label, and it dims with a disabled field.
| Prop | Type | Default | Description |
|---|---|---|---|
| className | string | (state) => string | undefined | — | CSS class applied to the element, or a function that returns a class based on the component's state. |
The error message in 12 px error text. It shows only while the field is invalid, is linked to the control and is left out while the field is disabled, so hide the hint while it shows.
| Prop | Type | Default | Description |
|---|---|---|---|
| match | boolean | keyof ValidityState | — | When the error shows. shows it at once, a validity key such as or shows it for that rule only, and without it the error shows whenever the field is invalid. |
| className | string | (state) => string | undefined | — | CSS class applied to the element, or a function that returns a class based on the component's state. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("field")npx wunderui-cli add fieldThe full library index for assistants is at /llms.txt.