# Label

Renders an accessible caption for a form control.

```tsx
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function LabelDemo() {
  return (
    <VStack gap={2} xstyle={widths.xs}>
      <Label htmlFor="label-demo-email">Email</Label>
      <Input id="label-demo-email" type="email" placeholder="me@example.com" />
    </VStack>
  )
}
```

## Installation

**Command**

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

Needs the [arene setup](https://www.arene.style/docs/installation) first.

**Manual**

1. Install the packages it imports:

   ```bash
   npm install @base-ui/react @stylexjs/stylex clsx
   ```

2. Set up the token layer and the StyleX compiler, if you have not already. See
   [Installation](https://www.arene.style/docs/installation), and paste `states.ts` from the same page,
   which is where the dimmed disabled label comes from. The label also needs
   `interop.css`, which sizes an icon the label does not render.

3. Paste this source into the file named in its title.

   ```tsx title="components/ui/label.tsx"
   "use client"

   import { useRender } from "@base-ui/react/use-render"
   import * as stylex from "@stylexjs/stylex"
   import type { StyleXStyles } from "@stylexjs/stylex"
   import { clsx } from "clsx"

   import { states } from "@/theme/states"
   import { space, text } from "@/theme/tokens.stylex"

   const styles = stylex.create({
     base: {
       display: "flex",
       alignItems: "center",
       gap: space.s2,
       userSelect: "none",
       fontSize: text.sm,
       lineHeight: 1,
       fontWeight: 500,
       "--arene-icon-size": space.s4,
     },
   })

   const labelStyles = { base: styles.base, disabled: states.disabled }

   type LabelProps = useRender.ComponentProps<"label", { disabled: boolean | undefined }> & {
     disabled?: boolean
     xstyle?: StyleXStyles
     className?: string
   }

   function Label({ render, ref, style, disabled, xstyle, className, ...props }: LabelProps) {
     const sx = stylex.props(styles.base, disabled && states.disabled, xstyle)

     return useRender({
       defaultTagName: "label",
       render,
       ref,
       state: { disabled },
       props: {
         "data-slot": "label",
         ...sx,
         ...props,
         className: clsx("arene-icons", sx.className, className),
         style: { ...sx.style, ...style },
       },
     })
   }

   export { Label, labelStyles }
   ```

4. Change the `@/` imports if your project uses different aliases.

## Usage

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

```tsx
<Label htmlFor="email">Email</Label>
<Input id="email" type="email" />
```

## Disabled

Use the `disabled` prop to dim the label and take it out of the hit test. It is
a prop rather than an inherited state. Inside a [Field](https://www.arene.style/docs/components/field)
the `FieldLabel` reads it from the field; a bare label has nothing to read it
from.

```tsx
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
import { VStack } from "@/components/ui/stack"
import { widths } from "@/theme/widths"

export default function LabelDisabled() {
  return (
    <VStack gap={2} xstyle={widths.xs}>
      <Label htmlFor="label-disabled-plan" disabled>
        Billing plan
      </Label>
      <Input id="label-disabled-plan" defaultValue="Enterprise" disabled />
    </VStack>
  )
}
```

## Content

The label is a flex row with a `0.5rem` gap, so an icon or a
[Badge](https://www.arene.style/docs/components/badge) sits beside the text without extra markup.

```tsx
import { Badge } from "@/components/ui/badge"
import { Input } from "@/components/ui/input"
import { Label } from "@/components/ui/label"
import { VStack } from "@/components/ui/stack"
import { LockSimpleIcon } from "@phosphor-icons/react/dist/csr/LockSimple"
import { widths } from "@/theme/widths"

export default function LabelContent() {
  return (
    <VStack gap={2} xstyle={widths.xs}>
      <Label htmlFor="label-content-secret">
        <LockSimpleIcon aria-hidden="true" />
        Signing secret
        <Badge variant="secondary">Recommended</Badge>
      </Label>
      <Input id="label-content-secret" type="password" placeholder="whsec_..." />
    </VStack>
  )
}
```

> **Note**
>
> Give the label either an `htmlFor` matching the control's `id` or the control
> itself as a child. Without one of the two the label is decoration, and clicking
> it does not focus anything.

## API reference

Pass `render` to replace a part's element or compose it with another component.

`Label` renders a `<label>` and accepts every `<label>` attribute.

### Label

| Prop        | Type           | Default |
| ----------- | -------------- | ------- |
| `disabled`  | `boolean`      | `false` |
| `htmlFor`   | `string`       | —       |
| `xstyle`    | `StyleXStyles` | —       |
| `className` | `string`       | —       |

The line height is `1` rather than the `sm` leading the type scale pairs with
`text.sm`. A label is one line. With the tight box, the stack's gap alone sets the
distance to the control below.

### labelStyles

The style maps behind the component. Spread them onto any element.

| Key        | What it is                            |
| ---------- | ------------------------------------- |
| `base`     | The row: gap, type, weight, icon size |
| `disabled` | The dimmed, non-interactive state     |

`disabled` is `states.disabled` from `theme/states.ts`, the same dimmed style
every control uses.

### Data attributes

| Attribute           | On        | Effect                          |
| ------------------- | --------- | ------------------------------- |
| `data-slot="label"` | the label | Targets the label from a parent |
| `data-disabled`     | the label | Present when `disabled` is set  |
