Toggle
Toggle switches allow the selection of on
or off
state.
Usage
Use a toggle switch when there is need to select a single options. E.g - on
and off
.
Toggle switches take up less space than an “on/off” radio button group and communicate their intended purpose better than a checkbox that toggles functionality.
Anatomy
Toggle inputs should be composed with the necessary parts needed to communicate relevant information to users.
Label
Use a label to clearly describe the setting. You will need to wrap your toggle switches with the ClrToggleWrapper component when you include a label. This manages the label and display of the toggle switch for you.
Clarity supports a toggle switch without a label but beware, only use this approach if the purpose of the control clearly made elsewhere. For example, if there is a group label or section header that allows the user to infer the description of the option.
Helper Message
To use helper messages, wrap all toggle switches inside of the ClrToggleContainer. Helper messages are always visible with one exception. The toggle switch container tracks any validations placed on the toggle switch(es) and will replace helper messages with an error message if there is one.
Error Message
To use error messages, wrap all toggle switches inside of the ClrToggleContainer. The toggle switch container tracks any validations placed on the toggle switch(es) and will display the error message when appropriate.
States
There are two states that can change the layout and look of a ClrToggle control.
Inline
Toggle switches can be placed inline when the clrInline directive is added to the ClrToggleContainer. The toggle switches will wrap if there is not enough space.
Disabled
A toggle switch can be disabled by putting the disabled attribute on the checkbox input. This requires that the toggle switch be inside of a ClrToggleContainer. When disabling groups of toggle switches, the last checkbox requires the disabled attribute. Angular doesn't support disabling individual checkboxes in a group.
Accessibility
For applications using the ClrToggle directive and the associated ClrToggleContainer and ClrToggleWrapper components there is built in support adding accessible behavior to the control and its form.
Included Behavior
- Programmatically associating the correct label for attribute with the id of the input
- Automatic wiring up of the aria-describedby behavior with associated clr-control-error elements
- An aria-live region that can notify screen readers about changes in the control error state
- Adds the label to a general form summary for screen readers when the control is in an error state after a form submit