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.

Toggle switch with helper text

Helper toggle

Toggle helper description

<clr-toggle-container>
  <label>Toggle switch with helper text</label>
  <clr-toggle-wrapper>
    <input type="checkbox" clrToggle name="options" required value="option1" [(ngModel)]="options" />
    <label>Helpter toggle</label>
  </clr-toggle-wrapper>
  <clr-control-helper>Toggle helper description</clr-control-helper>
</clr-toggle-container>

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.

Toggle switch with helper text

Helper toggle

Toggle error description

<clr-toggle-container>
  <label>Toggle switch with helper text</label>
  <clr-toggle-wrapper>
    <input type="checkbox" clrToggle name="options" required value="option1" [(ngModel)]="options" />
    <label>Helpter toggle</label>
  </clr-toggle-wrapper>
  <clr-control-error>Toggle error description</clr-control-error>
</clr-toggle-container>

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.

Inline toggle switches example

option 1

option 2

Option 3

Helper for inline toggle control

<clr-toggle-container clrInline>
  <label>Inline toggle switches example</label>
  <clr-toggle-wrapper>
    <input type="checkbox" clrToggle name="toggle-inline1" required value="option1" [(ngModel)]="options" />
    <label>Option 1</label>
  </clr-toggle-wrapper>
  <clr-toggle-wrapper>
    <input type="checkbox" clrToggle name="toggle-inline2" required value="option2" [(ngModel)]="options" />
    <label>Option 2</label>
  </clr-toggle-wrapper>
  <clr-toggle-wrapper>
    <input type="checkbox" clrToggle name="toggle-inline3" required value="option3" [(ngModel)]="options" />
    <label>Option 3</label>
  </clr-toggle-wrapper>
  <clr-control-helper>Helper for inline toggle control</clr-control-helper>
</clr-toggle-container>

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.

Disabled toggle switch

Option 1

Disabled toggle switch

<clr-toggle-container>
  <label>Disabled toggle switch</label>
  <clr-checkbox-wrapper>
    <input type="checkbox" clrToggle name="options" value="option1" [(ngModel)]="options" disabled />
    <label>Option 1</label>
  </clr-checkbox-wrapper>
  <clr-control-helper>Disabled toggle switch text</clr-control-helper>
</clr-toggle-container>

Right Aligned

Toggle switches be right aligned clr-toggle-right class is added to the ClrToggleContainer.

Toggle switch with helper text

Helper toggle

Toggle helper description

<clr-toggle-container class="clr-toggle-right">
  <label>Toggle switch with helper text</label>
  <clr-toggle-wrapper>
    <input type="checkbox" clrToggle name="options" required value="option1" [(ngModel)]="options" />
    <label>Helpter toggle</label>
  </clr-toggle-wrapper>
  <clr-control-helper>Toggle helper description</clr-control-helper>
</clr-toggle-container>

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

1. Programmatically associating the correct label for attribute with the id of the input
2. Automatic wiring up of the aria-describedby behavior with associated clr-control-error elements
3. An aria-live region that can notify screen readers about changes in the control error state
4. Adds the label to a general form summary for screen readers when the control is in an error state after a form submit