Tags
- Library
- UDS Base
- Repository
- github.com/telus/universal-design-system
- Package
- npmjs.com/package/@telus-uds/components-base
- Package version
- 1.6.1
Introduction
import { Tags } from '@telus-uds/components-base'
Tags allows the selection of one or more items, typically used for filtering content.
Spacing between buttons increases on wider viewports (lg and xl).
Guidance
Tags should have very simple, short labels, ideally one word or two.
maxValues prop
The prop maxValues may be passed a number to limit how many items are selelcted.
By default, any number of tags may be selected.
onChange prop
An onChange function may be provided, which is called when a Tags 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 Tags from a parent.
This is usually the easiest way to control subsequent lists of content with Tags.
Accessibility
Tags buttons will be treated like checkboxes by accessibility tools; unless maxValues is set to 1, in
which case they will be treated like radio buttons.
Props
| Name | Type | Default | Description |
|---|---|---|---|
| items | arrayOf | [] | The options a user may select |
| readOnly | false | ||
| inactive | false | ||
| accessibilityRole | 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 | |
| maxValues | number | If provided, sets a maximum number of items a user may select at once. | |
| 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 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. | |
| initialValues | arrayOf | 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. |