Toggle switch | iTwinUI

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.

Application of props

By default, className and style are applied on the wrapper element, and all other DOM props are passed to <input> element.

When wrapperProps is passed or when the ToggleSwitch.consistentPropsSpread future flag is enabled, className and style are applied on the <input> element, similar to other DOM props.

Below are some examples of how props are applied in different scenarios:

Default:

<ThemeProvider>
  <ToggleSwitch
    className='my-class' // applied to wrapper
    style={{ padding: 16 }} // applied to wrapper
    //
    // Other props are applied to input
    data-dummy='value' // applied to input
  />
</ThemeProvider>

With wrapperProps:

<ToggleSwitch
  className='my-class' // applied to input
  style={{ padding: 16 }} // applied to input
  wrapperProps={{
    className: 'my-wrapper-class', // applied to wrapper
    style: { padding: 16 }, // applied to wrapper
  }}
  //
  // Other props are applied to input
  data-dummy='value' // applied to input
/>

ThemeProvider’s ToggleSwitch.consistentPropsSpread is enabled:

<ThemeProvider future={{ ToggleSwitch: { consistentPropsSpread: true } }}>
  <ToggleSwitch
    className='my-class' // applied to input
    style={{ padding: 16 }} // applied to input
    //
    // Other props are applied to input
    data-dummy='value' // applied to input
  />
</ThemeProvider>

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'
wrapperProps	Passes props to wrapper. By default, `className` and `style` are applied on the wrapper element, and all other DOM props are passed to `<input>` element. When `wrapperProps` is passed or when the `ToggleSwitch.consistentPropsSpread` future flag is enabled, `className` and `style` are applied on the `<input>` element, similar to other DOM props. HTMLAttributes<HTMLElement>
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" \| ... 160 more ... \| FunctionComponent<...>