Label

An accessible label associated with controls.

Powered by

MDNShadcn UI

Installation

npx shadcn@latest add @redpanda/label

pnpm dlx shadcn@latest add @redpanda/label

yarn dlx shadcn@latest add @redpanda/label

bunx shadcn@latest add @redpanda/label

nubx shadcn@latest add @redpanda/label

aube dlx shadcn@latest add @redpanda/label

When to use

The Label component provides accessible text labels for form controls and interactive elements. Use this decision tree to determine when it’s appropriate:

Usage

<Label htmlFor="email">Your email address</Label>

Inset alignment

Use inset to align label text with adjacent field controls. It adds one spacing unit of horizontal padding; the default label remains unpadded. Keep htmlFor associated with the control in either treatment.

<Label htmlFor="start-date" inset>  Start date</Label>

Option labels

Use variant="option" for the normal-weight text beside a checkbox, radio, or switch. The default treatment stays medium-weight. FieldLabel and FormLabel also accept this variant; keep validation state on the owning Field or form.

<Label htmlFor="weekly-updates" variant="option">  Weekly updates</Label>

Choice surfaces

When a label is the entire hit area of a checkbox or radio, use a closed surface recipe rather than restyling the label: card, pill, attached, tile, or compact-card. default is an ordinary text label. Checked, disabled, and keyboard focus states come from the actual nested control or preceding peer control; do not mirror checked state into appearance classes. Content layout and hit-area dimensions remain caller-owned. FormLabel forwards these same recipes.

<Label htmlFor="retention" surface="card">  <Checkbox id="retention" />  Keep archived records</Label>

A tile may follow a visually hidden peer radio. Its keyboard ring remains visible on the label, and disabled tiles do not pick up an enabled hover treatment.

Props

• surface: default, card, pill, attached, tile, or compact-card; a closed whole-choice treatment.
• variant: default (medium weight), option (normal weight), or strong (semibold nested-field text).
• size: sm (small body text), default (label text), or lg (large body text). FormLabel and FieldLabel accept the same sizes.
• invalid: optional boolean, defaults to false. Uses the validation-error text color; set aria-invalid on the associated control, not the label.
• inset: optional boolean, defaults to false. Adds horizontal field-label padding.

Accessibility

• Always set htmlFor to the id of the control being labelled — clicking the label then focuses / activates the control.
• For checkboxes, switches, and radios you can alternatively wrap the control inside the label (no htmlFor needed).
• The component is a plain <label> — no keyboard interactions of its own.

Credits

• We use the native <label> element.
• We take our inspiration from Shadcn UI for the label style.