Skip to Content

Toggle switch

The toggle switch is a high contrast component used for toggling settings that only have two states.

import * as React from 'react';
import { ToggleSwitch } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <ToggleSwitch label='Option 1' defaultChecked={true} />
      <ToggleSwitch label='Option 2' defaultChecked={false} />
      <ToggleSwitch label='Option 3' defaultChecked={true} disabled />
      <ToggleSwitch label='Option 4' defaultChecked={false} disabled />
    </div>
  );
};

Toggle switches are instant action components used to toggle an option instantly with a single click or tap. They are more common in mobile layouts, but are also present in desktop environments. For example, on mobile, you can go to the settings menu and enable or disable wi-fi, airplane mode and sound with a single tap using the associated toggle switch.

It fulfills a role similar to that of a checkbox, though they are not necessarily used in the same contexts. To learn more about when to use a toggle switch or a checkbox, please read Checkbox vs Toggle Switch by Saadia Minhas.

Usage

Sizes

There are two sizes available.

import * as React from 'react';
import { ToggleSwitch } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <ToggleSwitch label='Small' size='small' defaultChecked={true} />
      <ToggleSwitch label='Medium' defaultChecked={true} />
    </div>
  );
};

Label placement

A toggle switch’s label can be placed on the right (default), left, or not used at all although it is strongly recommended that a label should be used.

import * as React from 'react';
import { ToggleSwitch } from '@itwin/itwinui-react';

export default () => {
  return (
    <div className='demo-container'>
      <ToggleSwitch label='Label on the right' defaultChecked={true} />
      <ToggleSwitch
        label='Label on the left'
        labelPosition='left'
        defaultChecked={true}
      />
    </div>
  );
};

With input group

Toggle switches can be paired with the input group which gives many additional options.

import * as React from 'react';
import { ToggleSwitch, InputGroup } from '@itwin/itwinui-react';

export default () => {
  return (
    <InputGroup label='Home lights'>
      <ToggleSwitch label='Dining room' defaultChecked={true} />
      <ToggleSwitch label='Garage' defaultChecked={false} />
      <ToggleSwitch label='Kitchen' defaultChecked={true} />
      <ToggleSwitch label='Living room' defaultChecked={false} />
    </InputGroup>
  );
};

Props

Prop Description Default
label
Label for the toggle switch.
ReactNode
labelProps
Passes properties for ToggleSwitch label.
DetailedHTMLProps<HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>
labelPosition
Position of the label.
"left" | "right"
'right'
size
Size of the toggle switch.
"small" | "default"
'default'
icon
Custom icon inside the toggle switch. Shown only when toggle is checked and size is not small.
Will override the default checkmark icon.
Element
as
"symbol" | "object" | "input" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 159 more ... | FunctionComponent<...>