# Label

> A visible name for a form control, linked to it by id.

- Name: `label`
- Status: beta
- Categories: forms
- File: the install writes `label.tsx` to your `ui` alias, `@/components/ui` by default.
- Gallery: https://arbokui.com/components/label
- Registry item: https://arbokui.com/r/label.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the component:

   ```bash
   npx shadcn@latest add @arbokui/label
   ```

## Use it for

- Naming an input, textarea, checkbox, or switch with text people can see.
- Give the control an id and pass the same value to htmlFor. Clicking the label then focuses an input or toggles a checkbox.
- Checkbox and Switch can also take their text as children. That needs no Label at all.
- Set disabled on the label when its control is disabled, so both look the same.
- Put short extra words, like (optional), inside the label in a muted span.

## Avoid it for

- Naming a group of controls, like a set of radio buttons. Use a fieldset with a legend.
- Help text or error messages. Put them in a separate element and link it with aria-describedby.
- Hiding the label to save space. If there is truly no room, give the control an aria-label instead.

## Props

- `htmlFor`: `string`. The id of the control it names. TypeScript requires it, so a label is never left unlinked.
- `disabled`: `boolean`. Default `false`. Dims the label and shows a not-allowed cursor. It does not disable the control.
- `className`: `string`. Extra classes. Later classes win, so className='text-base' replaces the text size.

## Accessibility

- Renders a native \<label>. Screen readers read its text as the control's name.
- Clicking the label focuses an input or textarea, and toggles a checkbox or switch.
- htmlFor is required at the type level, so an agent cannot ship a label that names nothing.
- Text uses --foreground, which the theme tests hold to 4.5:1 against the page.
- disabled only changes the look. Disable the control too, or keyboard users can still reach it.

## Examples

### Above an input

```tsx
<div className="grid gap-2">
  <Label htmlFor="project-name">Project name</Label>
  <input id="project-name" className="h-10 rounded-md border border-input px-3" />
</div>
```

### With a hint inside the label

```tsx
<Label htmlFor="nickname">
  Nickname <span className="font-normal text-muted-foreground">(optional)</span>
</Label>
```

### Next to a checkbox

```tsx
<div className="flex items-center gap-2">
  <input type="checkbox" id="newsletter" />
  <Label htmlFor="newsletter">Send me the monthly newsletter</Label>
</div>
```

### For a disabled control

```tsx
<div className="grid gap-2">
  <Label htmlFor="plan" disabled>
    Plan
  </Label>
  <input id="plan" defaultValue="Team" disabled className="h-10 rounded-md border border-input px-3" />
</div>
```