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<...> |