Use toggles when users can toggle between two states or options, and the changes take effect immediately.
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.
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.
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.
@skyux/forms
View in NPM | View in GitHub None found. npm install --save-exact @skyux/forms
None found. import { SkyToggleSwitchModule } from '@skyux/forms';
Selector: sky-toggle-switch
ariaLabel: string | undefined
labelText
input instead.
The ARIA label for the toggle switch. This sets the aria-label
attribute to provide a text equivalent for screen readers to support accessibility.
Use a context-sensitive label, such as "Activate annual fundraiser" for a toggle switch that activates and deactivates an annual fundraiser. Context is especially important if multiple toggle switches are in close proximity.
When the sky-toggle-switch-label
component displays a visible label, this property is only necessary if that label requires extra context.
For more information about the aria-label
attribute, see the WAI-ARIA definition.
checked: boolean
Whether the toggle switch is selected.
Default: false
disabled: boolean | undefined
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 FormControl
instead.
Default: false
helpKey: string | undefined
A help key that identifies the global help content to display. When specified along with labelText
, 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 labelText
is also specified.
helpPopoverContent: string | TemplateRef<unknown> | undefined
The content of the help popover. When specified along with labelText
, a help inline
button is added to the toggle switch. The help inline button displays a popover
when clicked using the specified content and optional title. This property only applies when labelText
is also specified.
helpPopoverTitle: string | undefined
The title of the help popover. This property only applies when helpPopoverContent
is
also specified.
labelHidden: boolean
Whether to hide labelText
from view.
Default: false
labelText: string | undefined
The text to display as the toggle switch's label.
tabIndex: number | undefined
The tab index for the toggle switch. If not defined, the index is set to the position of the toggle switch on load.
Default: 0
toggleChange: EventEmitter<SkyToggleSwitchChange>
Fires when the checked state of a toggle switch changes.
Selector: sky-toggle-switch-label
labelText
input on the toggle switch component instead.
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.
Indicates whether the toggle switch is selected.
interface SkyToggleSwitchChange {
checked: boolean;
}
checked: boolean
SKY UX test harnesses are built upon Angular CDK component harnesses. For more information see the Angular CDK component harness documentation.
import { SkyToggleSwitchHarness } from '@skyux/forms/testing';
Harness for interacting with a toggle switch component in tests.
blur(): Promise<void>
Blurs the toggle switch.
Promise<void>
check(): Promise<void>
Puts the toggle switch in a checked state.
Promise<void>
clickHelpInline(): Promise<void>
Clicks the help inline button.
Promise<void>
focus(): Promise<void>
Focuses the toggle switch.
Promise<void>
getHelpPopoverContent(): Promise<undefined | string>
Gets the help popover content.
Promise<undefined | string>
getHelpPopoverTitle(): Promise<undefined | string>
Gets the help popover title.
Promise<undefined | string>
getLabelHidden(): Promise<boolean>
Whether the label is hidden. Only supported when using the labelText
input to set the label.
Promise<boolean>
getLabelText(): Promise<undefined | string>
Gets the toggle switch's label text. If the label is set via labelText
and labelHidden
is true,
the text will still be returned.
Promise<undefined | string>
isChecked(): Promise<boolean>
Whether the toggle switch is checked.
Promise<boolean>
isDisabled(): Promise<boolean>
Whether the toggle switch is disabled.
Promise<boolean>
isFocused(): Promise<boolean>
Whether the toggle switch is focused.
Promise<boolean>
uncheck(): Promise<void>
Puts the toggle switch in an unchecked state.
Promise<void>
SkyToggleSwitchHarness.with(filters: SkyToggleSwitchHarnessFilters): HarnessPredicate<SkyToggleSwitchHarness>
Gets a HarnessPredicate
that can be used to search for a
SkyToggleSwitchHarness
that meets certain criteria.
filters: SkyToggleSwitchHarnessFilters
HarnessPredicate<SkyToggleSwitchHarness>
A set of criteria that can be used to filter a list of SkyToggleSwitchHarness
instances.
interface SkyToggleSwitchHarnessFilters {
dataSkyId?: string | RegExp;
}
dataSkyId?: string | RegExp
Only find instances whose data-sky-id
attribute matches the given value.
Loading...