# `src/components/checkbox/Checkbox.ts`:

## class: `Checkbox`, `btu-checkbox`

### Superclass

| Name         | Module | Package |
| ------------ | ------ | ------- |
| `LitElement` |        | lit     |

### Mixins

| Name                | Module                         | Package |
| ------------------- | ------------------------------ | ------- |
| `EventEmitterMixin` | /src/util/EventEmitterMixin.js |         |
| `ReadyMixin`        | /src/util/ReadyMixin.js        |         |

### Fields

| Name                      | Privacy | Type                  | Default                                       | Description                                                                                                                                                                                                     | Inherited From |
| ------------------------- | ------- | --------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
| `label`                   |         | `string \| undefined` |                                               | The text label displayed next to the checkbox.                                                                                                                                                                  |                |
| `description`             |         | `string \| undefined` |                                               | Optional helper text displayed below the label.                                                                                                                                                                 |                |
| `size`                    |         | `'sm' \| 'md'`        | `'sm'`                                        | Controls the scale of the checkbox and associated typography.                                                                                                                                                   |                |
| `checked`                 |         | `boolean`             | `false`                                       | Whether the checkbox is currently selected.                                                                                                                                                                     |                |
| `indeterminate`           |         | `boolean`             | `false`                                       | Whether the checkbox is in a partially selected state. Sets \`aria-checked='mixed'\`&#xA;and activates the native \`:indeterminate\` pseudo-class. Cleared automatically when&#xA;the user clicks the checkbox. |                |
| `disabled`                |         | `boolean`             | `false`                                       | If true, the checkbox is non-interactive and visually muted.                                                                                                                                                    |                |
| `invalid`                 |         | `boolean`             | `false`                                       | If true, displays error styling on the checkbox.                                                                                                                                                                |                |
| `error`                   |         | `string \| undefined` |                                               | Error message text displayed below the checkbox when validation fails.&#xA;Setting this also activates error styling without needing to set invalid.                                                            |                |
| `required`                |         | `boolean`             | `false`                                       | Marks the field as mandatory for form submission.                                                                                                                                                               |                |
| `name`                    |         | `string \| undefined` |                                               | Name of the form control submitted with the form data.                                                                                                                                                          |                |
| `value`                   |         | `string`              | `'on'`                                        | Value associated with the checkbox when submitted.                                                                                                                                                              |                |
| `_userInitiated`          | private | `boolean`             | `false`                                       |                                                                                                                                                                                                                 |                |
| `_initialClasses`         | private | `string[]`            | `[]`                                          |                                                                                                                                                                                                                 |                |
| `_initialClassesCaptured` | private | `boolean`             | `false`                                       |                                                                                                                                                                                                                 |                |
| `_descId`                 | private |                       | `` `checkbox-desc-${crypto.randomUUID()}` ``  |                                                                                                                                                                                                                 |                |
| `_errorId`                | private |                       | `` `checkbox-error-${crypto.randomUUID()}` `` |                                                                                                                                                                                                                 |                |
| `_handleClick`            | private |                       |                                               |                                                                                                                                                                                                                 |                |
| `_describedBy`            | private | `string \| undefined` |                                               |                                                                                                                                                                                                                 |                |
| `_iconSymbol`             | private | `'minus' \| 'check'`  |                                               |                                                                                                                                                                                                                 |                |

### Methods

| Name             | Privacy | Description                                                                                                                                                                                                                                                                        | Parameters                                              | Return    | Inherited From    |
| ---------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | --------- | ----------------- |
| `_onInputChange` | private |                                                                                                                                                                                                                                                                                    | `e: Event`                                              | `void`    |                   |
| `emit`           |         | Dispatches a type-safe CustomEvent with standardized configuration.&#xA;&#xA;All events are configured with:&#xA;- bubbles: true (event propagates up the DOM tree)&#xA;- cancelable: false (event cannot be cancelled)&#xA;- composed: true (event crosses shadow DOM boundaries) | `type: K, detail: UnpackCustomEvent<CustomEventMap[K]>` | `boolean` | EventEmitterMixin |

### Events

| Name                  | Type                                | Description                                                | Inherited From |
| --------------------- | ----------------------------------- | ---------------------------------------------------------- | -------------- |
| `btu-checkbox-ready`  | `CustomEvent`                       | Fired after the checkbox is first rendered and initialized |                |
| `btu-checkbox-change` | `CustomEvent<{ checked: boolean }>` | Fired when the user toggles the checked state              |                |

### Attributes

| Name            | Field         | Inherited From |
| --------------- | ------------- | -------------- |
| `label`         | label         |                |
| `description`   | description   |                |
| `size`          | size          |                |
| `checked`       | checked       |                |
| `indeterminate` | indeterminate |                |
| `disabled`      | disabled      |                |
| `invalid`       | invalid       |                |
| `error`         | error         |                |
| `required`      | required      |                |
| `name`          | name          |                |
| `value`         | value         |                |

### CSS Properties

| Name                       | Default | Description                                                                                                                                                                                      |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--checkbox-color-primary` |         | Background and border color when checked or indeterminate, and tinted background/border on unchecked hover (default: oklch(var(--btu-theme-primary-700)))                                        |
| `--checkbox-color-border`  |         | Border color in the unchecked state (default: oklch(var(--btu-theme-gray-300)))                                                                                                                  |
| `--checkbox-color-error`   |         | Border and text color in the error state (default: oklch(var(--btu-theme-error-600)))                                                                                                            |
| `--checkbox-border-radius` |         | Corner rounding of the checkbox square (default: 4px)                                                                                                                                            |
| `--checkbox-label-spacing` |         | Distance between the checkbox and the label (default: 0.75rem)                                                                                                                                   |
| `--checkbox-box-size`      |         | \[Internal] Width and height of the checkbox square, set by the size variant (sm: 1rem, md: 1.25rem). Use the \`size\` attribute instead of overriding directly — the icon must scale in tandem. |
| `--checkbox-icon-size`     |         | \[Internal] Width and height of the icon inside the box, set by the size variant (sm: 0.75rem, md: 0.875rem). Use the \`size\` attribute instead of overriding directly.                         |

<hr/>

## Exports

| Kind                        | Name           | Declaration | Module                              | Package |
| --------------------------- | -------------- | ----------- | ----------------------------------- | ------- |
| `js`                        | `default`      | Checkbox    | src/components/checkbox/Checkbox.ts |         |
| `custom-element-definition` | `btu-checkbox` | Checkbox    | src/components/checkbox/Checkbox.ts |         |
