# Checkbox

- Entry point: `@koobiq/components/checkbox`
- NgModule: `KbqCheckboxModule`
- API: https://koobiq.io/api/checkbox.md
- Component tokens: https://koobiq.io/tokens/checkbox.md
- Page: https://koobiq.io/en/components/checkbox/overview

## Overview

Checkbox lets users select independent options and can also represent the selection state of a group.

### Dual-state

Dual-state is applied using the boolean attribute `[checked]` to show whether the checkbox is checked or not.

[**Example: Checkbox** (`checkbox-overview`)](https://koobiq.io/examples/checkbox-overview.md)

### Indeterminate state (partial selection)

The indeterminate state is applied using the boolean attribute `[indeterminate]` and can be used when you have a group of options and a higher-level checkbox should reflect their state:

- If only some options in the group are selected, the higher-level checkbox appears partially selected (`[indeterminate]="true"`).
- If all are selected, the higher-level checkbox is shown as checked.
- If none are selected, the higher-level checkbox appears unchecked.

[**Example: Checkbox indeterminate** (`checkbox-indeterminate`)](https://koobiq.io/examples/checkbox-indeterminate.md)

### Click action config

When the user clicks on a `kbq-checkbox`, the default behavior toggles the `checked` value and sets `indeterminate` to `false`.
This behavior can be configured by [providing a new value](https://angular.io/guide/dependency-injection) for `KBQ_CHECKBOX_CLICK_ACTION` on the checkbox.

```ts
providers: [
    { provide: KBQ_CHECKBOX_CLICK_ACTION, useValue: 'check' }
];
```

Possible values: noop, check, check-indeterminate

### Pseudo checkbox

[**Example: Pseudo checkbox** (`pseudo-checkbox`)](https://koobiq.io/examples/pseudo-checkbox.md)

### Multiline

[**Example: Checkbox multiline example** (`checkbox-multiline`)](https://koobiq.io/examples/checkbox-multiline.md)

### Validation

To show a validation error, bind the checkbox to a form control, apply `required` or `Validators.requiredTrue`, and put the error text in a `kbq-error` inside the checkbox.

To show the error at another moment, for example only after the form is submitted, pass a matcher to the `errorStateMatcher` input. The matchers are described in the [Validation guide](https://koobiq.io/en/other/validation.md).

[**Example: Checkbox validation** (`checkbox-validation`)](https://koobiq.io/examples/checkbox-validation.md)

## Examples

### Block checkbox

A custom checkbox-like "card" control built on the shared `KbqCheckable` primitive (`@koobiq/components/core`), showing how to reuse checkbox's click/form/a11y behavior with your own markup and styling.

[**Example: Custom checkbox block** (`block-checkbox`)](https://koobiq.io/examples/block-checkbox.md)
