Label
FreeName a field in words that stay on screen, and join them to the field so a click on them focuses it.
npx wunderui-cli add labelPlayground
Installation
npx wunderui-cli add labelWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Label } from "@/components/ui/label"Then use it:
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
export function Name() {
return (
<div className="flex flex-col gap-1">
<Label htmlFor="name">Full name</Label>
<Input id="name" placeholder="Nora Lindgren" />
</div>
)
}Expected result: You see the words Full name above a white field. Clicking the words focuses the field and turns its border indigo.
When to use
Use Label for
- The visible name of an Input, a Textarea or a Checkbox
- A requirement note, a link or an info tip on the row of a field
- A name that only assistive technology sees (visually hidden)
Use something else for
- Field for a label, control, helper and error line that are joined for you (FieldLabel)
- Fieldset for the legend of a group of related controls
- Checkbox for a checkbox with its label and description in one clickable row
- Tooltip for a longer explanation next to a label, which does not fit in the helper line
Wiring
A label does nothing until it is joined to a field, so click the words in each card and the field takes focus. A Field joins them for you.
Content
Keep the label a short noun. A note says required or optional, a link goes on the right, and an info tip holds a rule too long for a helper line.
Position
Above the field is the default and works at every width. Left suits settings rows, right suits a checkbox or radio, and a hidden label names a compact control for screen readers.
Behavior and motion
What the label does itself, and what it leaves to the page.
- A native label
- Label renders a native label, so linking by id, wrapping a control and click-to-focus are all the browser's doing. It isn't a tab stop; the control is.
- Three ways to join
- Three ways to join: an id with htmlFor, the control inside the label, or FieldLabel inside a Field, which joins the two for you. Pick one per control.
- Accessible name
- The label text, with the requirement note inside it, is the control's name. Full name Required is announced as the name, which is why the note is a plain word.
- Row layout
- A label is a flex row with 8 px between children, so a note sits after the name on the same line. A control inside the label needs a column layout to sit below it.
- Disabled
- Inside a Field, a label dims to 40 % when its control is disabled. Next to a control marked peer, a disabled control dims it too; elsewhere, dim it yourself.
- Selection
- The label text isn't selectable, so quick repeated clicks on it, as a person makes to focus a field, never select the words.
- Hidden label
- A visually hidden label stays in the page and out of the layout. It still names the control and still focuses it when a click lands on it.
- Motion
- A label does not move or change colour on its own.
Anatomy
Label is the name of a field: a native label in a row. It does nothing until it is joined to a control, and the note after it, such as Required, is text you put inside it.
- 1data-slot="label"
A native label in a row, 8 px between children, in 14 px medium text. Join it to a control by id, by wrapping the control, or with FieldLabel inside a Field; clicking it focuses the control.
- 2Optional
A short word after the name, Required or Optional, in 12 px tertiary text. It sits inside the label, so it is part of the accessible name and a screen reader reads it too.
- 3data-slot="input"
The field the label names: an Input, a Textarea, a Checkbox. A label without a control is just text, and in a Field the label dims when the control is disabled.
Best practices
- Do
Join every label to its control: FieldLabel inside a Field, otherwise a matching id and htmlFor. The words then become a click target as large as the row.
- Do
Write the label as a short noun (Work email) and put a rule or an example in the helper line below the field. A label is a name, not a sentence.
- Do
Mark what is unusual: the optional fields in a mostly required form, the required ones in a mostly optional form. Put the note inside the label so it is read with the name.
- Do
Keep a label for a compact control and hide it visually. A search field without a visible label still has a name and a click target for assistive technology.
- Do
Keep buttons out of the label. An info tip next to a label is a sibling in the row, so clicking it doesn't focus the field.
- Don’t
Don't use a placeholder as the label. It is gone with the first keystroke and is not announced as a name on every screen reader.
- Don’t
Don't mark required with a colour or an asterisk alone. The word Required is readable by everyone; an asterisk needs an explanation on the page.
- Don’t
Don't leave a label unjoined. Text that looks like a label but has no link to the control gives it no name and no click target.
API reference
Label renders a native label and takes all its attributes plus a ref, with no props of its own. You mostly use htmlFor (the id of the control it names), className and children.
A native label in a row, 8 px between children, in 14 px medium text. Join it to a control by id, by wrapping the control, or with FieldLabel inside a Field; clicking it focuses the control.
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("label")npx wunderui-cli add labelThe full library index for assistants is at /llms.txt.