ToggleSwitchGroup

Library: UDS Base
Repository: github.com/telus/universal-design-system
Package: npmjs.com/package/@telus-uds/components-base
Package version: 1.6.1

<ToggleSwitchGroup
  items={[
    { label: 'First item', id: 'first' },
    { label: 'Second item', id: 'second' },
    { label: 'Third item', id: 'third', tooltip: 'Third time is a charm' },
    { label: 'Fourth item', id: 'fourth' },
    { label: 'Fifth item', id: 'fifth' }
  ]}
/>

<ToggleSwitchGroup
  items={[
    { label: 'First item', id: 'first' },
    { label: 'Second item', id: 'second' },
    { label: 'Third item', id: 'third', tooltip: 'Third time is a charm' },
    { label: 'Fourth item', id: 'fourth' },
    { label: 'Fifth item', id: 'fifth' }
  ]}
/>

Introduction

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

ToggleSwitchGroup allows the selection of (by default) one element from a selection of labeled buttons.

Guidance

Use for sets of options with very simple, short labels, ideally one word or two.

Consider RadioGroup for items with labels of a few words in length and RadioCard for more complex options requiring a title and additional description content.

`maxValues` prop

The prop maxValues may be passed to allow more than one item to be selected. Pass a number to set that as the maximum, or null to have no maximum and allow any number of selections.

<ToggleSwitchGroup
  items={[
    { label: 'First item', id: 'first' },
    { label: 'Second item', id: 'second' },
    { label: 'Third item', id: 'third' },
    { label: 'Fourth item', id: 'fourth' },
    { label: 'Fifth item', id: 'fifth' }
  ]}
  maxValues={2}
/>

<ToggleSwitchGroup
  items={[
    { label: 'First item', id: 'first' },
    { label: 'Second item', id: 'second' },
    { label: 'Third item', id: 'third' },
    { label: 'Fourth item', id: 'fourth' },
    { label: 'Fifth item', id: 'fifth' }
  ]}
  maxValues={2}
/>

`onChange` prop

An onChange function may be provided, which is called when a ToggleSwitchGroup item is toggled.

<ToggleSwitchGroup
  items={[
    { label: 'First item', id: 'first' },
    { label: 'Second item', id: 'second' },
    { label: 'Third item', id: 'third' },
    { label: 'Fourth item', id: 'fourth' },
    { label: 'Fifth item', id: 'fifth' }
  ]}
  onChange={(state) => setTimeout(() => alert(`ToggleSwitchGroup has selected: ${state}`), 100)}
/>

<ToggleSwitchGroup
  items={[
    { label: 'First item', id: 'first' },
    { label: 'Second item', id: 'second' },
    { label: 'Third item', id: 'third' },
    { label: 'Fourth item', id: 'fourth' },
    { label: 'Fifth item', id: 'fifth' }
  ]}
  onChange={(state) => setTimeout(() => alert(`ToggleSwitchGroup has selected: ${state}`), 100)}
/>

Controlled usage with `values` prop

Pass an array of item ids to the values prop as well as onChange to control the ToggleSwitchGroup from a parent.

This is usually the easiest way to control sibling content with a ToggleSwitchGroup.

function ControlledToggleSwitchGroup() {
  const [values, setValues] = useState([])
  const text = values.length ? `Saved: "${values.join('", "')}".` : 'No selection saved'
  return (
    <StackView space={2}>
      <Typography>{text}</Typography>
      <ToggleSwitchGroup
        values={values}
        onChange={setValues}
        items={[
          { label: 'First item', id: 'first' },
          { label: 'Second item', id: 'second' },
          { label: 'Third item', id: 'third' },
          { label: 'Fourth item', id: 'fourth' },
          { label: 'Fifth item', id: 'fifth' }
        ]}
      />
    </StackView>
  )
}

function ControlledToggleSwitchGroup() {
  const [values, setValues] = useState([])
  const text = values.length ? `Saved: "${values.join('", "')}".` : 'No selection saved'
  return (
    <StackView space={2}>
      <Typography>{text}</Typography>
      <ToggleSwitchGroup
        values={values}
        onChange={setValues}
        items={[
          { label: 'First item', id: 'first' },
          { label: 'Second item', id: 'second' },
          { label: 'Third item', id: 'third' },
          { label: 'Fourth item', id: 'fourth' },
          { label: 'Fifth item', id: 'fifth' }
        ]}
      />
    </StackView>
  )
}

Uncontrolled usage

The ToggleSwitchGroup manages its own state internally if values is not passed.

A default selection may be set by passing an array of item IDs to initialValues. Do not use both initialValues and values props in the same ToggleSwitchGroup.

<ToggleSwitchGroup
  items={[
    { label: 'First item', id: 'first' },
    { label: 'Second item', id: 'second' },
    { label: 'Third item', id: 'third' },
    { label: 'Fourth item', id: 'fourth' },
    { label: 'Fifth item', id: 'fifth' }
  ]}
  initialValues={['second']}
/>

<ToggleSwitchGroup
  items={[
    { label: 'First item', id: 'first' },
    { label: 'Second item', id: 'second' },
    { label: 'Third item', id: 'third' },
    { label: 'Fourth item', id: 'fourth' },
    { label: 'Fifth item', id: 'fifth' }
  ]}
  initialValues={['second']}
/>

Accessibility

By default, ToggleSwitchGroup is treated by accessibility tools as a group of radio buttons.

If maxValues prop is used to allow multiple selections, the buttons will be treated like checkboxes.

Props

Name	Type	Default	Description
items	arrayOf	[]	The options a user may select
maxValues	number	1	The maximum number of items a user may select at once. Defaults to 1 and behaves like radio buttons. To have no limit and allow any number of selections, pass `null`.
readOnly		false
inactive		false
accessibilityRole		maxValues === 1 ? 'radiogroup' // radiogroup is cross-platform; only web aria has generic groups : Platform.select({ web: 'group', default: 'none' })
tokens	custom		System tokens prop, see tokens for more details
variant	objectOf		System variant prop, see variants for more details
onChange	func		If provided, this function is called when the current selection is changed and is passed an array of the `id`s of all currently selected `items`.
values	arrayOf		If the selected item(s) in the toggle switch group are to be controlled externally by a parent component, pass an array of strings as well as an `onChange` handler. Passing an array for "values" makes the ToggleSwitchGroup a "controlled" component that expects its state to be handled via `onChange` and so doesn't handle it itself.
initialValues	arrayOf		If `values` is not passed, making the ToggleSwitchGroup an "uncontrolled" component managing its own selected state, a default set of selections may be provided. Changing the `initialValues` does not change the user's selections.
hint	string		Optional additional text giving more detail to help a user make a choice.
tooltip	string		Optional tooltip text content to include alongside the legend and hint.
feedback	string		If provided, a Feedback element is rendered containing this text.
legend	string		Main text used to describe this group, used in Fieldset's Legend element.
toggleSwitchTokens	custom		Toggle switch token overrides.
validation	'error' \| 'success'		Current validation status of the group, passed to the feedback element if there is one.

ToggleSwitchGroup

Introduction​

Guidance​

maxValues prop​

onChange prop​

Controlled usage with values prop​

Uncontrolled usage​

Accessibility​

Props​