File

src/checkbox/checkbox.component.ts

Description

Get started with importing the module:

Example :
import { CheckboxModule } from 'carbon-components-angular';

See demo

Implements

ControlValueAccessor AfterViewInit

Metadata

Index

Properties
Methods
Inputs
Outputs
HostListeners
Accessors

Constructor

constructor(changeDetectorRef: ChangeDetectorRef)

Creates an instance of Checkbox.

Parameters :
Name Type Optional
changeDetectorRef ChangeDetectorRef No

Inputs

ariaLabel
Type : string
ariaLabelledby
Type : string
checked
Type : boolean

Sets the checked state. true for checked, false for unchecked

Allows double binding with the checkedChange Output.

disabled
Type : boolean
Default value : false

Set to true for a disabled checkbox.

hideLabel
Type : boolean
Default value : false

Set to true to hide the checkbox labels.

id
Type : string
Default value : `checkbox-${Checkbox.checkboxCount}`

The unique id for the checkbox component.

indeterminate
Type : boolean

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.

name
Type : string

Sets the name attribute on the input element.

required
Type : boolean

Reflects the required attribute of the input element.

skeleton
Type : boolean
Default value : false

Set to true for a loading checkbox.

value
Type : CheckboxValue

Sets the value attribute on the input element.

Outputs

checkedChange
Type : EventEmitter

Emits an event when the value of the checkbox changes.

Allows double biding with the checked Input.

click
Type : EventEmitter

Emits click event.

indeterminateChange
Type : EventEmitter

Emits event notifying other classes when a change in state occurs specifically on an indeterminate checkbox.

HostListeners

focusout
focusout()

Methods

emitChangeEvent
emitChangeEvent()

Creates instance of CheckboxChange used to propagate the change event.

Returns : void
focusOut
focusOut()
Decorators :
@HostListener('focusout')
Returns : void
ngAfterViewInit
ngAfterViewInit()

Updates the checkbox if it is in the indeterminate state.

Returns : void
onChange
onChange(event: Event)

Executes on the event of a change within Checkbox to block propagation.

Parameters :
Name Type Optional
event Event No
Returns : void
onClick
onClick(event: Event)

Handles click events on the Checkbox and emits changes to other classes.

Parameters :
Name Type Optional
event Event No
Returns : void
Public registerOnChange
registerOnChange(fn: any)

Sets a method in order to propagate changes back to the form.

Parameters :
Name Type Optional
fn any No
Returns : void
Public registerOnTouched
registerOnTouched(fn: any)

Registers a callback to be triggered when the control has been touched.

Parameters :
Name Type Optional Description
fn any No

Callback to be triggered when the checkbox is touched.

Returns : void
Private setChecked
setChecked(checked: boolean, resetIndeterminate: boolean)

Sets checked state and optionally resets indeterminate state.

Parameters :
Name Type Optional
checked boolean No
resetIndeterminate boolean No
Returns : void
setDisabledState
setDisabledState(isDisabled: boolean)

ControlValueAccessor method to programmatically disable the checkbox.

ex: this.formGroup.get("myCheckbox").disable();

Parameters :
Name Type Optional Description
isDisabled boolean No

true to disable the checkbox

Returns : void
Public toggle
toggle()

Toggle the selected state of the checkbox.

Returns : void
transitionCheckboxState
transitionCheckboxState(newState: CheckboxState)

Handles changes between checkbox states.

Parameters :
Name Type Optional
newState CheckboxState No
Returns : void
Public writeValue
writeValue(value: any)

Writes a value from ngModel to the component.

In this case the value is the checked property.

Parameters :
Name Type Optional Description
value any No

boolean, corresponds to the checked property.

Returns : void

Properties

_checked
Default value : false

Set to true if the input checkbox is selected (or checked).

_indeterminate
Default value : false

Set to true if the input checkbox is in state indeterminate.

Static checkboxCount
Type : number
Default value : 0

Variable used for creating unique ids for checkbox components.

currentCheckboxState
Default value : CheckboxState.Init

Keeps a reference to the checkboxes current state, as defined in CheckboxState.

inputCheckbox
Type : ElementRef
Decorators :
@ViewChild('inputCheckbox')

Maintains a reference to the view DOM element of the Checkbox.

onTouched
Type : function
Default value : () => {...}

Called when checkbox is blurred. Needed to properly implement ControlValueAccessor.

propagateChange
Default value : () => {...}

Method set in registerOnChange to propagate changes back to the form.

Accessors

indeterminate
getindeterminate()

Reflects whether the checkbox state is indeterminate.

setindeterminate(indeterminate: boolean)

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.

Parameters :
Name Type Optional
indeterminate boolean No
Returns : void
checked
getchecked()

Returns value true if state is selected for the checkbox.

setchecked(checked: boolean)

Sets the checked state. true for checked, false for unchecked

Allows double binding with the checkedChange Output.

Parameters :
Name Type Optional
checked boolean No
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();
	}
}
Legend
Html element
Component
Html element with directive

results matching ""

    No results matching ""