# Checkbox


## Examples

### Default

```html
<m-checkbox
      value=${args.value}
      name=${args.name ?? ""}
      ?checked=${args.checked}
      ?disabled=${args.disabled}
      ?readonly=${args.readonly}
      ?required=${args.required}
      ?indeterminate=${args.indeterminate}
      ?labelHidden=${args.labelHidden}
      label=${args.label || ""}
      hint=${args.hint || ""}
      description=${args.description || ""}
      error=${args.error || ""}
      @input=${args.oninput}
      @change=${args.onchange}
    ></m-checkbox>
```

### States

```html
<m-stack direction="vertical" spacing="m">
      <m-checkbox label="Default checkbox"></m-checkbox>
      <m-checkbox label="Checked checkbox" checked></m-checkbox>
      <m-checkbox label="Indeterminate checkbox" indeterminate></m-checkbox>
      <m-checkbox label="Disabled checkbox" disabled></m-checkbox>
      <m-checkbox
        label="Disabled checked checkbox"
        disabled
        checked
      ></m-checkbox>
      <m-checkbox
        label="Disabled indeterminate checkbox"
        disabled
        indeterminate
      ></m-checkbox>
      <m-checkbox label="Readonly checkbox" readonly></m-checkbox>
      <m-checkbox
        label="Readonly checked checkbox"
        readonly
        checked
      ></m-checkbox>
      <m-checkbox
        label="Readonly indeterminate checkbox"
        readonly
        indeterminate
      ></m-checkbox>
      <m-checkbox label="Required checkbox" required></m-checkbox>
      <m-checkbox
        label="Required checked checkbox"
        required
        checked
      ></m-checkbox>
      <m-checkbox
        label="Required indeterminate checkbox"
        required
        indeterminate
      ></m-checkbox>
    </m-stack>
```

### WithHint

```html
<m-checkbox
      label="Checkbox with hint"
      hint="This is a helpful hint text"
    ></m-checkbox>
```

### WithDescription

```html
<m-checkbox label="Checkbox with description" description="This is a helpful description text">
```

### WithError

```html
<m-stack direction="vertical" spacing="m">
      <m-checkbox label="Checkbox checked with error" checked error="This field is required"></m-checkbox>
        <span slot="error">This field is required</span>
      </m-checkbox>
      <m-checkbox label="Checkbox with error">
        <span slot="error">This field is required</span>
      </m-checkbox>
    </m-stack>
```

### WithCustomContent

```html
<m-checkbox>
      <span slot="label">Custom <strong>formatted</strong> label</span>
      <span slot="hint">Custom <em>formatted</em> hint</span>
      <span slot="error">Custom <em>formatted</em> error</span>
    </m-checkbox>
```

## Usage

**Use a Checkbox to:**

- Allow users to select multiple options from a set.
- Enable or disable a specific feature or setting.
- Provide a binary choice (e.g., "I agree to the terms and conditions").
- Support independent selection where multiple checkboxes can be checked simultaneously.

**Do not use a Checkbox to:**

- Perform an action immediately when selected (use a toggle switch instead).
- Represent mutually exclusive choices (use radio buttons instead).
- Select all options at once without a clear way to deselect (consider an explicit "Select All" checkbox).

## Other Considerations

- Ensure the checkbox has a label that describes its purpose.
- Labels should be concise and clearly describe the option (e.g., "Receive email notifications").
- Avoid double negatives (e.g., "Do not disable notifications").
- Group related checkboxes under a clear heading.

## Design Rationale
- Checkboxes are a familiar UI pattern, making them easy to recognize and use.
- They offer clear affordance, showing whether an option is selected or not.
- They support bulk actions and multiple selections, making them flexible for many interfaces.
- Checkboxes align with accessibility guidelines, ensuring users with disabilities can interact with