# Chip

## Overview

The chip component presents compact native selection options with a rounded visual treatment.

Use `label.chip` with a direct child checkbox or radio input when the chip is a selectable form option. Use `span.badge` for display-only labels and status values.

## When to use

Use chips when a small checkbox or radio group should scan as compact selectable options while retaining native form behavior. Add `data-variant="error"`, `data-variant="info"`, `data-variant="success"`, or `data-variant="warning"` for a variant color treatment.

## When not to use

Do not use chips for display-only values, links, actions, or when the native checkbox or radio shape should remain visible; use a badge, link, button, checkbox, or radio.

## Usage

Keep the native input as a direct child of the label and wrap the visible label text in a child span:

```html
<fieldset>
  <legend>Notification channels</legend>
  <div class="cluster">
    <label class="chip">
      <input type="checkbox" name="channels" value="email" checked />
      <span>Email</span>
    </label>
    <label class="chip">
      <input type="checkbox" name="channels" value="sms" />
      <span>SMS</span>
    </label>
    <label class="chip" data-variant="success">
      <input type="checkbox" name="channels" value="push" />
      <span>Push enabled</span>
    </label>
  </div>
</fieldset>
```

Radio chips use the same label pattern:

```html
<fieldset>
  <legend>Approval priority</legend>
  <div class="cluster">
    <label class="chip">
      <input type="radio" name="priority" value="standard" checked />
      <span>Standard</span>
    </label>
    <label class="chip">
      <input type="radio" name="priority" value="expedited" />
      <span>Expedited</span>
    </label>
  </div>
</fieldset>
```

Selected chips use the filled default-button treatment. Unselected chips use a white background with a base-color outline and strong-color text; variant color chips use their corresponding variant colors when selected or activated.

Use the existing checkbox or radio components when the native control shape should remain visible.

Do not use the chip class on display, link, or button elements; those are not part of this component's public API.

## Behavior

Covered by [Playwright behavior tests](../../tests/e2e/forms-inputs.spec.js).

- CHP-001: Chips hide the native checkbox or radio visually while preserving native input semantics.
- CHP-002: Checked chips use the filled default-button treatment.
- CHP-003: Unchecked chips use a white background, base-color outline, and strong-color text.
- CHP-005: Chip color changes should transition smoothly, with reduced-motion preferences disabling the transition.
- CHP-006: Disabled chips use disabled surface and text tokens and the not-allowed cursor.
- CHP-007: Keyboard focus on a hidden selectable input appears on the visible chip surface.
- CHP-008: Individual chips stay on one line; use `.cluster` to wrap groups of chips.
- CHP-009: Chips use a fixed pill radius by default and can override it with `--chip-border-radius`.
- CHP-010: Chip groups suppress native fieldset border, margin, and padding so they match checkbox and radio group chrome.
- CHP-012: Chips support color variants through `data-variant` without requiring a color class.
- CHP-014: Activated chips use the same strong pressed surface, border, and inverse text color as buttons.
## Accessibility

- Use native checkbox and radio inputs for chips so form submission, grouping, disabled state, and assistive technology semantics remain intact.
- Group chips in a native `<fieldset>` with a `<legend>`.
- Keep chip text short and descriptive.
- Mark decorative icons with `aria-hidden="true"`.
- Do not rely on color alone when a status value needs to communicate critical information; include clear text.

## Variables

| Variable | Type | Description |
| --- | --- | --- |
| `--chip-background` | `<color>` | Sets the chip fill color for resting, selected, and disabled states; change it to tune the chip treatment for a status or selection context. |
| `--chip-border-color` | `<color>` | Sets the chip outline color; change it when selectable chips need more or less edge contrast. |
| `--chip-border-radius` | `<length>` | Sets the chip corner shape; change it to move chips away from the default pill treatment. |
| `--chip-color-focus-ring` | `<color>` | Sets --chip-color-focus-ring so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-color-text` | `<color>` | Sets the chip label and icon color; change it when the fill or selected state needs a different contrast pairing. |
| `--chip-color-text-accent` | `<color>` | Sets the chip group legend color; change it when chip groups need stronger or subtler label emphasis. |
| `--chip-control-border-width` | `<length>` | Sets --chip-control-border-width so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-control-gap` | `<length>` | Sets --chip-control-gap so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-control-padding-inline` | `<length>` | Sets --chip-control-padding-inline so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-focus-ring-size` | `<length>` | Sets --chip-focus-ring-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-font-family-sans` | `Any` | Sets --chip-font-family-sans so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-font-size` | `<length>` | Sets --chip-font-size so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-font-size-caption` | `<length>` | Sets --chip-font-size-caption so the component can default to shared theme or layout tokens while exposing an overrideable component API. |
| `--chip-icon-size` | `<length>` | Sets the icon size inside chips; change it when chip icons should be balanced differently against the label text. |
| `--chip-line-height` | `<number>` | Sets --chip-line-height so the component can default to shared theme or layout tokens while exposing an overrideable component API. |

## Depends On

- `--color-accent-disabled`
- `--color-error`
- `--color-error-strong`
- `--color-focus-ring`
- `--color-info`
- `--color-info-strong`
- `--color-primary`
- `--color-primary-strong`
- `--color-success`
- `--color-success-strong`
- `--color-text-accent`
- `--color-text-inverse`
- `--color-text-subtle`
- `--color-warning`
- `--color-warning-strong`
- `--font-family-sans`
- `--font-line-height-body`
- `--font-size`
- `--font-size-caption`
- `--layout-control-border-width`
- `--layout-control-gap`
- `--layout-control-padding-inline`
- `--layout-focus-ring-size`