@terminus/ui-checkbox

v4.0.2

Published

2 years ago

<h1>Checkbox</h1>

Downloads

0High
0Medium
0Low

bmalinconico-terminus

atlwendy

terminus_devops

Installation

Use the ng add command to quickly install all the needed dependencies:

ng add @terminus/ui-checkbox

CSS 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 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:

<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;

[source]

| Function | |---------------------------| | getAllCheckboxInstances | | getCheckboxInstance | | getCheckboxElement | | toggleCheckbox |