ToggleSwitchGroup
- Library
- UDS Base
- Repository
- github.com/telus/universal-design-system
- Package
- npmjs.com/package/@telus-uds/ds-allium
- Package version
- 1.14.0
Introduction
import { ToggleSwitchGroup } from '@telus-uds/ds-allium'
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.
onChange
prop
An onChange
function may be provided, which is called when a ToggleSwitchGroup item is toggled.
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.
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
.
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.
Platform considerations
The component is available on both native platforms and web.
Props
Name | Type | Default | Description |
---|---|---|---|
accessibilityRole | maxValues === 1 ? 'radiogroup' // radiogroup is cross-platform; only web aria has generic groups : Platform.select({ web: 'group', default: 'none' }) | ||
copy | 'en' | 'fr' | 'en' | Whether the English or French copy will be used (e.g. for accessibility labels). |
feedback | string | If provided, a Feedback element is rendered containing this text. | |
hint | string | Optional additional text giving more detail to help a user make a choice. | |
inactive | false | ||
initialValues | Array<string> | 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. | |
items | Array<{ label: string, accessibilityLabel: string, id: string, ref }> | [] | The options a user may select |
legend | string | Main text used to describe this group, used in Fieldset's Legend element. | |
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'. |
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'. | |
readOnly | false | ||
toggleSwitchTokens | custom | Toggle switch token overrides. | |
tokens | custom | System tokens prop, see tokens for more details | |
tooltip | string | Optional tooltip text content to include alongside the legend and hint. | |
validation | 'error' | 'success' | Current validation status of the group, passed to the feedback element if there is one. | |
values | Array<string> | 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. | |
variant | objectOf | System variant prop, see variants for more details |
Figma
Variants
This component does not have any stylistic variants.
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