src/checkbox/checkbox.component.ts
Get started with importing the module:
Example :import { CheckboxModule } from 'carbon-components-angular';
ControlValueAccessor
AfterViewInit
changeDetection | ChangeDetectionStrategy.OnPush |
providers |
{
provide: NG_VALUE_ACCESSOR, useExisting: Checkbox, multi: true
}
|
selector | cds-checkbox, ibm-checkbox |
template |
|
Properties |
Methods |
|
Inputs |
Outputs |
HostListeners |
Accessors |
constructor(changeDetectorRef: ChangeDetectorRef)
|
||||||
Defined in src/checkbox/checkbox.component.ts:194
|
||||||
Creates an instance of
Parameters :
|
ariaLabel | |
Type : string
|
|
Defined in src/checkbox/checkbox.component.ts:108
|
ariaLabelledby | |
Type : string
|
|
Defined in src/checkbox/checkbox.component.ts:109
|
checked | |
Type : boolean
|
|
Defined in src/checkbox/checkbox.component.ts:148
|
|
Sets the Allows double binding with the |
disabled | |
Type : boolean
|
|
Default value : false
|
|
Defined in src/checkbox/checkbox.component.ts:83
|
|
Set to |
hideLabel | |
Type : boolean
|
|
Default value : false
|
|
Defined in src/checkbox/checkbox.component.ts:91
|
|
Set to |
id | |
Type : string
|
|
Default value : `checkbox-${Checkbox.checkboxCount}`
|
|
Defined in src/checkbox/checkbox.component.ts:99
|
|
The unique id for the checkbox component. |
indeterminate | |
Type : boolean
|
|
Defined in src/checkbox/checkbox.component.ts:116
|
|
Set the checkbox's indeterminate state to match the parameter and transition the view to reflect the change. Allows double binding with the |
name | |
Type : string
|
|
Defined in src/checkbox/checkbox.component.ts:95
|
|
Sets the name attribute on the |
required | |
Type : boolean
|
|
Defined in src/checkbox/checkbox.component.ts:103
|
|
Reflects the required attribute of the |
skeleton | |
Type : boolean
|
|
Default value : false
|
|
Defined in src/checkbox/checkbox.component.ts:87
|
|
Set to |
value | |
Type : CheckboxValue
|
|
Defined in src/checkbox/checkbox.component.ts:107
|
|
Sets the value attribute on the |
checkedChange | |
Type : EventEmitter
|
|
Defined in src/checkbox/checkbox.component.ts:169
|
|
Emits an event when the value of the checkbox changes. Allows double biding with the |
click | |
Type : EventEmitter
|
|
Defined in src/checkbox/checkbox.component.ts:162
|
|
Emits click event. |
indeterminateChange | |
Type : EventEmitter
|
|
Defined in src/checkbox/checkbox.component.ts:175
|
|
Emits event notifying other classes when a change in state occurs specifically on an indeterminate checkbox. |
focusout |
focusout()
|
Defined in src/checkbox/checkbox.component.ts:251
|
emitChangeEvent |
emitChangeEvent()
|
Defined in src/checkbox/checkbox.component.ts:296
|
Creates instance of
Returns :
void
|
focusOut |
focusOut()
|
Decorators :
@HostListener('focusout')
|
Defined in src/checkbox/checkbox.component.ts:251
|
Returns :
void
|
ngAfterViewInit |
ngAfterViewInit()
|
Defined in src/checkbox/checkbox.component.ts:304
|
Updates the checkbox if it is in the indeterminate state.
Returns :
void
|
onChange | ||||||
onChange(event: Event)
|
||||||
Defined in src/checkbox/checkbox.component.ts:258
|
||||||
Executes on the event of a change within
Parameters :
Returns :
void
|
onClick | ||||||
onClick(event: Event)
|
||||||
Defined in src/checkbox/checkbox.component.ts:265
|
||||||
Handles click events on the
Parameters :
Returns :
void
|
Public registerOnChange | ||||||
registerOnChange(fn: any)
|
||||||
Defined in src/checkbox/checkbox.component.ts:226
|
||||||
Sets a method in order to propagate changes back to the form.
Parameters :
Returns :
void
|
Public registerOnTouched | ||||||||
registerOnTouched(fn: any)
|
||||||||
Defined in src/checkbox/checkbox.component.ts:234
|
||||||||
Registers a callback to be triggered when the control has been touched.
Parameters :
Returns :
void
|
Private setChecked |
setChecked(checked: boolean, resetIndeterminate: boolean)
|
Defined in src/checkbox/checkbox.component.ts:318
|
Sets checked state and optionally resets indeterminate state.
Returns :
void
|
setDisabledState | ||||||||
setDisabledState(isDisabled: boolean)
|
||||||||
Defined in src/checkbox/checkbox.component.ts:245
|
||||||||
ex:
Parameters :
Returns :
void
|
Public toggle |
toggle()
|
Defined in src/checkbox/checkbox.component.ts:206
|
Toggle the selected state of the checkbox.
Returns :
void
|
transitionCheckboxState | ||||||
transitionCheckboxState(newState: CheckboxState)
|
||||||
Defined in src/checkbox/checkbox.component.ts:289
|
||||||
Handles changes between checkbox states.
Parameters :
Returns :
void
|
Public writeValue | ||||||||
writeValue(value: any)
|
||||||||
Defined in src/checkbox/checkbox.component.ts:218
|
||||||||
Writes a value from In this case the value is the
Parameters :
Returns :
void
|
_checked |
Default value : false
|
Defined in src/checkbox/checkbox.component.ts:180
|
Set to |
_indeterminate |
Default value : false
|
Defined in src/checkbox/checkbox.component.ts:184
|
Set to |
Static checkboxCount |
Type : number
|
Default value : 0
|
Defined in src/checkbox/checkbox.component.ts:78
|
Variable used for creating unique ids for checkbox components. |
currentCheckboxState |
Default value : CheckboxState.Init
|
Defined in src/checkbox/checkbox.component.ts:189
|
Keeps a reference to the checkboxes current state, as defined in |
inputCheckbox |
Type : ElementRef
|
Decorators :
@ViewChild('inputCheckbox')
|
Defined in src/checkbox/checkbox.component.ts:194
|
Maintains a reference to the view DOM element of the |
onTouched |
Type : function
|
Default value : () => {...}
|
Defined in src/checkbox/checkbox.component.ts:284
|
Called when checkbox is blurred. Needed to properly implement |
propagateChange |
Default value : () => {...}
|
Defined in src/checkbox/checkbox.component.ts:313
|
Method set in |
indeterminate | ||||||
getindeterminate()
|
||||||
Defined in src/checkbox/checkbox.component.ts:139
|
||||||
Reflects whether the checkbox state is indeterminate. |
||||||
setindeterminate(indeterminate: boolean)
|
||||||
Defined in src/checkbox/checkbox.component.ts:116
|
||||||
Set the checkbox's indeterminate state to match the parameter and transition the view to reflect the change. Allows double binding with the
Parameters :
Returns :
void
|
checked | ||||||
getchecked()
|
||||||
Defined in src/checkbox/checkbox.component.ts:155
|
||||||
Returns value |
||||||
setchecked(checked: boolean)
|
||||||
Defined in src/checkbox/checkbox.component.ts:148
|
||||||
Sets the Allows double binding with the
Parameters :
Returns :
void
|
import {
AfterViewInit,
ChangeDetectionStrategy,
ChangeDetectorRef,
Component,
ElementRef,
EventEmitter,
Input,
Output,
ViewChild,
HostListener
} from "@angular/core";
import { NG_VALUE_ACCESSOR, ControlValueAccessor } from "@angular/forms";
import { CheckboxValue } from "./checkbox.types";
/**
* Defines the set of states for a checkbox component.
*/
export enum CheckboxState {
Init,
Indeterminate,
Checked,
Unchecked
}
/**
* Get started with importing the module:
*
* ```typescript
* import { CheckboxModule } from 'carbon-components-angular';
* ```
*
* [See demo](../../?path=/story/components-checkbox--basic)
*/
@Component({
selector: "cds-checkbox, ibm-checkbox",
template: `
<div class="cds--form-item cds--checkbox-wrapper">
<input
#inputCheckbox
class="cds--checkbox"
type="checkbox"
[id]="id + '_input'"
[value]="value"
[name]="name"
[required]="required"
[checked]="checked"
[disabled]="disabled"
[attr.aria-labelledby]="ariaLabelledby"
(change)="onChange($event)"
(click)="onClick($event)">
<label
[for]="id + '_input'"
[attr.aria-label]="ariaLabel"
class="cds--checkbox-label"
[ngClass]="{
'cds--skeleton' : skeleton
}">
<span [ngClass]="{'cds--visually-hidden' : hideLabel}" class="cds--checkbox-label-text">
<ng-content></ng-content>
</span>
</label>
</div>
`,
providers: [
{
provide: NG_VALUE_ACCESSOR,
useExisting: Checkbox,
multi: true
}
],
changeDetection: ChangeDetectionStrategy.OnPush
})
export class Checkbox implements ControlValueAccessor, AfterViewInit {
/**
* Variable used for creating unique ids for checkbox components.
*/
static checkboxCount = 0;
/**
* Set to `true` for a disabled checkbox.
*/
@Input() disabled = false;
/**
* Set to `true` for a loading checkbox.
*/
@Input() skeleton = false;
/**
* Set to `true` to hide the checkbox labels.
*/
@Input() hideLabel = false;
/**
* Sets the name attribute on the `input` element.
*/
@Input() name: string;
/**
* The unique id for the checkbox component.
*/
@Input() id = `checkbox-${Checkbox.checkboxCount}`;
/**
* Reflects the required attribute of the `input` element.
*/
@Input() required: boolean;
/**
* Sets the value attribute on the `input` element.
*/
@Input() value: CheckboxValue;
@Input() ariaLabel: string;
@Input() ariaLabelledby: string;
/**
* Set the checkbox's indeterminate state to match the parameter and transition the view to reflect the change.
*
* Allows double binding with the `indeterminateChange` Output.
*/
@Input() set indeterminate(indeterminate: boolean) {
if (indeterminate === this._indeterminate) {
return;
}
this._indeterminate = indeterminate;
if (this._indeterminate) {
this.transitionCheckboxState(CheckboxState.Indeterminate);
} else {
this.transitionCheckboxState(this.checked ? CheckboxState.Checked : CheckboxState.Unchecked);
}
if (this.inputCheckbox && this.inputCheckbox.nativeElement) {
this.inputCheckbox.nativeElement.indeterminate = indeterminate;
}
this.changeDetectorRef.markForCheck();
this.indeterminateChange.emit(this._indeterminate);
}
/**
* Reflects whether the checkbox state is indeterminate.
*/
get indeterminate() {
return this._indeterminate;
}
/**
* Sets the `checked` state. `true` for checked, `false` for unchecked
*
* Allows double binding with the `checkedChange` Output.
*/
@Input() set checked (checked: boolean) {
this.setChecked(checked, false);
}
/**
* Returns value `true` if state is selected for the checkbox.
*/
get checked() {
return this._checked;
}
/**
* Emits click event.
*/
@Output() click = new EventEmitter<void>();
/**
* Emits an event when the value of the checkbox changes.
*
* Allows double biding with the `checked` Input.
*/
@Output() checkedChange = new EventEmitter<boolean>();
/**
* Emits event notifying other classes when a change in state occurs specifically
* on an indeterminate checkbox.
*/
@Output() indeterminateChange = new EventEmitter<boolean>();
/**
* Set to `true` if the input checkbox is selected (or checked).
*/
_checked = false;
/**
* Set to `true` if the input checkbox is in state indeterminate.
*/
_indeterminate = false;
/**
* Keeps a reference to the checkboxes current state, as defined in `CheckboxState`.
*/
currentCheckboxState = CheckboxState.Init;
/**
* Maintains a reference to the view DOM element of the `Checkbox`.
*/
@ViewChild("inputCheckbox") inputCheckbox: ElementRef;
/**
* Creates an instance of `Checkbox`.
*/
constructor(protected changeDetectorRef: ChangeDetectorRef) {
Checkbox.checkboxCount++;
}
/**
* Toggle the selected state of the checkbox.
*/
public toggle() {
// Flip checked and reset indeterminate
this.setChecked(!this.checked, true);
}
/**
* Writes a value from `ngModel` to the component.
*
* In this case the value is the `checked` property.
*
* @param value boolean, corresponds to the `checked` property.
*/
public writeValue(value: any) {
// Set checked and reset indeterminate
this.setChecked(!!value, true);
}
/**
* Sets a method in order to propagate changes back to the form.
*/
public registerOnChange(fn: any) {
this.propagateChange = fn;
}
/**
* Registers a callback to be triggered when the control has been touched.
* @param fn Callback to be triggered when the checkbox is touched.
*/
public registerOnTouched(fn: any) {
this.onTouched = fn;
}
/**
* `ControlValueAccessor` method to programmatically disable the checkbox.
*
* ex: `this.formGroup.get("myCheckbox").disable();`
*
* @param isDisabled `true` to disable the checkbox
*/
setDisabledState(isDisabled: boolean) {
this.disabled = isDisabled;
this.changeDetectorRef.markForCheck();
}
@HostListener("focusout")
focusOut() {
this.onTouched();
}
/**
* Executes on the event of a change within `Checkbox` to block propagation.
*/
onChange(event: Event) {
event.stopPropagation();
}
/**
* Handles click events on the `Checkbox` and emits changes to other classes.
*/
onClick(event: Event) {
if (this.click.observers.length) {
// Disable default checkbox activation behavior which flips checked and resets indeterminate.
// This allows the parent component to control the checked/indeterminate properties.
event.preventDefault();
this.click.emit();
return;
}
if (!this.disabled) {
this.toggle();
this.transitionCheckboxState(this._checked ? CheckboxState.Checked : CheckboxState.Unchecked);
this.emitChangeEvent();
}
}
/**
* Called when checkbox is blurred. Needed to properly implement `ControlValueAccessor`.
*/
onTouched: () => any = () => {};
/**
* Handles changes between checkbox states.
*/
transitionCheckboxState(newState: CheckboxState) {
this.currentCheckboxState = newState;
}
/**
* Creates instance of `CheckboxChange` used to propagate the change event.
*/
emitChangeEvent() {
this.checkedChange.emit(this.checked);
this.propagateChange(this.checked);
}
/**
* Updates the checkbox if it is in the indeterminate state.
*/
ngAfterViewInit() {
if (this.indeterminate && this.inputCheckbox && this.inputCheckbox.nativeElement) {
this.inputCheckbox.nativeElement.indeterminate = true;
}
}
/**
* Method set in `registerOnChange` to propagate changes back to the form.
*/
propagateChange = (_: any) => {};
/**
* Sets checked state and optionally resets indeterminate state.
*/
private setChecked(checked: boolean, resetIndeterminate: boolean) {
if (checked === this._checked) {
return;
}
this._checked = checked;
// Reset indeterminate if requested
if (resetIndeterminate && this._indeterminate) {
this._indeterminate = false;
Promise.resolve().then(() => {
this.indeterminateChange.emit(this._indeterminate);
});
}
this.changeDetectorRef.markForCheck();
}
}