[![CI/CD Status][github-action-badge]][github-action-link] [![Codecov][codecov-badge]][codecov-project] [![MIT License][license-image]][license-url]
[![NPM version][npm-version-image]][npm-package] [![Library size][file-size-badge]][raw-distribution-js]
## Table of Contents
- [Installation](#installation)
- [CSS imports](#css-imports)
- [CSS resources](#css-resources)
- [Usage](#usage)
- [State](#state)
- [Reactive Forms](#reactive-forms)
- [`ngModel`](#ngmodel)
- [Checked](#checked)
- [Disabled](#disabled)
- [Indeterminate](#indeterminate)
- [Required](#required)
- [a11y](#a11y)
- [Tab Index](#tab-index)
- [Focus](#focus)
- [Events](#events)
- [Default settings](#default-settings)
- [Click action](#click-action)
- [Test Helpers](#test-helpers)
## Installation
Use the `ng add` command to quickly install all the needed dependencies:
```bash
ng add @terminus/ui-checkbox
```
### CSS imports
In your top-level stylesheet, add these imports:
```css
@import '~@terminus/design-tokens/css/library-design-tokens.css';
@import '~@terminus/ui-styles/terminus-ui.css';
```
### CSS resources
Load the needed font families by adding this link to the `` of your application:
```css
```
## Usage
The checkbox label content can be set in two ways:
```html
My checkbox label
```
### State
#### Reactive Forms
To use the checkbox with a reactive form, pass the `FormControl` or the `formControlName` to the checkbox:
```html
I will be checked if `myForm.myControl.value` is true.
I will be checked if `myForm.myControl.value` is true.
```
> NOTE: If no `FormControl` or `ngModel` is passed in, one will be assigned to manage state.
#### `ngModel`
To use the checkbox with Angular's `ngModel`, just attach the directive to the checkbox:
```html
I will be checked if `myValue` is true.
```
#### Checked
The checked state will likely be managed by setting the `FormControl` or `ngModel` value. It can also be set via
`@Input` or programmatically:
```html
I will be checkedI can be toggled via a button
```
> NOTE: Events will not be emitted when state changes programmatically.
#### Disabled
The checkbox can be disabled by disabling the associated `FormControl` or `ngModel`. It can also be set via `@Input` or
programmatically:
```html
I will be disabledI can be disabled via a button
```
#### Indeterminate
The indeterminate state can be set via `@Input`:
```html
I will be indeterminate
```
#### Required
The checkbox can be marked as required:
```html
I will be required
```
### a11y
The checkbox supports aria properties:
```html
FooFooFoo
```
### Tab Index
Custom `tabindex` can be set to control the flow:
```html
FooI will be skipped when tabbing through the DOMBar
```
### Focus
Programmatically focus the underlying ``:
```html
My checkbox
```
### Events
```html
Bar
```
| Event | Description | Payload |
|:----------------------|:----------------------------------------------------|:-------------------|
| `inputChange` | Fired when the checkbox checked state changes | `TsCheckboxChange` |
| `indeterminateChange` | Fired when the checkbox indeterminate state changes | `boolean` |
> NOTE: Events will not be emitted when state changes programmatically.
### Default settings
The default settings can be overridden via a provider:
```typescript
@Component({
selector: 'my-component',
providers: [
{
provide: TS_CHECKBOX_DEFAULT_OPTIONS,
useValue: { clickAction: 'check' },
},
],
})
export class MyComponent {}
```
Currently, only `clickAction` is a supported default.
#### Click action
- `noop`: Do not toggle checked or indeterminate
- `check`: Only toggle checked status, ignore indeterminate
- `check-indeterminate`: Toggle checked status, set indeterminate to false. Default behavior
- `undefined`: Same as check-indeterminate.
> See the previous section for usage example
## Test Helpers
Some helpers exist to assist with testing. These are imported from `@terminus/ui-checkbox/testing`;
[[source]][test-helpers-src]
| Function |
|---------------------------|
| `getAllCheckboxInstances` |
| `getCheckboxInstance` |
| `getCheckboxElement` |
| `toggleCheckbox` |
[test-helpers-src]: testing/src/test-helpers.ts
[license-url]: https://github.com/GetTerminus/terminus-oss/blob/release/LICENSE
[license-image]: http://img.shields.io/badge/license-MIT-blue.svg
[codecov-project]: https://codecov.io/gh/GetTerminus/terminus-oss
[codecov-badge]: https://codecov.io/gh/GetTerminus/terminus-oss/branch/release/graph/badge.svg
[npm-version-image]: http://img.shields.io/npm/v/@terminus/ui-checkbox.svg
[npm-package]: https://www.npmjs.com/package/@terminus/ui-checkbox
[github-action-badge]: https://github.com/GetTerminus/terminus-oss/workflows/Release%20CI/badge.svg
[github-action-link]: https://github.com/GetTerminus/terminus-oss/actions?query=workflow%3A%22CI+Release%22
[file-size-badge]: http://img.badgesize.io/https://unpkg.com/@terminus/ui-checkbox/bundles/terminus-ui-checkbox.umd.min.js?compression=gzip
[raw-distribution-js]: https://unpkg.com/@terminus/ui-checkbox/bundles/terminus-ui-checkbox.umd.js