ToggleSwitch

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/components-base

Package version

1.6.1

Loading...

<ToggleSwitch label="Enable data" tooltip="Toggle this on to enable data" />

<ToggleSwitch label="Enable data" tooltip="Toggle this on to enable data" />

Introduction

import { ToggleSwitch } from '@telus-uds/components-base'

Use ToggleSwitch to control a boolean state.

Guidance

• Use ToggleSwitch where a user can alternate between easy-to-understand "on" and "off" states.
• Use ToggleSwitchGroup if you need to combine several switches and / or implement a radio group-like behavior.

Uncontrolled usage with initialValue prop

By default, ToggleSwitch controls its own state. Its default state may be set using initialValue prop, and onChange may also be passed to trigger an action when the value changes.

Loading...

<ToggleSwitch label="Enable data" initialValue={true} onChange={(newValue) => alert(`New value is "${newValue}"`)} />

<ToggleSwitch
  label="Enable data"
  initialValue={true}
  onChange={(newValue) => alert(`New value is "${newValue}"`)}
/>

Controlled usage with value prop

Pass a boolean true or false to the value prop and pass a state-setting function to the onChange prop to control the ToggleSwitch from a parent.

This makes the ToggleSwitch not manage its own state and instead trust the parent component to manage it. If a ToggleSwitch uses this pattern, it must always receive a value prop of true or false (never undefined), and its intialValue prop should not be used.

Loading...

function ControlledToggleSwitch() { const [value, setValue] = useState(false) return ( <StackView space={3}> <Typography>Toggle switch is {value ? 'on' : 'off'}.</Typography> <ToggleSwitch label="Enable data" value={value} onChange={setValue} /> </StackView> ) }

function ControlledToggleSwitch() {
  const [value, setValue] = useState(false)
  return (
    <StackView space={3}>
      <Typography>Toggle switch is {value ? 'on' : 'off'}.</Typography>
      <ToggleSwitch label="Enable data" value={value} onChange={setValue} />
    </StackView>
  )
}

Accessibility

If a ToggleSwitch's effect is understood through context in the surrounding text, pass the accessibilityLabel prop so that users of accessibility tools such as screen readers know exactly what the ToggleSwitch will do at the time they will use it.

Loading...

<StackView space={3}> <Typography variant={{ size: 'h3' }}>Marketing preferences</Typography> <Typography>Choose whether to receive marketing emails, such as special offers.</Typography> <Typography> These will be tailored to your interests and direct from Telus, not from third parties. </Typography> <ToggleSwitch label="Enable data" accessibilityLabel="Receive marketing emails from Telus" /> </StackView>

<StackView space={3}>
  <Typography variant={{ size: 'h3' }}>Marketing preferences</Typography>
  <Typography>Choose whether to receive marketing emails, such as special offers.</Typography>
  <Typography>
    These will be tailored to your interests and direct from Telus, not from third parties.
  </Typography>
  <ToggleSwitch label="Enable data" accessibilityLabel="Receive marketing emails from Telus" />
</StackView>

When used as a standalone input, ToggleSwitch has the switch role and declares its on/off state as selected. If a group of ToggleSwitches are used like radio buttons where only one may be selected at a time, setting the radio role via accessibilityRole may be more appropriate.

Props

Name	Type	Default	Description
accessibilityRole		'switch'
accessibilityLabel		label
tokens	custom		System tokens prop, see tokens for more details
variant	objectOf		System variant prop, see variants for more details
value	bool		If this is a "controlled" component and a parent handles its selected state, tells the switch if it is on (true) or off (false).
initialValue	bool		If this is an "uncontrolled" component that handles its own selected state, optionally tells the switch if it should default to on (true) or off (false).
onChange	func		Function called when the switch is toggled, with one boolean argument that is the new position of the switch, on (true) or off (false). For "controlled" components, this should always be passed and used to control the state of the switch.
id	string		Input ID.
label	string		An optional label.
inactive	bool		If passed, the switch does not respond to user input and may recieve different theme tokens if the theme supports inactive appearance.
tooltip	string		Content of an optional Tooltip. If set, a tooltip button will be shown next to the label.