# Label

Renders an accessible label associated with controls.

Source: https://webjs.dev/ui/docs/components/label

```ts
import { html } from '@webjsdev/core';
import { checkboxClass } from '#components/ui/checkbox.ts';
import { labelClass } from '#components/ui/label.ts';

export default function LabelDemo() {
  return html`
    <div class="flex gap-2">
      <input type="checkbox" data-slot="checkbox" id="terms" class=${checkboxClass()}>
      <label data-slot="label" for="terms" class=${labelClass()}>Accept terms and conditions</label>
    </div>
  `;
}
```

For form fields, use the [Field](https://webjs.dev/ui/docs/components/field) component which includes built-in label, description, and error handling.

## Installation

```bash
npx @webjsdev/ui add label
```

### Copy and paste the following code into your project.

````ts title="components/ui/label.ts"
/**
 * Label: styled native `<label>`. Tier-1 class helper. Compose with a
 * real `<label for="...">` so click-to-focus, `htmlFor` / `for` linking,
 * and screen-reader association all work natively (no Radix Label needed).
 *
 * shadcn parity:
 *   Label  → labelClass()
 *
 * Disabled-state inheritance: when the label is inside a container with
 * `data-disabled="true"` (the "field" pattern), or next to a peer-disabled
 * control, it dims automatically.
 *
 * Design tokens used: none (typography only).
 *
 * A11y (required for accessible output):
 *   Put this on a REAL `<label>`, and link it to its control, either with `for`
 *   pointing at the control's `id` (below) or by nesting the control inside the
 *   `<label>`. That link is the entire point of the element: it supplies the
 *   control's accessible name and makes clicking the text focus the control.
 *   The same classes on a `<span>` or `<div>` look identical and name nothing.
 *   One label, one control. `for` takes a single id, so a label cannot name a
 *   group; use `<fieldset>` + `<legend>`, or a heading referenced by
 *   `aria-labelledby`, for that.
 *   Do not use a label as a heading for a non-control region. A label with no
 *   control is inert; if it is really a section title, use a heading element.
 *   The dimmed disabled look is presentational only (it keys on a parent's
 *   `data-disabled` or a `peer-disabled:` sibling). Actually disable the
 *   CONTROL: styling the label alone leaves a control that still takes input.
 *
 * @example
 * ```html
 * <label class=${labelClass()} for="email">Email</label>
 * <input class=${inputClass()} id="email" name="email" type="email">
 *
 * <!-- Nesting works too, and needs no id / for pair. -->
 * <label class=${labelClass()}>
 *   <input type="checkbox" data-slot="checkbox" class=${checkboxClass()}>
 *   Email me a receipt
 * </label>
 * ```
 */

/** Compose Tailwind classes for a native `<label>`. */
export function labelClass(): string {
  return 'gap-2 text-sm leading-none font-medium group-data-[disabled=true]:opacity-50 peer-disabled:opacity-50 flex items-center select-none group-data-[disabled=true]:pointer-events-none peer-disabled:cursor-not-allowed';
}
````

### Update the import paths to match your project setup.

## Usage

```ts
import { labelClass } from '#components/ui/label.ts';
```

```ts
<label class=${labelClass()} for="email">Your email address</label>
```

## Label in Field

For form fields, use the [Field](https://webjs.dev/ui/docs/components/field) component which includes built-in `fieldLabelClass()`, `fieldDescriptionClass()`, and `fieldErrorClass()` helpers.

```ts
<div role="group" data-slot="field" class=${fieldClass()}>
  <label data-slot="field-label" for="email" class=${fieldLabelClass()}>Your email address</label>
  <input data-slot="input" id="email" class=${inputClass()}>
</div>
```

```ts
import { html } from '@webjsdev/core';
import { cn } from '#lib/utils/cn.ts';
import { buttonClass } from '#components/ui/button.ts';
import { checkboxClass } from '#components/ui/checkbox.ts';
import {
  fieldSetClass, fieldLegendClass, fieldGroupClass, fieldClass, fieldLabelClass,
  fieldDescriptionClass, fieldSeparatorClass,
} from '#components/ui/field.ts';
import { inputClass } from '#components/ui/input.ts';
import { selectTriggerClass } from '#components/ui/select.ts';
import { textareaClass } from '#components/ui/textarea.ts';

const months = ['01', '02', '03', '04', '05', '06', '07', '08', '09', '10', '11', '12'];
const years = ['2024', '2025', '2026', '2027', '2028', '2029'];

export default function FieldDemo() {
  return html`
    <div class="w-full max-w-md">
      <form>
        <div data-slot="field-group" class=${fieldGroupClass()}>
          <fieldset data-slot="field-set" class=${fieldSetClass()}>
            <legend data-slot="field-legend" data-variant="legend" class=${fieldLegendClass()}>Payment Method</legend>
            <p data-slot="field-description" class=${fieldDescriptionClass()}>
              All transactions are secure and encrypted
            </p>
            <div data-slot="field-group" class=${fieldGroupClass()}>
              <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
                <label data-slot="field-label" for="checkout-7j9-card-name-43j" class=${fieldLabelClass()}>
                  Name on Card
                </label>
                <input data-slot="input" id="checkout-7j9-card-name-43j" placeholder="Evil Rabbit" required class=${inputClass()}>
              </div>
              <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
                <label data-slot="field-label" for="checkout-7j9-card-number-uw1" class=${fieldLabelClass()}>
                  Card Number
                </label>
                <input data-slot="input" id="checkout-7j9-card-number-uw1" placeholder="1234 5678 9012 3456" required class=${inputClass()}>
                <p data-slot="field-description" class=${fieldDescriptionClass()}>
                  Enter your 16-digit card number
                </p>
              </div>
              <div class="grid grid-cols-3 gap-4">
                <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
                  <label data-slot="field-label" for="checkout-exp-month-ts6" class=${fieldLabelClass()}>
                    Month
                  </label>
                  <ui-select placeholder="MM">
                    <select id="checkout-exp-month-ts6" class=${selectTriggerClass()}>
                      <option value="" disabled selected hidden>MM</option>
                      ${months.map((m) => html`<option value=${m}>${m}</option>`)}
                    </select>
                  </ui-select>
                </div>
                <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
                  <label data-slot="field-label" for="checkout-7j9-exp-year-f59" class=${fieldLabelClass()}>
                    Year
                  </label>
                  <ui-select placeholder="YYYY">
                    <select id="checkout-7j9-exp-year-f59" class=${selectTriggerClass()}>
                      <option value="" disabled selected hidden>YYYY</option>
                      ${years.map((y) => html`<option value=${y}>${y}</option>`)}
                    </select>
                  </ui-select>
                </div>
                <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
                  <label data-slot="field-label" for="checkout-7j9-cvv" class=${fieldLabelClass()}>CVV</label>
                  <input data-slot="input" id="checkout-7j9-cvv" placeholder="123" required class=${inputClass()}>
                </div>
              </div>
            </div>
          </fieldset>
          <div data-slot="field-separator" data-content="false" class=${fieldSeparatorClass()}></div>
          <fieldset data-slot="field-set" class=${fieldSetClass()}>
            <legend data-slot="field-legend" data-variant="legend" class=${fieldLegendClass()}>Billing Address</legend>
            <p data-slot="field-description" class=${fieldDescriptionClass()}>
              The billing address associated with your payment method
            </p>
            <div data-slot="field-group" class=${fieldGroupClass()}>
              <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
                <input type="checkbox" data-slot="checkbox" id="checkout-7j9-same-as-shipping-wgm" checked class=${checkboxClass()}>
                <label data-slot="field-label" for="checkout-7j9-same-as-shipping-wgm" class=${cn(fieldLabelClass(), 'font-normal')}>
                  Same as shipping address
                </label>
              </div>
            </div>
          </fieldset>
          <fieldset data-slot="field-set" class=${fieldSetClass()}>
            <div data-slot="field-group" class=${fieldGroupClass()}>
              <div role="group" data-slot="field" data-orientation="vertical" class=${fieldClass()}>
                <label data-slot="field-label" for="checkout-7j9-optional-comments" class=${fieldLabelClass()}>
                  Comments
                </label>
                <textarea data-slot="textarea" id="checkout-7j9-optional-comments" placeholder="Add any additional comments" class=${cn(textareaClass(), 'resize-none')}></textarea>
              </div>
            </div>
          </fieldset>
          <div role="group" data-slot="field" data-orientation="horizontal" class=${fieldClass({ orientation: 'horizontal' })}>
            <button type="submit" data-slot="button" data-variant="default" data-size="default" class=${buttonClass()}>Submit</button>
            <button type="button" data-slot="button" data-variant="outline" data-size="default" class=${buttonClass({ variant: 'outline' })}>
              Cancel
            </button>
          </div>
        </div>
      </form>
    </div>
  `;
}
```

## RTL

To enable RTL support, see the [RTL configuration guide](https://webjs.dev/ui/docs/rtl).

```ts
import { html } from '@webjsdev/core';
import { checkboxClass } from '#components/ui/checkbox.ts';
import { labelClass } from '#components/ui/label.ts';

const translations = {
  en: {
    dir: 'ltr',
    values: {
      label: 'Accept terms and conditions',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      label: 'قبول الشروط والأحكام',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      label: 'קבל תנאים והגבלות',
    },
  },
};

export default function LabelRtl() {
  const lang = 'ar';
  const { dir, values: t } = translations[lang];

  return html`
    <div class="flex gap-2" dir=${dir} lang=${lang}>
      <input type="checkbox" data-slot="checkbox" id="terms-rtl" class=${checkboxClass()}>
      <label data-slot="label" for="terms-rtl" class=${labelClass()}>${t.label}</label>
    </div>
  `;
}
```

## API Reference

### labelClass

`labelClass()` returns the classes for a native `<label>` and takes no options. Link the label to its control with `for` pointing at the control's `id`, or nest the control inside the label. That link supplies the control's accessible name and makes clicking the text focus the control, with no script.

The label dims on its own inside a container marked `data-disabled="true"`, or next to a disabled `peer` control. The dimming is visual only, so disable the control itself.
