Select

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

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

Package version

1.14.0

Loading...

<Select label="Label" hint="This is the hint (below)" hintPosition="below" tooltip="This is the tooltip content" feedback="Some instructional feedback" > <Select.Item value="root-item-1">Root item 1</Select.Item> <Select.Item value="root-item-2">Root item 2</Select.Item> <Select.Group label="Group label"> <Select.Item value="group-item-1">Group item 1</Select.Item> <Select.Item value="group-item-2">Group item 2</Select.Item> </Select.Group> <Select.Item value="root-item-3">Root item 3</Select.Item> </Select>

<Select
  label="Label"
  hint="This is the hint (below)"
  hintPosition="below"
  tooltip="This is the tooltip content"
  feedback="Some instructional feedback"
>
  <Select.Item value="root-item-1">Root item 1</Select.Item>
  <Select.Item value="root-item-2">Root item 2</Select.Item>
  <Select.Group label="Group label">
    <Select.Item value="group-item-1">Group item 1</Select.Item>
    <Select.Item value="group-item-2">Group item 2</Select.Item>
  </Select.Group>
  <Select.Item value="root-item-3">Root item 3</Select.Item>
</Select>

Introduction

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

Select is a basic form single-choice select component. You can use it in forms or individually to receive user's input.

Guidance

• Include a placeholder to provide instructions such as "Please select..." as an unselectable option (recommended)
• Use when options are between 7-15 (recommended)
• For options are 6 and under, use Radio groups or ButtonGroup.
• For options 15 and above, look for alternatives (e.g grouping into categories, or input field with auto-complete etc.)

Controlled component

If it is required that the state of the Select be controlled by the application or other external methods, value and onChange props must be passed to the Select. If the Select value should not be changed by user input, a readOnly prop must be provided.

Uncontrolled component

If it is not necessary to control the Select state, you can create one without a value prop. In this case its value can be accessed within the onChange callback. Use the initialValue prop to set the default value for an uncontrolled Select.

Getting feedback for entered values

Use the feedback prop to give the user feedback regarding their selection. You can affirm that the user's selection was correct, or highlight errors that must be corrected, using the validation prop. Keep feedback text as brief as possible, should be limited to text and links.

Loading...

<> <Select label="Success" feedback="He chose wisely" validation="success" initialValue="good"> <Select.Item value="good">Good</Select.Item> <Select.Item value="bad">Bad</Select.Item> </Select> <Select label="Error" feedback="He chose poorly" validation="error" initialValue="bad"> <Select.Item value="good">Good</Select.Item> <Select.Item value="bad">Bad</Select.Item> </Select> </>

<>
  <Select label="Success" feedback="He chose wisely" validation="success" initialValue="good">
    <Select.Item value="good">Good</Select.Item>
    <Select.Item value="bad">Bad</Select.Item>
  </Select>

  <Select label="Error" feedback="He chose poorly" validation="error" initialValue="bad">
    <Select.Item value="good">Good</Select.Item>
    <Select.Item value="bad">Bad</Select.Item>
  </Select>
</>

Using a tooltip

When a more in-depth explanation is needed to fill out a Select properly, the tooltip prop may be used.

Grouping options

Select supports option groups. Use a Select.Group component to render an <optgroup> element with its items.

Accessibility

Select component uses label prop to set the accessibility label attribute. It also uses hint or feedback prop (depending on the validation results) to set the accessibility hint and described by (aria-describedby) attributes.

Platform considerations

The component is available on both native platforms and web.

Keep in mind though that grouping does not work on native platforms - the grouped items will be shown at the same level as the non-grouped items.

Props

Name	Type	Default	Description
children	componentPropType(['Item', 'Group'])		An array of items or item groups to be used as options.
inactive	bool		Whether the select is disabled.
initialValue	string		Initial value for the uncontrolled version.
onChange	func		Callback to be called when the value changes.
placeholder	string		A placeholder to provide instructions (such as "Please select...") as an unselectable option
readOnly	bool		Whether the select is read-only.
testID	string		Dedicated ID for testing.
tokens	custom		System tokens prop, see tokens for more details
value	string		Current value to be set as selected.
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	backgroundColor	color
	color	color
	borderWidth	border
	borderColor	color
	borderRadius	radius
	paddingTop	size
	paddingBottom	size
	paddingLeft	size
	paddingRight	size
	height	size
	outerBackgroundColor	color
	outerBorderWidth	border
	outerBorderColor	color
	fontSize	fontSize
	fontName	fontName
	fontWeight	fontWeight
	icon	icon
	iconSize	size
	iconColor	color
	validationIcon	icon
	validationIconSize	size
	validationIconColor	color

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