ButtonGroup

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

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

Package version

1.14.0

Loading...

<ButtonGroup 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' } ]} />

<ButtonGroup
  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' }
  ]}
/>

Introduction

import { ButtonGroup } from '@telus-uds/ds-allium'

ButtonGroup allows the selection of (by default) one element from a selection of labelled buttons.

Spacing between buttons increases on wider viewports (lg and xl).

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.

Loading...

<ButtonGroup 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} />

<ButtonGroup
  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 ButtonGroup item is toggled.

Loading...

<ButtonGroup 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(`ButtonGroup has selected: ${state}`), 100)} />

<ButtonGroup
  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(`ButtonGroup 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 ButtonGroup from a parent.

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

Loading...

function ControlledButtonGroup() { const [values, setValues] = useState([]) const text = values.length ? `Saved: "${values.join('", "')}".` : 'No selection saved' return ( <StackView space={2}> <Typography variant={{ size: 'small' }}>{text}</Typography> <ButtonGroup 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 ControlledButtonGroup() {
  const [values, setValues] = useState([])
  const text = values.length ? `Saved: "${values.join('", "')}".` : 'No selection saved'
  return (
    <StackView space={2}>
      <Typography variant={{ size: 'small' }}>{text}</Typography>
      <ButtonGroup
        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 ButtonGroup 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 ButtonGroup.

Loading...

<ButtonGroup 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']} />

<ButtonGroup
  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, ButtonGroup 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'		Sets the language of microcopy in subcomponents (e.g. Tooltip's default accessibility label).
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	bool	false	If true, the buttons cannot be interacted with, elements are set as 'disabled' and if the theme supports 'inactive' appearances rules, these are applied.
initialValues	Array<string>		If 'values' is not passed, making the ButtonGroup 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'.
name	string		On Web, this is passed to the 'name' attribute of the fieldset.
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	bool	false	If true, the buttons cannot be selected by the user and simply show their current state.
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 button 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 ButtonGroup 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

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	space	integer
	fieldSpace	integer
	direction	direction
	alignItems	flexAlign
	justifyContent	flexJustifyContent
	flexGrow	integer
	flexShrink	integer

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