---
title: Label
description: An accessible label associated with controls.
icon: tag
author:
  name: shadcn
  url: https://github.com/shadcn
mode: wide
---

<PoweredBy
  packages={[
    { name: 'MDN', url: 'https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label' },
    { name: 'Shadcn UI', url: 'https://ui.shadcn.com/docs/components/input' },
  ]}
/>

### Installation

```package-install
npx shadcn@latest add @redpanda/label
```

<ComponentPreview name="label-demo" />

## 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:

```mermaid
graph TD;
    A[❓ Need to label an element?] --> B{Form control present?};
    A --> C[ℹ️ Use plain text or headings];
    B --> D{Need accessibility binding?};
    B --> E[⚠️ Decorative text only?];
    D --> F[✅ Use Label with htmlFor];
    D --> G{Visual label only?};
    E --> H[ℹ️ Use span or div];
    G --> I[✅ Use Label];
    G --> J[✅ Use aria-label instead];

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef discouraged fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#000;
    classDef decision fill:#60a5fa,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef neutral fill:#9ca3af,stroke:#6b7280,stroke-width:2px,color:#fff;

    class F,I,J recommended;
    class E discouraged;
    class A,B,D,G decision;
    class C,H neutral;
```

## Usage

```tsx
<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.

```tsx
<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.

```tsx
<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.

```tsx
<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.

<div className="flex flex-row gap-x-3">
  <ExternalLink href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label" text="MDN reference" />
</div>

## 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>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label) element.
- We take our inspiration from [Shadcn UI](https://ui.shadcn.com/docs/components/label) for the label style.