Toggle switch
Use when
Use toggles when users can toggle between two states or options, and the changes take effect immediately.
Don't use when
Don't use toggles when the options have significant consequences that the users need to confirm before changes take effect. Use a workflow where users must confirm the changes instead.
Don't use toggles when the input is presented in a modal. Use checkboxes instead.
Label
Text labels describe the properties that toggles control, and you can provide labels for both the selected and unselected states. Always include text labels unless other text clearly indicates the purpose of toggles. For example, when toggles are in grids, you can rely on column headings instead of text labels.
In scenarios where toggles may become disabled, always include labels for both the selected and unselected states to make those states clear to users.
Help inline button
When you need to supplement a toggle switch label with additional information, you can place a help inline button beside the label to invoke contextual user assistance.
Components
Guidelines
- Defined in
SkyToggleSwitchModule- NPM package
@skyux/forms- Installation
- None found.
npm install --save-exact @skyux/forms
Specifies the label to display beside the toggle switch. To display a help button beside the label, include a help
button element, such as sky-help-inline, in the sky-toggle-switch element and a sky-control-help CSS class on
that help button element.
Selector
sky-toggle-switch-label
Selector
sky-toggle-switch
| Input | Description |
|---|---|
| Deprecated. Use the The ARIA label for the toggle switch. This sets the Optional. |
checked?: boolean | Whether the toggle switch is selected. Optional. Default is false |
disabled?: boolean | Whether to disable the toggle switch on template-driven forms. Don't use this input on reactive forms because they may overwrite the input or leave the control out of sync.
To set the disabled state on reactive forms, use the Optional. Default is false |
helpKey?: string | A help key that identifies the global help content to display. When specified, a help inline
button is placed beside the toggle switch label. Clicking the button invokes global help
as configured by the application. This property only applies when Optional. |
helpPopoverContent?: string | TemplateRef<unknown> | The content of the help popover. When specified along with Optional. |
helpPopoverTitle?: string | The title of the help popover. This property only applies when Optional. |
labelHidden?: boolean | Whether to hide Optional. Default is false |
labelText?: string | The text to display as the toggle switch's label. Optional. |
tabIndex?: number | The tab index for the toggle switch. If not defined, the index is set to the position of the toggle switch on load. Optional. Default is 0 |
| Event | Description |
|---|---|
toggleChange: EventEmitter<SkyToggleSwitchChange> | Fires when the checked state of a toggle switch changes. |
Indicates whether the toggle switch is selected.
interface SkyToggleSwitchChange {
checked: boolean;
}| Property | Description |
|---|---|
checked: boolean |
<form [formGroup]="formGroup">
<sky-toggle-switch
formControlName="registration"
labelText="Open for registration"
[helpPopoverContent]="helpPopoverContent"
/>
</form>import { Component, inject } from '@angular/core';
import {
FormBuilder,
FormControl,
FormGroup,
FormsModule,
ReactiveFormsModule,
} from '@angular/forms';
import { SkyToggleSwitchModule } from '@skyux/forms';
interface ToggleSwitchFormType {
registration: FormControl<boolean | null>;
}
@Component({
standalone: true,
selector: 'app-demo',
templateUrl: './demo.component.html',
imports: [FormsModule, ReactiveFormsModule, SkyToggleSwitchModule],
})
export class DemoComponent {
protected formGroup: FormGroup;
protected helpPopoverContent =
'When you open an event, a registration page becomes available online, and admins are able to register people to attend.';
constructor() {
this.formGroup = inject(FormBuilder).group<ToggleSwitchFormType>({
registration: new FormControl(false),
});
}
}<form [formGroup]="formGroup">
<div class="sky-font-heading-2 sky-margin-stacked-lg">Annual fundraiser</div>
<div class="sky-margin-stacked-lg">
<sky-toggle-switch
ariaLabel="Activate annual fundraiser"
formControlName="controlToggle"
>
<sky-toggle-switch-label> Active </sky-toggle-switch-label>
<sky-help-inline
class="sky-control-help"
(actionClick)="onHelpClick()"
ariaLabel="Information about top toggle switch"
/>
</sky-toggle-switch>
</div>
<div class="sky-margin-stacked-lg">
<sky-toggle-switch
ariaLabel="Annual fundraiser is accepting donations"
formControlName="dynamicToggle"
>
<sky-toggle-switch-label> Accepting donations </sky-toggle-switch-label>
<sky-help-inline
class="sky-control-help"
(actionClick)="onHelpClick()"
ariaLabel="Information about bottom toggle switch"
/>
</sky-toggle-switch>
</div>
</form>import { Component, OnDestroy, inject } from '@angular/core';
import {
FormBuilder,
FormControl,
FormGroup,
FormsModule,
ReactiveFormsModule,
} from '@angular/forms';
import { SkyToggleSwitchModule } from '@skyux/forms';
import { SkyHelpInlineModule } from '@skyux/indicators';
import { Subject, takeUntil } from 'rxjs';
interface ToggleSwitchFormType {
controlToggle: FormControl<boolean | null>;
dynamicToggle: FormControl<boolean | null>;
}
@Component({
standalone: true,
selector: 'app-demo',
templateUrl: './demo.component.html',
imports: [
FormsModule,
ReactiveFormsModule,
SkyHelpInlineModule,
SkyToggleSwitchModule,
],
})
export class DemoComponent implements OnDestroy {
protected formGroup: FormGroup;
#ngUnsubscribe = new Subject<void>();
constructor() {
this.formGroup = inject(FormBuilder).group<ToggleSwitchFormType>({
controlToggle: new FormControl(false),
dynamicToggle: new FormControl({ value: true, disabled: true }),
});
this.formGroup
.get('controlToggle')
?.valueChanges.pipe(takeUntil(this.#ngUnsubscribe))
.subscribe((value) => {
if (value) {
this.formGroup.get('dynamicToggle')?.enable();
} else {
this.formGroup.get('dynamicToggle')?.disable();
}
});
}
public ngOnDestroy(): void {
this.#ngUnsubscribe.next();
this.#ngUnsubscribe.complete();
}
protected onHelpClick(): void {
alert(`Help clicked`);
}
}