Select

Library

UDS Base

Repository

github.com/telus/universal-design-system

Package

npmjs.com/package/@telus-uds/components-base

Package version

1.6.1

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/components-base'

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

Keep in mind 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
initialValue	string		Initial value for the uncontrolled version.
value	string		Current value to be set as selected.
onChange	func		Callback to be called when the value changes.
children	custom		An array of items or item groups to be used as options.
inactive	bool		Whether the select is disabled.
readOnly	bool		Whether the select is read-only.
placeholder	string		A placeholder to provide instructions (such as "Please select...") as an unselectable option
tokens	custom		System tokens prop, see tokens for more details
variant	objectOf		System variant prop, see variants for more details
testID	string		Dedicated ID for testing.