Label

Form label — the name of a control: above a field, beside a checkbox or a switch.

Beta · Forms · packages/css/src/components/label.css · React on Base UI: @pepperui/label

.pui-label · __hint · --disabled — the name of a control on its own.

Label — every size and every stateOpen in the workshop

Sizes across, states down.

What it is for

• Label is a text property; Hint is a second text in text/muted behind Has hint — an optional field says ‘(optional)’, never an asterisk, and no required mark exists
• States default and disabled (0.5 opacity, together with its control; Field does the same)
• One size: 14 at every control size, and Field keeps it so
• No margin of its own: the row (space/8 beside a Checkbox or Switch) belongs to the consumer’s auto-layout

Use when a control needs a visible name without the Field wrapper — a checkbox or switch row, a radio group’s items, an inline control in a toolbar or a dialog.

Do not use when the control is an Input, Select or Textarea in a form — that is Field, which carries this label with a description and an error; for a heading over a group of fields (that is text on a Heading pair or a section title).

Relates to Field, Checkbox, Radio, Switch, Input, Select.

Anti-patterns an asterisk for required · a label in ALL CAPS or Title Case (Writing rules) · a label that is a sentence · a label with no control · a colour changed on the instance.

Keywords: label, form, field, caption, name, checkbox row

Figma — page Label: Label (2 variants)

shadcn: label

The markup — copy this

The class, the parts, and nothing that is not in the package. The same block opens label.css.

<label class="pui-label" for="name">Name <span class="pui-label__hint">(optional)</span></label>

Accessibility — measured, not assumed

Every number here is measured on the rendered component: contrast (npm run contrast:render), the focus ring (npm run focus) and the keyboard (npm run keyboard). The floors are principle 12’s.

Contrast

ink on ground	reads	floor	the matrix calls it
#858181 on #ffffff	3.85	—	not a token pair (off-token)	axe
#544d4d on #ffffff	8.24	4.5	text.muted on surface.page (promised)	ok
#0b0202 on #ffffff	20.51	4.5	text.default on surface.page (promised)	ok

3 distinct pair(s) rendered, 1 that axe calls a violation — each one carries its reason in storybook/test/axe-allowlist.json.

The focus ring

Nothing in this component takes focus.

Keyboard

Nothing in this component claims an ARIA role with a keyboard contract; its controls are ordinary ones and the browser already gives them their keys.

Tab order across the whole library is document order over 344 stops, and Shift+Tab is its exact reverse — no keyboard trap anywhere (WCAG 2.1.2).