# xpl-checkbox

Checkboxes allow users to make selections or choices. Checkboxes can be multi-select, and also act as controls.

Provide visible label text in the default slot, or set `aria-label` when the checkbox has no adjacent label (for example, icon-only toolbars or table selection cells).

## Design Tokens

The checkbox component uses the following Apollo Foundation tokens:

| Token | Usage |
|-------|-------|
| `--xpl-background-surface-default` | Default checkbox background; styled label background (resting/hover/focused) |
| `--xpl-background-action-primary-default` | Checked/indeterminate state background and border |
| `--xpl-background-action-disabled` | Disabled state background; disabled label background (styled variant) |
| `--xpl-background-surface-information` | Checked/indeterminate label background (styled variant) |
| `--xpl-text-inverse` | Checkmark and indeterminate icon color (checked / indeterminate states; inverse foreground on primary fill) |
| `--xpl-icon-disabled` | Checkmark and indeterminate icon color (disabled state) |
| `--xpl-border-strong` | Resting (unchecked) border color |
| `--xpl-border-hover` | Hover, checked, and indeterminate border color; styled container hover/focus border |
| `--xpl-border-default` | Styled container border; disabled state border |
| `--xpl-border-focus` | Focus visible outline |
| `--xpl-border-radius-small` | Checkbox corner radius and styled container corner radius (4px) |
| `--xpl-border-small` | Border width (1px) |
| `--xpl-size-100` | Checkbox dimensions (16px) |

<!-- Auto Generated Below -->


## Properties

| Property        | Attribute       | Description                                                                                                                                                                                                                                                                          | Type      | Default     |
| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ----------- |
| `ariaLabel`     | `aria-label`    | Accessible name for the native checkbox input (sets `aria-label` on the `input`). Use when there is no visible label text in the default slot. Defaults to `''`; empty or whitespace-only values omit `aria-label` on the input so a visible `<label>` remains the sole name source. | `string`  | `''`        |
| `checked`       | `checked`       | Whether the input is checked                                                                                                                                                                                                                                                         | `boolean` | `undefined` |
| `dataId`        | `data-id`       | A custom data attribute for the checkbox                                                                                                                                                                                                                                             | `string`  | `undefined` |
| `description`   | `description`   | Description text for the field                                                                                                                                                                                                                                                       | `string`  | `undefined` |
| `disabled`      | `disabled`      | Whether the input is disabled                                                                                                                                                                                                                                                        | `boolean` | `undefined` |
| `indeterminate` | `indeterminate` | A visual state for when the input has not been interacted with                                                                                                                                                                                                                       | `boolean` | `undefined` |
| `name`          | `name`          | The name attribute for the html input. (submitted in form as name/value pair)                                                                                                                                                                                                        | `string`  | `undefined` |
| `required`      | `required`      | Whether the input is required                                                                                                                                                                                                                                                        | `boolean` | `undefined` |
| `styled`        | `styled`        | Whether the input is contained in a box with a border and a background                                                                                                                                                                                                               | `boolean` | `undefined` |
| `value`         | `value`         | The value attribute for the checkbox input. (submitted in form as name/value pair)                                                                                                                                                                                                   | `string`  | `undefined` |


## Events

| Event            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Type                   |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
| `checkboxChange` | Emits the new checked state of the checkbox after a user interaction.  Always emits a boolean so the event payload reliably represents whether the checkbox is now on or off. This is what Vue `v-model` binds to via the `checked` attribute — emitting the `value` string here would coerce any non-empty string to `true` and make it impossible to uncheck a checkbox that has a `value` prop set. Consumers that need the `value` can read it from the host element (`event.target.value`) or rely on native form submission (`name`/`value` pair). | `CustomEvent<boolean>` |


## Dependencies

### Used by

 - [xpl-choicelist](../xpl-choicelist)
 - [xpl-header-accordion](../xpl-header-accordion)
 - [xpl-table](../xpl-table)
 - [xpl-table-header-cell](../xpl-table-header-cell)

### Graph
```mermaid
graph TD;
  xpl-choicelist --> xpl-checkbox
  xpl-header-accordion --> xpl-checkbox
  xpl-table --> xpl-checkbox
  xpl-table-header-cell --> xpl-checkbox
  style xpl-checkbox fill:#f9f,stroke:#333,stroke-width:4px
```

----------------------------------------------

*Built with [StencilJS](https://stenciljs.com/)*