Toggle switch

Toggle switches are used to switch between two possible states.

Examples

Base

Web Component
HTML Blueprint

<chi-switch id="toggle-ba1" label="Label"></chi-switch>

<div class="chi-form__item">
  <label class="chi-switch" for="toggle-ba1">
    <input type="checkbox" class="chi-switch__input" id="toggle-ba1">
    <span class="chi-switch__content">
      <span class="chi-switch__thumb"></span>
    </span>
    <span class="chi-switch__label">Label</span>
  </label>
</div>

Checked

Use the checked boolean attribute to set the default value of a toggle switch to true.

Web Component
HTML Blueprint

<chi-switch id="toggle-ch1" label="Label" checked></chi-switch>

<div class="chi-form__item">
  <label class="chi-switch" for="toggle-ch1">
    <input type="checkbox" class="chi-switch__input" id="toggle-ch1" checked>
    <span class="chi-switch__content">
      <span class="chi-switch__thumb"></span>
    </span>
    <span class="chi-switch__label">Label</span>
  </label>
</div>

Disabled

Use the disabled boolean attribute to prevent users from interacting with an input. Disabled inputs are not submitted with the form and can not receive any browsing events such as mouse clicks or focus. Note: The required attribute can not be used on inputs with a disabled attribute specified.

Web Component
HTML Blueprint

<chi-switch id="toggle-di1" label="Label" disabled></chi-switch>

<div class="chi-form__item">
  <label class="chi-switch" for="toggle-di1">
    <input type="checkbox" class="chi-switch__input" name="toggle-di1" value="toggle-di1" disabled>
    <span id="toggle-di1" class="chi-switch__content">
      <span class="chi-switch__thumb"></span>
    </span>
    <span class="chi-switch__label">Label</span>
  </label>
</div>

Layout Variations

<div class="chi-form__item">
  <chi-switch id="toggle3" label="Label"></chi-switch>
</div>
<div class="chi-form__item">
  <chi-switch id="toggle4" label="Label"></chi-switch>
</div>

<fieldset>
  <legend class="chi-label">Configure options</legend>
  <div class="chi-form__item">
    <label class="chi-switch" for="toggle3">
      <input type="checkbox" class="chi-switch__input" id="toggle3">
      <span class="chi-switch__content">
        <span class="chi-switch__thumb"></span>
      </span>
      <span class="chi-switch__label">Label</span>
    </label>
  </div>
  <div class="chi-form__item">
    <label class="chi-switch" for="toggle4">
      <input type="checkbox" class="chi-switch__input" id="toggle4">
      <span class="chi-switch__content">
        <span class="chi-switch__thumb"></span>
      </span>
      <span class="chi-switch__label">Label</span>
    </label>
  </div>
</fieldset>

Inline

Web Component
HTML Blueprint

Apply the -inline class to chi-form__item for displaying toggle switches inline.

<div class="chi-form__item -inline">
  <chi-switch id="toggle5" label="Label"></chi-switch>
</div>
<div class="chi-form__item -inline">
  <chi-switch id="toggle6" label="Label"></chi-switch>
</div>

Apply the class -inline to chi-form__item to display switches inline.

<fieldset>
  <legend class="chi-label">Configure options</legend>
  <div class="chi-form__item -inline">
    <label class="chi-switch" for="toggle5">
      <input type="checkbox" class="chi-switch__input" id="toggle5">
      <span class="chi-switch__content">
        <span class="chi-switch__thumb"></span>
      </span>
      <span class="chi-switch__label">Label</span>
    </label>
  </div>
  <div class="chi-form__item -inline">
    <label class="chi-switch" for="toggle6">
      <input type="checkbox" class="chi-switch__input" id="toggle6">
      <span class="chi-switch__content">
        <span class="chi-switch__thumb"></span>
      </span>
      <span class="chi-switch__label">Label</span>
    </label>
  </div>
</fieldset>

Switch list

Switch lists are used to wrap a series of switches in a list. To render, apply the class -list to chi-form__item.

Web Component
HTML Blueprint

<fieldset>
  <legend class="chi-label">Select options</legend>
  <ul class="chi-form__item -list">
    <li class="chi-form__item">
      <label class="chi-switch" for="toggle10">
        <span class="chi-switch__label">Label</span>
        <input type="checkbox" class="chi-switch__input" id="toggle10">
        <span class="chi-switch__content">
          <span class="chi-switch__thumb"></span>
        </span>
      </label>
    </li>
    <li class="chi-form__item">
      <label class="chi-switch" for="toggle11">
        <span class="chi-switch__label">Label</span>
        <input type="checkbox" class="chi-switch__input" id="toggle11">
        <span class="chi-switch__content">
          <span class="chi-switch__thumb"></span>
        </span>
      </label>
    </li>
    <li class="chi-form__item">
      <label class="chi-switch" for="toggle12">
        <span class="chi-switch__label">Label</span>
        <input type="checkbox" class="chi-switch__input" id="toggle12">
        <span class="chi-switch__content">
          <span class="chi-switch__thumb"></span>
        </span>
      </label>
    </li>
    <li class="chi-form__item">
      <label class="chi-switch" for="toggle13">
        <span class="chi-switch__label">Label</span>
        <input type="checkbox" class="chi-switch__input" id="toggle13">
        <span class="chi-switch__content">
          <span class="chi-switch__thumb"></span>
        </span>
      </label>
    </li>
    <li class="chi-form__item" for="toggle14">
      <label class="chi-switch">
        <span class="chi-switch__label">Label</span>
        <input type="checkbox" class="chi-switch__input" id="toggle14">
        <span class="chi-switch__content">
          <span class="chi-switch__thumb"></span>
        </span>
      </label>
    </li>
  </ul>
</fieldset>

Switch with Left Label

Label

Web Component
HTML Blueprint

<div class="chi-form__item">
  <label class="chi-switch" for="toggle7">
    <span class="chi-switch__label">Label</span>
    <input type="checkbox" class="chi-switch__input" id="toggle7">
    <span class="chi-switch__content">
      <span class="chi-switch__thumb"></span>
    </span>
  </label>
</div>

Switch with Hidden Label

Web Component
HTML Blueprint

Apply the hide-label attribute to chi-switch to render a switch without a label. Use this method for rendering switches in close proximity to other text that clearly describes its purpose.

<div class="chi-form__item">
  <chi-switch id="toggle8" label="Label" hide-label></chi-switch>
</div>

Apply the class -label--hide to chi-switch to render a switch without a label. Use this method for rendering switches in close proximity to other text that clearly describes its purpose.

<div class="chi-form__item">
  <label class="chi-switch -label--hide" for="toggle8">
    <input type="checkbox" class="chi-switch__input" id="toggle8">
    <span class="chi-switch__content">
      <span class="chi-switch__thumb"></span>
    </span>
    <span class="chi-switch__label">Label</span>
  </label>
</div>

Sizes

Toggle switch supports different sizes: xs, sm. The default size is sm.

Web Component
HTML Blueprint

<!-- xs -->
<div class="chi-form__item">
  <chi-switch id="toggle15" label="Label" size="xs"></chi-switch>
</div>

<!-- sm -->
<div class="chi-form__item">
  <chi-switch id="toggle16" label="Label" size="sm"></chi-switch>
</div>

<!-- xs -->
<div class="chi-form__item">
  <label class="chi-switch -xs" for="toggle15">
    <input type="checkbox" class="chi-switch__input" id="toggle15">
    <span class="chi-switch__content">
      <span class="chi-switch__thumb"></span>
    </span>
    <span class="chi-switch__label">Label</span>
  </label>
</div>

<!-- sm -->
<div class="chi-form__item">
  <label class="chi-switch -sm" for="toggle16">
    <input type="checkbox" class="chi-switch__input" id="toggle16">
    <span class="chi-switch__content">
      <span class="chi-switch__thumb"></span>
    </span>
    <span class="chi-switch__label">Label</span>
  </label>
</div>

Size

Toggle switch supports one size: sm.

Web Component
HTML Blueprint

<!-- sm -->
<div class="chi-form__item">
  <chi-switch id="toggle18" label="Label" size="sm"></chi-switch>
</div>

<!-- sm -->
<div class="chi-form__item">
  <label class="chi-switch -sm" for="toggle16">
    <input type="checkbox" class="chi-switch__input" id="toggle18">
    <span class="chi-switch__content">
      <span class="chi-switch__thumb"></span>
    </span>
    <span class="chi-switch__label">Label</span>
  </label>
</div>

Web Component

Properties

Property	Attribute	Description	Type	Default
`checked`	`checked`	used to check the toggle switch.	`boolean`	`false`
`disabled`	`disabled`	used to disable the toggle switch.	`boolean`	`false`
`hideLabel`	`hide-label`	used to disable the toggle labels.	`boolean`	`false`
`label`	`label`	to set a label for the toggle switch.	`string`	undefined
`size`	`size`	OPTIONAL. Size of the label. { xs, sm }.	`string`	undefined

Events

Event	Description	Type
`toggle`	emitting a custom event toggle.	`CustomEvent<any>`

Accessibility

Keyboard Navigation

Key	Function
`Tab`	Moves keyboard focus to the switch.
`Space`,`Enter`	Changes state of the switch to checked or not checked.

For comprehensive details on keyboard support for toggle switch, refer to our Keyboard Control Guide.

Visit WebAIM for keyboard techniques.

Ensure each toggle switch is accompanied by a label. Use the aria-labelledby attribute on the toggle switch that matches the id of the label element. This is crucial for screen reader users to understand the purpose of the switch.
Use aria-checked to indicate whether the toggle switch is in the "on" or "off" state. This attribute should dynamically change as the toggle state changes to keep assistive technologies informed.
Toggles should be operable using keyboard alone. Ensure that users can tab to the toggle switch and change its state using keyboard keys like Space or Enter.
Implement the toggle using a button element assigned with a role="switch". This approach ensures that the element is recognized correctly by assistive technologies.

Ensure that the toggle switch includes non-color visual indicators (e.g., text labels or distinctive shapes) to convey its state. This helps users with color vision deficiencies.
According to WCAG Success Criterion 3.2.2 (On Input), avoid designs where flipping a switch causes immediate changes in context or navigation. If such changes are necessary, provide clear warnings before the switch is used, or offer a way to undo the change.
Maintain high contrast ratios for all textual and graphical elements of the toggle switch to ensure legibility and visibility under various lighting conditions.
Ensure that toggle switches are large enough to be easily manipulated by users with limited dexterity, and spaced sufficiently to prevent accidental activation.

Find live examples in the A11y Style Guide.

Roles and attributes

The following list provides essential roles and attributes you should consider to ensure our components are fully accessible across various interface scenarios.

Attribute	Element	Usage
`aria-label`	`div`	Defines a string value that labels an interactive element. It is required props for controls without text content.
`aria-labelledby`	`div`	The aria-labelledby attribute identifies the element (or elements) that labels the element it is applied to. It is required props for controls without text content.

Resources

W3 Switch Example: Contains comprehensive details regarding the accessibility behavior of the switch .
Mozilla Resources for Developers: Find examples of accessible switches.

Other recommendations

Explore additional accessibility tips in the general Accessibility Guide.

WCAG 2.2 Guidelines

Non-text Content: All non-text content that is presented to the user has a text alternative that serves the equivalent purpose. (Level A)
Info and Relationships: Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A)
Headings and Labels: Headings and labels describe topic or purpose. (Level AA)
Labels or Instructions: Labels or instructions are provided when content requires user input. (Level A)
Name, Role, Value: For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies. (Level A)