Checkbox
Table of Contents
Installation
Use the ng add command to quickly install all the needed dependencies:
ng add @terminus/ui-checkboxCSS imports
In your top-level stylesheet, add these imports:
@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 <head> of your application:
<link href="https://fonts.googleapis.com/css2?family=Roboto:ital,wght@0,400;0,500;0,700;1,400&display=swap" rel="stylesheet">Usage
The checkbox label content can be set in two ways:
<!-- Pass text in through ng-content -->
<ts-checkbox>My checkbox label</ts-checkbox>
<!-- Pass text in through the label input -->
<ts-checkbox label="My checkbox label"></ts-checkbox>State
Reactive Forms
To use the checkbox with a reactive form, pass the FormControl or the formControlName to the checkbox:
<ts-checkbox [formControl]="myForm.get('myControl')">
I will be checked if `myForm.myControl.value` is true.
</ts-checkbox>
<ts-checkbox formControlName="myControl">
I will be checked if `myForm.myControl.value` is true.
</ts-checkbox>NOTE: If no
FormControlorngModelis 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:
<ts-checkbox [(ngModel)]="myValue">
I will be checked if `myValue` is true.
</ts-checkbox>Checked
The checked state will likely be managed by setting the FormControl or ngModel value. It can also be set via
@Input or programmatically:
<!-- @Input -->
<ts-checkbox [isChecked]="true">I will be checked</ts-checkbox>
<!-- Programmatically -->
<ts-checkbox #myCheckbox="tsCheckbox">I can be toggled via a button</ts-checkbox>
<button (click)="myCheckbox.toggle()">Toggle the checked value</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:
<!-- @Input -->
<ts-checkbox [isDisabled]="true">I will be disabled</ts-checkbox>
<!-- Programmatically -->
<ts-checkbox #myCheckbox="tsCheckbox">I can be disabled via a button</ts-checkbox>
<button (click)="myCheckbox.isDisabled != myCheckbox.isDisabled">Toggle the disabled state</button>Indeterminate
The indeterminate state can be set via @Input:
<ts-checkbox [isIndeterminate]="true">I will be indeterminate</ts-checkbox>Required
The checkbox can be marked as required:
<ts-checkbox [isRequired]="true">I will be required</ts-checkbox>a11y
The checkbox supports aria properties:
<!-- Pass the ID of an element that describes the checkbox -->
<ts-checkbox [ariaDescribedby]="myId">Foo</ts-checkbox>
<!-- Pass a space-separated list of element IDs that provide essential information about the checkbox -->
<ts-checkbox [ariaLabelledby]="myId anotherId">Foo</ts-checkbox>
<!-- Set the aria label -->
<ts-checkbox [ariaLabel]="My descriptive label.">Foo</ts-checkbox>Tab Index
Custom tabindex can be set to control the flow:
<ts-checkbox>Foo</ts-checkbox>
<ts-checkbox [tabIndex]="-1">I will be skipped when tabbing through the DOM</ts-checkbox>
<ts-checkbox>Bar</ts-checkbox>Focus
Programmatically focus the underlying <input>:
<ts-checkbox #myCheckbox="tsCheckbox">My checkbox</ts-checkbox>
<button (click)="myCheckbox.focus()">Focus the internal native `input`</button>Events
<ts-checkbox (inputChange)="myChangeFunction($event)>Foo</ts-checkbox>
<ts-checkbox (indeterminateChange)="myIndeterminateChangeFunction($event)>Bar</ts-checkbox>| 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:
@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;
| Function |
|---|
getAllCheckboxInstances |
getCheckboxInstance |
getCheckboxElement |
toggleCheckbox |