Fields
A field owns its label, its error, and its busyness, so a form is only fields in a column.
Input, textarea, select, number field, date picker, and combobox share one set of behaviours. Learn them here once. Each component page covers what is particular to that field: its value, its keys, and its panel.
Anatomy and states
Sizes
Two sizes, shared across the family and matched to the button tiers. There is no variant prop, so every field has one look.
| Sample | Size | Value | Use it for |
|---|---|---|---|
| Default | h-9, px-3 | The standard field. It matches the default button, so a field and its submit button line up in a row. | |
| Small | h-8, px-2.5 | A dense field. It matches the small button and the small chip. |
State props
Each state is a prop on the field. A form never draws these itself.
| Sample | Prop | Looks like | Behaviour |
|---|---|---|---|
| description | Muted text under the box | Helper text that a screen reader reads with the field. It stays when an error arrives. | |
| error | Destructive border, ring, label, and message | The field owns the whole failure. The message renders below the box and the field grows downward only. | |
| loading | A spinner in the end slot | Background work such as a search or a name check. The field stays editable. | |
| disabled | Dimmed field and label | No pointer events, and nothing posts, like a native disabled control. | |
| readOnly | Muted background, full contrast | The value stays readable, focusable, and selectable. |
className styles the wrapper
A field renders a wrapper around its box so it can hold the label, the description, and the error message. className styles that wrapper, not the box. That is where width belongs: set w-64 on the field and the label, box, and message all take it. Every other native prop passes through to the control inside.
Description
description is helper text in muted type directly under the box. It joins the field’s accessible description, so a screen reader reads it with the field. It stays put when an error arrives: the message renders below it, and a screen reader hears the error first, then the description. A disabled field dims its description with its label.
Error
Pass error and the field owns the whole failure: the border, the ring, and the label turn destructive, the field is marked aria-invalid, and the message renders below. The field grows downward only, never sideways, and nothing shakes, so errors arrive calmly.
A form does not collect field errors or render a summary. Each field shows its own. A failure that spans fields, or that only the server can judge, goes in the form’s result slot instead.
Loading
loading puts the spinner in the field’s end slot and sets aria-busy. The field stays editable. Field loading means background work, and the submit button is what locks a flow. With an error alongside, both show and the spinner turns destructive: hiding the message during a re-check would flash a validity the field has not earned.
Disabled and read-only
Disabled dims the field and its label together, takes no pointer events, and posts nothing. Read-only keeps full text contrast on a muted background, shows a normal cursor, and stays focusable so the value can still be read, selected, and copied. Use disabled for a control that cannot apply right now and read-only for a value the person may see but not change.
Fields in a form
Form gives its children one vertical rhythm, an actions row, and a result slot. It needs no wrapper around a field, because the field already holds its own label and message. The submit button’s loading is the only busyness a submitting form shows, and the fields stay editable while it runs.
Usage rules
- DoKeep a field’s label, description, and error inside the field.The field wires the label to the control and the message to its accessible description, so a screen reader hears them with the control.
- DoGive a field’s label, message, and box one width.The wrapper holds all three, so a width set on the field with className sizes them together.
- DoMatch the field size to the buttons beside it.Default and small share heights across the family, so a row lines up without adjustment.
- Don’tLock a field with loading.Loading is background work and the field stays editable. Disable the submit button, or use disabled, to lock the flow.
- Don’tHold the error until submit when the field can tell sooner.The error belongs under the field the person is looking at, as soon as you know.