Field
A label, an optional hint and an error message wired to any form control by id.
import { Field } from "@butteryui/react";Demo
CSV and JSON hold every order.
When to use it
Use it for
- A buttery control without a form label of its own, such as Select (variant="outline") or SegmentedControl
- Your own control that needs a label, a hint and an error read with it
Not for
- A line of text: use TextField
- A password: use PasswordField
- Longer text: use TextArea
Examples
Bag size field
A segmented control with a label, a hint and an error, wired by Field: 1 kg shows the error.
500 g lasts about two weeks.
Format field
A select in its outline look for the export format, labelled by Field, with a hint that follows the choice.
CSV opens in any spreadsheet app.
New coffee form
A shop's form for a new coffee: Field labels the roast and the grind, and shows the grind's error on save.
Variants and states
Any control
The label names the control, and the hint and the error are read with it.
CSV and JSON hold every order.
PDF holds the first 500 orders only.
A segmented control
500 g lasts about two weeks.
Props
Field
| Prop | Type | Default | Description |
|---|---|---|---|
labelrequired | string | What the control asks for, shown above it. | |
hint | ReactNode | A hint under the label, such as the format expected. | |
error | ReactNode | What's wrong, shown under the control and read with it. Leave it out while nothing is. | |
required | boolean | Whether the control needs an answer; screen readers say so. | |
controlId | string | The control's id, when it needs a particular one. | |
announceError | boolean | true | Whether a new error is read out as it appears. Defaults to true; turn it off when an error summary
that takes focus reads the errors instead. |
childrenrequired | (control: FieldControlProps) => ReactNode | Renders the control, given the props that label and describe it. |
It also takes Omit<ComponentPropsWithRef<"div">, "children">.
FieldControlProps
What a field's control needs to be labelled and described: spread it onto the control.
| Field | Type | Default | Description |
|---|---|---|---|
idrequired | string | Ties the label to a native control through its htmlFor. | |
aria-labelledbyrequired | string | Names any control, native or not, by the label. | |
aria-describedbyrequired | string | The hint and the error, while they show. | |
aria-invalidrequired | true | Set while there's an error. | |
aria-requiredrequired | true | Set when the control needs an answer. |
Accessibility
The label names the control through htmlFor and aria-labelledby, so custom controls (a slider thumb, a combobox) are named too; the hint and the error describe it through aria-describedby, and an error sets aria-invalid, so screen readers read all three when the control takes focus. A new error is also read out with the field's name as it appears, unless announceError is off because an error summary reads it. The error has an icon as well as its color. required sets aria-required.
It takes no keyboard input of its own.
Motion
It doesn't move.
With reduced motion: Nothing changes.
Layout
A column as wide as its container: the label, the hint 6px under it, the control 8px below them and the error 8px under the control. The label, the hint and the error wrap rather than truncate. Field adds no hit area of its own; the control keeps its own size and target.
Related
See it in the Halfmoon shop demo.