Skip to content

Toggle

An on/off switch. Unlike the Checkbox, it represents a change that applies immediately. Supports a loading state and icons in the thumb.

Forms · TaishoDS Core, in plain HTML.

Examples

One working example per case. Each example is the HTML of its preview—copy it as is, and with Core’s CSS and JS loaded, it looks and works the same.

Notifications on

html

Dark mode off

html

Option locked by plan

html

Class reference

Every value of each modifier, with its HTML ready to copy.

Size

Switch size: sm, md, or lg.

html

Variant

The color when on. primary by default, which takes the theme primary (primary; the brand if you don’t set one), or a status color.

html

States

The switch states: is-checked, is-disabled, and is-loading.

html

Combinations

Size and color combined.

html

When to use

  • A setting that turns on or off and takes effect immediately (a preference).
  • The on/off state speaks for itself, with no need to “save.”
  • You want to show that something is happening while it applies (loading state).

When not to use

  • The value is only confirmed when a form is submitted → checkbox.
  • It’s a choice between options, not on/off → radio or segmented-control.

Do

  • Write a label that names the “on” state, not an action.
  • If applying takes a while, show the loading state instead of faking the result.

Don’t

  • Don’t use it inside a form that gets submitted later → checkbox.
  • Don’t use it for three or more states. It’s binary.

TaishoDS Core

Needs Core’s JS, which hooks in through data-ts-* attributes.

It’s a native <input type="checkbox"> styled as a switch. To paint the state, Core mirrors checked to the label’s is-checked class and to the switch’s aria-checked.

What it does: When the switch changes, it mirrors checked to the label’s is-checked class and, if the field has role="switch", to its aria-checked, so the state is announced. Keyboard, focus, and submission are the browser’s.

From the CDN, without a build, load taisho.toggle.css along with taisho.base.css. Also load:

  • taisho.spinner.css

For how Core works in general, see Behavior.

Accessibility

Implements the Switch pattern from the WAI-ARIA APG.

  • Uses role="switch" with aria-checked.
  • When loading, write is-loading, aria-busy="true", and disabled together. The class alone only changes the look and isn’t announced.
  • The label is associated with the control and also works as a click target.

Verification

What was actually tested. Anything that wasn’t tested says so—we’d rather say “not verified” than claim too much.

  • axe WCAG 2.2 A + AA in a real browser, in light and dark mode, before every release.
  • keyboard Adds no keys of its own—it uses the browser’s native behavior.
  • screen reader Not verified with a screen reader. Test it in your own combination of components, not just here, where each one appears alone and on its happy path.