Label
A native label element at the form type scale. One job: name a control, and make clicking the text focus it. Most of the time you want Field, which renders this for you and wires the id.
Import
import { Label } from "@mikenotthepope/substrateui"Prefer Field
Field generates the id, points FieldLabel at it, and wires any hint and error text into aria-describedby. Doing that by hand is three chances to get it wrong on every field in the app.
Reach for Label directly when there is no field to describe — a group caption, a label on a control you have built yourself, or a row where the label sits beside the control rather than above it.
Lowercase letters, numbers, and hyphens.
Beside a control
A checkbox or switch reads better with its label to the side. The label is still the click target, so the whole phrase toggles the control rather than only the 16 pixels of the box.
Disabled controls
The label dims itself when a peer-marked control next to it is disabled, via peer-disabled. That needs the control to carry the peerclass and to be a previous sibling — the label cannot see a disabled control it isn't next to.
Accessibility
This renders a real <label>, so the browser supplies the accessible name and the click-to-focus behaviour. A div styled to look like a label gives neither.
The association must exist: either htmlFormatching the control's id, or the control nested inside the label. Placeholder text is not a label — it disappears on first keystroke and is not announced as the field's name.
One label per control. Two elements both claiming to name the same input produce an unpredictable accessible name.
API Reference
Label adds no props of its own — everything, including className and ref, goes to the underlying <label>. See React.ComponentPropsWithRef<"label"> for that surface; the one prop worth naming is the association.
| Prop | Type | Default | Description |
|---|---|---|---|
htmlFor | string | — | The id of the control this labels. Required unless the control is nested inside the label. |