# Checkbox Component

Checkboxes allow users to select one or more options from a set. Each checkbox can toggle between checked and unchecked states.

## Usage {#usage}

Import the component:

```js
import 'mdui/components/checkbox.js';
```

Import the TypeScript type:

```ts
import type { Checkbox } from 'mdui/components/checkbox.js';
```

Example:

```html
<mdui-checkbox>Checkbox</mdui-checkbox>
```

## Examples {#examples}

### Checked State {#example-checked}

The `checked` property is `true` when the checkbox is checked. Add the `checked` attribute to set the checkbox to the checked state by default.

```html
<mdui-checkbox checked>Checkbox</mdui-checkbox>
```

### Disabled State {#example-disabled}

Use the `disabled` attribute to disable the checkbox.

```html
<mdui-checkbox disabled>Checkbox</mdui-checkbox>
<mdui-checkbox disabled checked>Checkbox</mdui-checkbox>
```

### Indeterminate State {#example-indeterminate}

The `indeterminate` attribute sets the checkbox to an indeterminate state.

```html
<mdui-checkbox indeterminate>Checkbox</mdui-checkbox>
```

### Icons {#example-icon}

Use the `unchecked-icon`, `checked-icon`, and `indeterminate-icon` attributes to set the Material Icons for the checkbox in unchecked, checked, and indeterminate states, respectively. Alternatively, use the corresponding slots to set the icons.

```html
<mdui-checkbox
  unchecked-icon="radio_button_unchecked"
  checked-icon="check_circle"
  indeterminate-icon="playlist_add_check_circle"
>Checkbox</mdui-checkbox>

<mdui-checkbox
  indeterminate
  unchecked-icon="radio_button_unchecked"
  checked-icon="check_circle"
  indeterminate-icon="playlist_add_check_circle"
>Checkbox</mdui-checkbox>

<br/>

<mdui-checkbox>
  <mdui-icon slot="unchecked-icon" name="radio_button_unchecked"></mdui-icon>
  <mdui-icon slot="checked-icon" name="check_circle"></mdui-icon>
  <mdui-icon slot="indeterminate-icon" name="playlist_add_check_circle"></mdui-icon>
  Checkbox
</mdui-checkbox>

<mdui-checkbox indeterminate>
  <mdui-icon slot="unchecked-icon" name="radio_button_unchecked"></mdui-icon>
  <mdui-icon slot="checked-icon" name="check_circle"></mdui-icon>
  <mdui-icon slot="indeterminate-icon" name="playlist_add_check_circle"></mdui-icon>
  Checkbox
</mdui-checkbox>
```

## mdui-checkbox API

### Properties

<table>
<thead>
  <tr>
    <th>Attribute</th>
    <th>Property</th>
    <th>Reflect</th>
    <th>Type</th>
    <th>Default</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>disabled</td>
    <td>disabled</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Disables the checkbox.</p>
</td>
  </tr>
  <tr>
    <td>checked</td>
    <td>checked</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Sets the checkbox to the checked state.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>defaultChecked</td>
    <td>false</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Sets the default checked state. The checkbox resets to this state when the form is reset. JavaScript only.</p>
</td>
  </tr>
  <tr>
    <td>indeterminate</td>
    <td>indeterminate</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Sets the checkbox to an indeterminate state.</p>
</td>
  </tr>
  <tr>
    <td>required</td>
    <td>required</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>The checkbox must be checked to submit the form.</p>
</td>
  </tr>
  <tr>
    <td>form</td>
    <td>form</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Associates the checkbox with a <code>&lt;form&gt;</code> element. Set this to the <code>id</code> of a <code>&lt;form&gt;</code> in the same document. If omitted, the checkbox uses its parent <code>&lt;form&gt;</code>, if any.</p>
<p>This lets the checkbox work with any form in the document, not just the one it is nested in.</p>
</td>
  </tr>
  <tr>
    <td>name</td>
    <td>name</td>
    <td>true</td>
    <td>string</td>
    <td>''</td>
    <td><p>Sets the checkbox&#39;s name, which is submitted with form data.</p>
</td>
  </tr>
  <tr>
    <td>value</td>
    <td>value</td>
    <td>true</td>
    <td>string</td>
    <td>'on'</td>
    <td><p>Sets the checkbox&#39;s value, which is submitted with form data.</p>
</td>
  </tr>
  <tr>
    <td>unchecked-icon</td>
    <td>uncheckedIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Sets the Material Icons name for the unchecked state. Alternatively, use <code>slot=&quot;unchecked-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>checked-icon</td>
    <td>checkedIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Sets the Material Icons name for the checked state. Alternatively, use <code>slot=&quot;checked-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>indeterminate-icon</td>
    <td>indeterminateIcon</td>
    <td>true</td>
    <td>string</td>
    <td></td>
    <td><p>Sets the Material Icons name for the indeterminate state. Alternatively, use <code>slot=&quot;indeterminate-icon&quot;</code>.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validity</td>
    <td>false</td>
    <td>ValidityState</td>
    <td></td>
    <td><p>A <a href="https://developer.mozilla.org/en-US/docs/Web/API/ValidityState" target="_blank" rel="noopener nofollow"><code>ValidityState</code></a> object that represents the element&#39;s validity states.</p>
</td>
  </tr>
  <tr>
    <td>undefined</td>
    <td>validationMessage</td>
    <td>false</td>
    <td>string</td>
    <td></td>
    <td><p>Validation message. Empty string when valid.</p>
</td>
  </tr>
  <tr>
    <td>autofocus</td>
    <td>autofocus</td>
    <td>true</td>
    <td>boolean</td>
    <td>false</td>
    <td><p>Whether the element is focused when the page loads.</p>
</td>
  </tr>
  <tr>
    <td>tabindex</td>
    <td>tabIndex</td>
    <td>false</td>
    <td>number</td>
    <td></td>
    <td><p>The element&#39;s tab order when navigating with the Tab key.</p>
</td>
  </tr>
</tbody>
</table>

### Methods

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>checkValidity(): boolean</td>
    <td><p>Checks the validity of the form field. If it is invalid, it triggers an <code>invalid</code> event and returns <code>false</code>. If valid, it returns <code>true</code>.</p>
</td>
  </tr>
  <tr>
    <td>reportValidity(): boolean</td>
    <td><p>Checks the validity of the form field. If it is invalid, it triggers an <code>invalid</code> event, returns <code>false</code>, and displays a validation message. If valid, it returns <code>true</code>.</p>
</td>
  </tr>
  <tr>
    <td>setCustomValidity(message: string): void</td>
    <td><p>Sets a custom error message. If the message is non-empty, the field is considered invalid.</p>
</td>
  </tr>
  <tr>
    <td>click(): void</td>
    <td><p>Simulates a mouse click on the element.</p>
</td>
  </tr>
  <tr>
    <td>focus(options?: FocusOptions): void</td>
    <td><p>Sets focus on the element. An optional object parameter may include a <code>preventScroll</code> property. If <code>preventScroll</code> is set to <code>true</code>, the page will not scroll to bring the focused element into view.</p>
</td>
  </tr>
  <tr>
    <td>blur(): void</td>
    <td><p>Removes focus from the element.</p>
</td>
  </tr>
</tbody>
</table>

### Events

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>focus</td>
    <td><p>Emitted when the checkbox gains focus.</p>
</td>
  </tr>
  <tr>
    <td>blur</td>
    <td><p>Emitted when the checkbox loses focus.</p>
</td>
  </tr>
  <tr>
    <td>change</td>
    <td><p>Emitted when the checked state changes.</p>
</td>
  </tr>
  <tr>
    <td>input</td>
    <td><p>Emitted when the checked state changes.</p>
</td>
  </tr>
  <tr>
    <td>invalid</td>
    <td><p>Emitted when the form control&#39;s validity is checked and it does not meet the constraints.</p>
</td>
  </tr>
</tbody>
</table>

### Slots

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>(default)</td>
    <td><p>Text.</p>
</td>
  </tr>
  <tr>
    <td>unchecked-icon</td>
    <td><p>Icon for the unchecked state.</p>
</td>
  </tr>
  <tr>
    <td>checked-icon</td>
    <td><p>Icon for the checked state.</p>
</td>
  </tr>
  <tr>
    <td>indeterminate-icon</td>
    <td><p>Icon for the indeterminate state.</p>
</td>
  </tr>
</tbody>
</table>

### CSS Parts

<table>
<thead>
  <tr>
    <th>Name</th>
    <th>Description</th>
  </tr>
</thead>
<tbody>
  <tr>
    <td>control</td>
    <td><p>Container for the left icon.</p>
</td>
  </tr>
  <tr>
    <td>unchecked-icon</td>
    <td><p>Icon for the unchecked state.</p>
</td>
  </tr>
  <tr>
    <td>checked-icon</td>
    <td><p>Icon for the checked state.</p>
</td>
  </tr>
  <tr>
    <td>indeterminate-icon</td>
    <td><p>Icon for the indeterminate state.</p>
</td>
  </tr>
  <tr>
    <td>label</td>
    <td><p>Text.</p>
</td>
  </tr>
</tbody>
</table>