# dds-checkbox

<!-- Auto Generated Below -->


## Overview

A single checkbox control for a binary choice, or a partial one when indeterminate. It is form-associated, so it submits its own `name` and `value` and responds to `form.reset()`.

## Usage

### Checkbox

A single checkbox for a binary choice. Put the label text in the default slot.

```html
<dds-checkbox name="terms" value="accepted">Accept the terms and conditions</dds-checkbox>
```

#### Form behaviour

`dds-checkbox` is itself the form control. It submits `name` and `value` when `checked`, and submits `on` when no `value` is set. It resets with `form.reset()` and is disabled by an ancestor `<fieldset disabled>`.

`checked` is live, not controlled. The attribute sets the starting state and the property follows the user. A framework that re-renders with a stale `checked` will fight the component, so bind to the `ddsChange` event and read `checked` from its `detail`.

```html
<form>
  <dds-checkbox name="newsletter" checked>Send me the newsletter</dds-checkbox>
</form>
```

Set `required` to make the checkbox invalid until it is checked. The browser supplies the validation message.

```html
<dds-checkbox name="terms" required>Accept the terms and conditions</dds-checkbox>
```

#### Label, hint and end content

The default slot is the accessible name. Put supporting text in the `hint` attribute; it is shown below the label and announced as the checkbox's description. Put an inline element after the label in the `end` slot.

```html
<dds-checkbox name="plan" value="premium" hint="Advanced features for professionals">
  Premium plan
  <span slot="end">Recommended</span>
</dds-checkbox>
```

With no visible label, name the checkbox with `aria-label` on the host. Do not use `aria-labelledby` or `aria-describedby` on the host: an id reference cannot cross the shadow boundary, so they are not forwarded.

```html
<dds-checkbox aria-label="Select this row"></dds-checkbox>
```

#### States

Use `indeterminate` for a partial selection, such as a "select all" over a partly selected list. The user toggling the checkbox clears it.

```html
<dds-checkbox indeterminate aria-label="Select all"></dds-checkbox>
```

Set `error` to a message to mark the checkbox invalid. The message is shown below the label, announced with `aria-invalid`, and becomes the checkbox's custom validity message, so the form cannot submit while it is set. Clear it to make the checkbox valid again. `disabled` removes the checkbox from the tab order and from the form. `readonly` keeps the checkbox focusable but stops the user changing it.

```html
<dds-checkbox error="You must accept the terms to continue">Accept the terms</dds-checkbox>
<dds-checkbox disabled>Disabled</dds-checkbox>
<dds-checkbox readonly checked>Read-only</dds-checkbox>
```

#### Size, shape and decoration

`size` is `s` or `m`. `shape` is `square` or `circle`. `decoration` strikes the label through while the checkbox is checked or indeterminate.

```html
<dds-checkbox size="s" shape="circle" decoration checked>Done</dds-checkbox>
```

#### Events

`dds-checkbox` emits `ddsChange` when the user changes the checked state, with `checked` and `value` in `detail`. Setting `checked` from code does not emit it. It also emits `ddsFocus` and `ddsBlur`, which bubble where native `focus` and `blur` do not. In React, bind them as `onddsChange`, `onddsFocus` and `onddsBlur`.

```js
document.querySelector("dds-checkbox").addEventListener("ddsChange", (event) => {
  console.log(event.detail.checked);
});
```

#### Keyboard

The checkbox follows the [WAI-ARIA Authoring Practices checkbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/checkbox/): Space toggles it, and Tab moves focus to and from it. There is no deviation.



## Properties

| Property        | Attribute       | Description                                                                                                              | Type                   | Default     |
| --------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------ | ---------------------- | ----------- |
| `checked`       | `checked`       | Whether the checkbox is checked. The attribute is the default; the property follows user input.                          | `boolean`              | `false`     |
| `decoration`    | `decoration`    | Strikes through the label while the checkbox is checked or indeterminate.                                                | `boolean`              | `false`     |
| `disabled`      | `disabled`      | Prevents interaction and removes the checkbox from the tab order.                                                        | `boolean`              | `false`     |
| `error`         | `error`         | An error message shown below the label. While set, the checkbox is invalid, styled as an error and announced as invalid. | `string \| undefined`  | `undefined` |
| `hint`          | `hint`          | Supporting text shown below the label and announced as the checkbox's description.                                       | `string \| undefined`  | `undefined` |
| `indeterminate` | `indeterminate` | Shows the partial-selection state. Cleared when the user toggles the checkbox.                                           | `boolean`              | `false`     |
| `name`          | `name`          | The name submitted with the form.                                                                                        | `string \| undefined`  | `undefined` |
| `readonly`      | `readonly`      | Prevents the user from changing the checked state while keeping the checkbox focusable.                                  | `boolean`              | `false`     |
| `required`      | `required`      | Makes the checkbox invalid until it is checked.                                                                          | `boolean`              | `false`     |
| `shape`         | `shape`         | Whether the control's corners are square or fully rounded.                                                               | `"circle" \| "square"` | `"square"`  |
| `size`          | `size`          | Which step of the size scale to render at.                                                                               | `"m" \| "s"`           | `"m"`       |
| `value`         | `value`         | The value submitted with the form when checked. Submits `on` when omitted.                                               | `string \| undefined`  | `undefined` |


## Events

| Event       | Description                                                                                                                     | Type                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `ddsBlur`   | Emitted when the checkbox loses focus.                                                                                          | `CustomEvent<void>`                      |
| `ddsChange` | Emitted when the user changes the checked state. This event will not emit when programmatically setting the `checked` property. | `CustomEvent<CheckboxChangeEventDetail>` |
| `ddsFocus`  | Emitted when the checkbox has focus.                                                                                            | `CustomEvent<void>`                      |


## Slots

| Slot    | Description                                    |
| ------- | ---------------------------------------------- |
|         | The label text.                                |
| `"end"` | Content shown after the label, such as a chip. |


## Shadow Parts

| Part     | Description                                   |
| -------- | --------------------------------------------- |
| `"root"` | The outermost element inside the shadow root. |


## Custom States

| State                   | Initial Value | Description |
| ----------------------- | ------------- | ----------- |
| `:state(checked)`       | `false`       |             |
| `:state(indeterminate)` | `false`       |             |
| `:state(invalid)`       | `false`       |             |


## Dependencies

### Depends on

- [dds-icon](../icon)

### Graph
```mermaid
graph TD;
  dds-checkbox --> dds-icon
  style dds-checkbox fill:#f9f,stroke:#333,stroke-width:4px
```

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

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