carbon-components-angular documentation
  1. Components
  2. Toggle

File

src/toggle/toggle.component.ts

Description

Get started with importing the module:

Example :
import { ToggleModule } from 'carbon-components-angular';
Example :
<cds-toggle [(ngModel)]="toggleState">Toggle</cds-toggle>

See demo

Extends

Checkbox

Metadata

providers { provide: NG_VALUE_ACCESSOR, useExisting: Toggle, multi: true }
selector cds-toggle, ibm-toggle
template 
<ng-container *ngIf="!skeleton; else skeletonTemplate;">
	<button
		class="cds--toggle__button"
		[disabled]="disabled"
		[id]="id"
		role="switch"
		type="button"
		[attr.aria-checked]="checked"
		(click)="onClick($event)"
		[attr.aria-label]="ariaLabel">
	</button>
	<label
		class="cds--toggle__label"
		[for]="id">
		<span
			class="cds--toggle__label-text"
			[ngClass]="{
				'cds--visually-hidden': hideLabel
			}">
			<ng-container *ngIf="!isTemplate(label)">{{label}}</ng-container>
			<ng-template *ngIf="isTemplate(label)" [ngTemplateOutlet]="label"></ng-template>
		</span>
		<div
			class="cds--toggle__appearance"
			[ngClass]="{
				'cds--toggle__appearance--sm': size === 'sm'
			}">
			<div
				class="cds--toggle__switch"
				[ngClass]="{
					'cds--toggle__switch--checked': checked
				}">
				<svg
					*ngIf="size === 'sm'"
					class='cds--toggle__check'
					width="6px"
					height="5px"
					viewBox="0 0 6 5">
					<path d="M2.2 2.7L5 0 6 1 2.2 5 0 2.7 1 1.5z" />
				</svg>
			</div>
			<span class="cds--toggle__text">
				{{(hideLabel ? label : (getCheckedText() | async))}}
			</span>
		</div>
	</label>
</ng-container>
<ng-template #skeletonTemplate>
	<div class="cds--toggle__skeleton-circle"></div>
	<div class="cds--toggle__skeleton-rectangle"></div>
</ng-template>

Index

Properties
Methods
Inputs
Outputs
HostBindings
HostListeners
Accessors

Constructor

constructor(changeDetectorRef: ChangeDetectorRef, i18n: I18n)
Defined in src/toggle/toggle.component.ts:170

Creates an instance of Toggle.

Parameters :
Name Type Optional
changeDetectorRef ChangeDetectorRef No
i18n I18n No

Inputs

ariaLabel
Type : string
Inherited from Checkbox
Defined in Checkbox:151

Set aria-label property for the button when label is empty
hideLabel
Type : boolean
Default value : false
Inherited from Checkbox
Defined in Checkbox:146

Set to true to hide the toggle label & set toggle on/off text to label.
label
Type : string | TemplateRef<any>
Defined in src/toggle/toggle.component.ts:138

Text that is set as the label of the toggle.
offText
Type : string | Observable
Defined in src/toggle/toggle.component.ts:116

Text that is set on the left side of the toggle.
onText
Type : string | Observable
Defined in src/toggle/toggle.component.ts:128

Text that is set on the right side of the toggle.
size
Type : "sm" | "md"
Default value : "md"
Defined in src/toggle/toggle.component.ts:142

Size of the toggle component.
skeleton
Type : boolean
Default value : false
Inherited from Checkbox
Defined in Checkbox:153
ariaLabelledby
Type : string
Inherited from Checkbox
Defined in Checkbox:109
checked
Type : boolean
Inherited from Checkbox
Defined in Checkbox:148

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

Allows double binding with the checkedChange Output.
disabled
Type : boolean
Default value : false
Inherited from Checkbox
Defined in Checkbox:83

Set to true for a disabled checkbox.
id
Type : string
Default value : `checkbox-${Checkbox.checkboxCount}`
Inherited from Checkbox
Defined in Checkbox:99

The unique id for the checkbox component.
indeterminate
Type : boolean
Inherited from Checkbox
Defined in Checkbox:116

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
Inherited from Checkbox
Defined in Checkbox:95

Sets the name attribute on the input element.
required
Type : boolean
Inherited from Checkbox
Defined in Checkbox:103

Reflects the required attribute of the input element.
value
Type : CheckboxValue
Inherited from Checkbox
Defined in Checkbox:107

Sets the value attribute on the input element.

Outputs

checkedChange
Type : EventEmitter
Inherited from Checkbox
Defined in Checkbox:169

Emits an event when the value of the checkbox changes.

Allows double biding with the checked Input.
click
Type : EventEmitter
Inherited from Checkbox
Defined in Checkbox:162

Emits click event.
indeterminateChange
Type : EventEmitter
Inherited from Checkbox
Defined in Checkbox:175

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

HostBindings

class.cds--form-item
Type : boolean
Defined in src/toggle/toggle.component.ts:160
class.cds--toggle
Type : boolean
Default value : true
Defined in src/toggle/toggle.component.ts:155
class.cds--toggle--disabled
Type : any
Defined in src/toggle/toggle.component.ts:156

HostListeners

focusout
focusout()
Inherited from Checkbox
Defined in Checkbox:251

Methods

emitChangeEvent
emitChangeEvent()
Inherited from Checkbox
Defined in Checkbox:208

Creates instance of ToggleChange used to propagate the change event.

Returns : void
getCheckedText
getCheckedText()
Defined in src/toggle/toggle.component.ts:198
Returns : Observable<string>
getOffText
getOffText()
Defined in src/toggle/toggle.component.ts:190
Returns : Observable<string>
getOnText
getOnText()
Defined in src/toggle/toggle.component.ts:194
Returns : Observable<string>
Public isTemplate
isTemplate(value)
Defined in src/toggle/toggle.component.ts:213
Parameters :
Name Optional
value No
Returns : boolean
setDisabledState
setDisabledState(isDisabled: boolean)
Inherited from Checkbox
Defined in Checkbox:186

ControlValueAccessor method to programmatically disable the toggle input.

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

Parameters :
Name Type Optional Description
isDisabled boolean No

true to disable the input
Returns : void
focusOut
focusOut()
Decorators :
@HostListener('focusout')
Inherited from Checkbox
Defined in Checkbox:251
Returns : void
ngAfterViewInit
ngAfterViewInit()
Inherited from Checkbox
Defined in Checkbox:304

Updates the checkbox if it is in the indeterminate state.

Returns : void
onChange
onChange(event: Event)
Inherited from Checkbox
Defined in Checkbox:258

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)
Inherited from Checkbox
Defined in Checkbox:265

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)
Inherited from Checkbox
Defined in Checkbox:226

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)
Inherited from Checkbox
Defined in Checkbox:234

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)
Inherited from Checkbox
Defined in Checkbox:318

Sets checked state and optionally resets indeterminate state.

Parameters :
Name Type Optional
checked boolean No
resetIndeterminate boolean No
Returns : void
Public toggle
toggle()
Inherited from Checkbox
Defined in Checkbox:206

Toggle the selected state of the checkbox.

Returns : void
transitionCheckboxState
transitionCheckboxState(newState: CheckboxState)
Inherited from Checkbox
Defined in Checkbox:289

Handles changes between checkbox states.

Parameters :
Name Type Optional
newState CheckboxState No
Returns : void
Public writeValue
writeValue(value: any)
Inherited from Checkbox
Defined in Checkbox:218

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

Protected _offValues
Default value : this.i18n.getOverridable("TOGGLE.OFF")
Defined in src/toggle/toggle.component.ts:169
Protected _onValues
Default value : this.i18n.getOverridable("TOGGLE.ON")
Defined in src/toggle/toggle.component.ts:170
id
Default value : "toggle-" + Toggle.toggleCount
Defined in src/toggle/toggle.component.ts:167

The unique id allocated to the Toggle.
toggleClass
Default value : true
Decorators :
@HostBinding('class.cds--toggle')
Defined in src/toggle/toggle.component.ts:155
Static toggleCount
Type : number
Default value : 0
Defined in src/toggle/toggle.component.ts:110

Variable used for creating unique ids for toggle components.
_checked
Default value : false
Inherited from Checkbox
Defined in Checkbox:180

Set to true if the input checkbox is selected (or checked).
_indeterminate
Default value : false
Inherited from Checkbox
Defined in Checkbox:184

Set to true if the input checkbox is in state indeterminate.
Static checkboxCount
Type : number
Default value : 0
Inherited from Checkbox
Defined in Checkbox:78

Variable used for creating unique ids for checkbox components.
currentCheckboxState
Default value : CheckboxState.Init
Inherited from Checkbox
Defined in Checkbox:189

Keeps a reference to the checkboxes current state, as defined in CheckboxState.
inputCheckbox
Type : ElementRef
Decorators :
@ViewChild('inputCheckbox')
Inherited from Checkbox
Defined in Checkbox:194

Maintains a reference to the view DOM element of the Checkbox.
onTouched
Type : function
Default value : () => {...}
Inherited from Checkbox
Defined in Checkbox:284

Called when checkbox is blurred. Needed to properly implement ControlValueAccessor.
propagateChange
Default value : () => {...}
Inherited from Checkbox
Defined in Checkbox:313

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

Accessors

offText
getoffText()
Defined in src/toggle/toggle.component.ts:120
setoffText(value: string | Observable)
Defined in src/toggle/toggle.component.ts:116

Text that is set on the left side of the toggle.

Parameters :
Name Type Optional
value string | Observable<string> No
Returns : void
onText
getonText()
Defined in src/toggle/toggle.component.ts:132
setonText(value: string | Observable)
Defined in src/toggle/toggle.component.ts:128

Text that is set on the right side of the toggle.

Parameters :
Name Type Optional
value string | Observable<string> No
Returns : void
disabledClass
getdisabledClass()
Defined in src/toggle/toggle.component.ts:156
formItem
getformItem()
Defined in src/toggle/toggle.component.ts:160
 
import { Checkbox } from "carbon-components-angular/checkbox";
import {
	ChangeDetectorRef,
	Component,
	Input,
	HostBinding,
	TemplateRef
} from "@angular/core";
import { NG_VALUE_ACCESSOR } from "@angular/forms";

import { I18n } from "carbon-components-angular/i18n";
import { Observable } from "rxjs";

/**
 * @deprecated since v5 - Use boolean
 * Defines the set of states for a toggle component.
 */
export enum ToggleState {
	Init,
	Checked,
	Unchecked
}

/**
 * @todo - Toggle component will no longer extend `Checkbox` component as of v6
 * Toggle is no longer repies on using checkbox, so doesn't make sense for us to continue inheriting ALL checkbox
 * component attributes.
 */

/**
 * Get started with importing the module:
 *
 * ```typescript
 * import { ToggleModule } from 'carbon-components-angular';
 * ```
 *
 * ```html
 * <cds-toggle [(ngModel)]="toggleState">Toggle</cds-toggle>
 * ```
 *
 * [See demo](../../?path=/story/components-toggle--basic)
 */
@Component({
	selector: "cds-toggle, ibm-toggle",
	template: `
		<ng-container *ngIf="!skeleton; else skeletonTemplate;">
			<button
				class="cds--toggle__button"
				[disabled]="disabled"
				[id]="id"
				role="switch"
				type="button"
				[attr.aria-checked]="checked"
				(click)="onClick($event)"
				[attr.aria-label]="ariaLabel">
			</button>
			<label
				class="cds--toggle__label"
				[for]="id">
				<span
					class="cds--toggle__label-text"
					[ngClass]="{
						'cds--visually-hidden': hideLabel
					}">
					<ng-container *ngIf="!isTemplate(label)">{{label}}</ng-container>
					<ng-template *ngIf="isTemplate(label)" [ngTemplateOutlet]="label"></ng-template>
				</span>
				<div
					class="cds--toggle__appearance"
					[ngClass]="{
						'cds--toggle__appearance--sm': size === 'sm'
					}">
					<div
						class="cds--toggle__switch"
						[ngClass]="{
							'cds--toggle__switch--checked': checked
						}">
						<svg
							*ngIf="size === 'sm'"
							class='cds--toggle__check'
							width="6px"
							height="5px"
							viewBox="0 0 6 5">
							<path d="M2.2 2.7L5 0 6 1 2.2 5 0 2.7 1 1.5z" />
						</svg>
					</div>
					<span class="cds--toggle__text">
						{{(hideLabel ? label : (getCheckedText() | async))}}
					</span>
				</div>
			</label>
		</ng-container>
		<ng-template #skeletonTemplate>
			<div class="cds--toggle__skeleton-circle"></div>
			<div class="cds--toggle__skeleton-rectangle"></div>
		</ng-template>
	`,
	providers: [
		{
			provide: NG_VALUE_ACCESSOR,
			useExisting: Toggle,
			multi: true
		}
	]
})
export class Toggle extends Checkbox {
	/**
	 * Variable used for creating unique ids for toggle components.
	 */
	static toggleCount = 0;

	/**
	 * Text that is set on the left side of the toggle.
	 */
	@Input()
	set offText(value: string | Observable<string>) {
		this._offValues.override(value);
	}

	get offText() {
		return this._offValues.value;
	}

	/**
	 * Text that is set on the right side of the toggle.
	 */
	@Input()
	set onText(value: string | Observable<string>) {
		this._onValues.override(value);
	}

	get onText() {
		return this._onValues.value;
	}
	/**
	 * Text that is set as the label of the toggle.
	 */
	@Input() label: string | TemplateRef<any>;
	/**
	 * Size of the toggle component.
	 */
	@Input() size: "sm" | "md" = "md";
	/**
	 * Set to `true` to hide the toggle label & set toggle on/off text to label.
	 */
	@Input() hideLabel = false;

	/**
	 * Set `aria-label` property for the button when label is empty
	 */
	@Input() ariaLabel: string;

	@HostBinding("class.cds--toggle--skeleton") @Input() skeleton = false;

	@HostBinding("class.cds--toggle") toggleClass = true;
	@HostBinding("class.cds--toggle--disabled") get disabledClass () {
		return this.disabled;
	}

	@HostBinding("class.cds--form-item") get formItem() {
		return !this.skeleton;
	}

	/**
	 * The unique id allocated to the `Toggle`.
	 */
	id = "toggle-" + Toggle.toggleCount;

	protected _offValues = this.i18n.getOverridable("TOGGLE.OFF");
	protected _onValues = this.i18n.getOverridable("TOGGLE.ON");
	/**
	 * Creates an instance of Toggle.
	 */
	constructor(protected changeDetectorRef: ChangeDetectorRef, protected i18n: I18n) {
		super(changeDetectorRef);
		Toggle.toggleCount++;
	}

	/**
	 * `ControlValueAccessor` method to programmatically disable the toggle input.
	 *
	 * ex: `this.formGroup.get("myToggle").disable();`
	 *
	 * @param isDisabled `true` to disable the input
	 */
	setDisabledState(isDisabled: boolean) {
		this.disabled = isDisabled;
	}

	getOffText(): Observable<string> {
		return this._offValues.subject;
	}

	getOnText(): Observable<string> {
		return this._onValues.subject;
	}

	getCheckedText(): Observable<string> {
		if (this.checked) {
			return this._onValues.subject;
		}
		return this._offValues.subject;
	}

	/**
	 * Creates instance of `ToggleChange` used to propagate the change event.
	 */
	emitChangeEvent() {
		this.checkedChange.emit(this.checked);
		this.propagateChange(this.checked);
	}

	public isTemplate(value) {
		return value instanceof TemplateRef;
	}
}
Legend
Html element
Component
Html element with directive

results matching ""

    No results matching ""