Skip to content
WunderUI

Field

Free

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

Playground

We send receipts to this address.

Installation

bash
npx wunderui-cli add field

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
import {
  Field,
  FieldControl,
  FieldDescription,
  FieldError,
  FieldLabel,
} from "@/components/ui/field"

Then use it:

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

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.

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.

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.

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

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

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

PropTypeDefaultDescription
namestring—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.
invalidboolean—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.
disabledbooleanfalseDisables 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.
validationDebounceTimenumber0How long to wait between callbacks if is used. Specified in milliseconds.
dirtyboolean—Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library.
touchedboolean—Whether the field has been touched. Useful when the field state is controlled by an external library.
actionsRefRefObject<FieldRoot.Actions | null>—A ref to imperative actions. - : Validates the field when called.
classNamestring | (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.

PropTypeDefaultDescription
nativeLabelbooleantrueWhether 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.
classNamestring | (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.

PropTypeDefaultDescription
renderReactElement | (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.
defaultValueComponentProps<"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.

PropTypeDefaultDescription
classNamestring | (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.

PropTypeDefaultDescription
matchboolean | 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.
classNamestring | (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.

MCPget_component("field")
Installnpx wunderui-cli add field

The full library index for assistants is at /llms.txt.