ToggleSwitch

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/ds-allium

Package version

1.14.0

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/ds-allium'

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.

Platform considerations

The component is available on both native platforms and web.

Props

Name	Type	Default	Description
accessibilityLabel		label
accessibilityRole		'switch'
copy	'en' | 'fr'	'en'	Whether the English or French copy will be used (e.g. for accessibility labels).
id	string		Input ID.
inactive	bool		If passed, the switch does not respond to user input and may recieve different theme tokens if the theme supports inactive appearance.
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).
label	string		An optional label.
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.
tokens	custom		System tokens prop, see tokens for more details
tooltip	string		Content of an optional Tooltip. If set, a tooltip button will be shown next to the label.
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).
variant	objectOf		System variant prop, see variants for more details

Tokens

In exceptional circumstances, the following tokens can be passed to this component to override its default styles. Do not do this unless absolutely necessary. Read more about overriding styles.

View Tokens

Prop Name	Token Property	Token Type
tokens	borderColor	color
	borderWidth	border
	borderRadius	radius
	outerBorderColor	color
	outerBorderWidth	border
	outerBorderGap	size
	outerBackgroundColor	color
	backgroundColor	color
	opacity	opacity
	paddingLeft	size
	paddingRight	size
	paddingTop	size
	paddingBottom	size
	shadow	shadow
	alignSelf	flexAlign
	icon	icon
	width	size
	trackBorderWidth	border
	trackBorderColor	color
	trackBorderRadius	radius
	iconSize	size
	iconColor	color
	labelColor	color
	labelFontName	fontName
	labelFontSize	fontSize
	labelFontWeight	fontWeight
	labelLineHeight	lineHeight
	labelMarginLeft	size
	switchSize	size
	switchColor	color
	switchBorderColor	color
	switchBorderWidth	border
	switchBorderRadius	radius
	switchShadow	shadow

Figma

Variants

This component does not have any stylistic variants.

It does have an inactive appearance state. Use this only when absolutely necessary along with clear messaging (such as Feedback) as to what the user should do.

Loading...

<StackView space={3}> <ToggleSwitch label="Enable data" initialValue={false} inactive /> <ToggleSwitch label="Enable data" initialValue={true} inactive /> </StackView>

<StackView space={3}>
  <ToggleSwitch label="Enable data" initialValue={false} inactive />
  <ToggleSwitch label="Enable data" initialValue={true} inactive />
</StackView>

Try to structure user interactions such that inactive inputs are not needed because they intuitively do not become part of the content flow.

Feedback

• Spotted a problem with this component? Raise an issue on GitHub
• See any existing issues for this component
• Contact the team on slack in #ds-allium-support