# Label

An accessible label for a form control.

- Category: Forms
- Page: https://wunderui.com/components/label
- Tier: Free

## Install

```bash
npx wunderui-cli add label
```

## Import

```tsx
import { Label } from "@/components/ui/label"
```

## Minimal usage

Then use it:

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

## Usage

```tsx
import { Field } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <Field>
      <Label htmlFor="name" className="mb-1">
        Full name
      </Label>
      <Input id="name" placeholder="Nora Lindgren" autoComplete="name" />
    </Field>
  )
}
```

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

- [Field](https://wunderui.com/components/field) for a label, control, helper and error line that are joined for you (FieldLabel)
- [Fieldset](https://wunderui.com/components/fieldset) for the legend of a group of related controls
- [Checkbox](https://wunderui.com/components/checkbox) for a checkbox with its label and description in one clickable row
- [Tooltip](https://wunderui.com/components/tooltip) for a longer explanation next to a label, which does not fit in the helper line

## Behavior

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`: 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.
- `Requirement note`: 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.
- `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

### When to use

- Use a Label for every control with a visible name: above a field, to the left in a settings row, or to the right of a checkbox. Name a group of controls with a Fieldset legend, not a Label.

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

| Prop | Type | Default |
|---|---|---|


Also accepts React.LabelHTMLAttributes attributes.

## Examples

### Wiring: htmlFor with an id, the field inside the label, and Field

```tsx
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <div className="flex flex-col gap-1">
      <Label htmlFor="name">Full name</Label>
      <Input id="name" placeholder="Nora Lindgren" autoComplete="name" />
    </div>
  )
}
```

### Content: text, a requirement note, a link and an info tip

```tsx
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <div className="flex flex-col gap-1">
      <Label htmlFor="name">Full name</Label>
      <Input id="name" placeholder="Nora Lindgren" autoComplete="name" />
    </div>
  )
}
```

### Position: above, left, right and hidden

```tsx
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <div className="flex flex-col gap-1">
      <Label htmlFor="name">Full name</Label>
      <Input id="name" placeholder="Nora Lindgren" autoComplete="name" />
    </div>
  )
}
```

### Required mark

A red asterisk after the label marks a required field. It is decoration only; the required attribute on the field carries the meaning.

```tsx
<Label htmlFor="email">Email <span aria-hidden className="text-text-error">*</span></Label>
<Input id="email" type="email" required />
```

### Optional note

When most fields are required, mark the few that are not. The note is plain text in a lighter colour.

```tsx
<Label htmlFor="company">Company <span className="font-normal text-text-tertiary">(optional)</span></Label>
<Input id="company" />
```

### Label with a tooltip

An info button beside the label explains the field on hover and focus. Keep it outside the label.

```tsx
<div className="flex items-center gap-1.5">
  <Label htmlFor="url">Workspace URL</Label>
  <Tooltip>
    <TooltipTrigger render={<button type="button" aria-label="About the workspace URL" />}><Info className="size-4" /></TooltipTrigger>
    <TooltipContent>The address your team uses to sign in.</TooltipContent>
  </Tooltip>
</div>
<Input id="url" />
```

### Label with a badge

A badge after the label names a plan, a state or a new feature without taking room from the field.

```tsx
<div className="flex items-center gap-2">
  <Label htmlFor="domain">Custom domain</Label>
  <Badge color="indigo" badgeStyle="light" shape="pill">Pro</Badge>
</div>
<Input id="domain" />
```

### Label with a counter

The counter sits opposite the label and follows what is typed. The field's maximum length stops input at the limit.

```tsx
<div className="flex items-center justify-between">
  <Label htmlFor="name">Project name</Label>
  <span className="text-xs tabular-nums text-text-tertiary">{value.length}/{max}</span>
</div>
<Input id="name" value={value} maxLength={max} onChange={(e) => setValue(e.target.value)} />
```

### Label with a hint

A line under the field says what to enter. It is linked to the field, so a screen reader reads it with the label.

```tsx
<Label htmlFor="username">Username</Label>
<Input id="username" aria-describedby="username-hint" />
<p id="username-hint" className="text-xs text-text-tertiary">Letters, numbers and dots.</p>
```

### Label with an error

The label turns red, the field is marked invalid and the message says what to change.

```tsx
<Label htmlFor="email" className="text-text-error">Email</Label>
<Input id="email" aria-invalid aria-describedby="email-error" />
<p id="email-error" className="text-xs text-text-error">Enter a full email address.</p>
```

### Label with an edit button

The value reads as plain text until Edit turns it into a field, and Done turns it back. Use it for settings that rarely change.

```tsx
<div className="flex items-center justify-between">
  <Label htmlFor="email">Billing email</Label>
  <Button variant="link" size="sm" onClick={() => setEditing(!editing)}>{editing ? "Done" : "Edit"}</Button>
</div>
{editing ? <Input id="email" value={value} onChange={…} /> : <p id="email">{value}</p>}
```

### Label with a status

A dot and a word after the label show the state of what the field holds. The word means colour is never the only signal.

```tsx
<div className="flex items-center justify-between">
  <Label htmlFor="domain">Domain</Label>
  <span className="flex items-center gap-1.5 text-xs text-text-secondary">
    <span aria-hidden className="size-2 rounded-full bg-success" />
    Verified
  </span>
</div>
<Input id="domain" />
```

## In context

### Sign up: required and optional fields

Required fields carry a note, the optional one says so, and every label is joined to its field. Press Create account with an empty form to see the browser's rules in the tooltip.

```tsx
import { Button } from "@/components/ui/button"
import { Field } from "@/components/ui/field"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <form className="flex flex-col gap-4" onSubmit={(event) => event.preventDefault()}>
      <Field>
        <Label htmlFor="name" className="mb-1">
          Full name <span className="text-xs font-normal text-text-tertiary">Required</span>
        </Label>
        <Input id="name" placeholder="Nora Lindgren" autoComplete="name" required />
      </Field>
      <Field>
        <Label htmlFor="email" className="mb-1">
          Work email <span className="text-xs font-normal text-text-tertiary">Required</span>
        </Label>
        <Input id="email" type="email" placeholder="name@company.com" autoComplete="email" required />
      </Field>
      <Field>
        <Label htmlFor="company" className="mb-1">
          Company <span className="text-xs font-normal text-text-tertiary">Optional</span>
        </Label>
        <Input id="company" placeholder="WunderUI" autoComplete="organization" />
      </Field>
      <Button type="submit" variant="gradient">
        Create account
      </Button>
    </form>
  )
}
```

### Notifications: the label as the whole row

The label fills the row, so the whole row is the click target, not just the words. It stays regular weight because it names an option, not a field.

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"
import { Separator } from "@/components/ui/separator"

const OPTIONS = [
  { id: "mentions", label: "Mentions and replies", checked: true },
  { id: "digest", label: "Weekly digest", checked: true },
  { id: "product", label: "Product updates", checked: false },
]

export function Example() {
  return (
    <div className="flex flex-col">
      {OPTIONS.map((option, index) => (
        <div key={option.id}>
          {index > 0 && <Separator />}
          <div className="flex items-center gap-2 py-3">
            <Checkbox id={option.id} defaultChecked={option.checked} />
            <Label htmlFor={option.id} className="flex-1 cursor-pointer font-normal">
              {option.label}
            </Label>
          </div>
        </div>
      ))}
    </div>
  )
}
```

### Filter: a label only screen readers see

A search field in a toolbar has no room for a visible label. A screen-reader-only label names it and gives it a click target.

```tsx
import { Search } from "lucide-react"
import { Input } from "@/components/ui/input"
import { InputGroup, InputGroupAddon } from "@/components/ui/input-group"
import { Label } from "@/components/ui/label"

export function Example() {
  return (
    <div>
      <Label htmlFor="members" className="sr-only">
        Search members
      </Label>
      <InputGroup>
        <InputGroupAddon>
          <Search aria-hidden />
        </InputGroupAddon>
        <Input id="members" type="search" placeholder="Search members" />
      </InputGroup>
    </div>
  )
}
```

## For AI agents

`get_component("label")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
