Select

Select allows users to make a single selection or multiple selections from a list of options.

Neutral selected states

When the platform-dst-tokens-finesse feature flag is enabled, this component uses the new neutral treatment for selected states.

Motion in Early Access

Motion updates for multi-value Select tags are in Early Access and available behind the platform-dst-motion-uplift-labels feature flag.

Examples Code Migration guide Usage Testing Changelog

Testing with `testId`

As of version 18.10.4, Select now supports specifying a testId for testing. These should be used going forward as the preferred method over the previously recommended className or classNamePrefix as these may be deprecated in the future.

Here are new values you can use as locators:

classeNamePrefix	testId
`[classNamePrefix]__control`	`${testId}-select--control`
`[classNamePrefix]__input`	`${testId}-select--input`
`[classNamePrefix]__placeholder`	`${testId}-select--placeholder`
`[classNamePrefix]__value-container`	`${testId}-select--value-container`
`[classNamePrefix]__indicators`	`${testId}-select--indicators-container`
`[classNamePrefix]__dropdown-indicator`	`${testId}-select--dropdown-indicator`
`[classNamePrefix]__clear-indicator`	`${testId}-select--clear-indicator`
`[classNamePrefix]__menu`	`${testId}-select--listbox-container`
`[classNamePrefix]__menu-list`	`${testId}-select--listbox`
`[classNamePrefix]__option`	`${testId}-select--option-${id}`

Additionally, there are some new locators that have been added:

${testId}-select--input-container
${testId}-select--loading-indicator
${testId}-select--group-${groupIndex}-heading

Lastly, instead of using className to produce a locator on the entire select container, you can now use ${testId}-select--container instead.

Testing via `role`

You can also use semantic roles as locators. The following semantic roles have been added to Select:

role="combobox" for the select input
role="listbox" for the select list
role="option" for select options (specify the option label as the name to locate a specific option)

You can see both testId and role's in action by inspecting the following example.

What city do you live in?

import React from 'react';

import { Label } from '@atlaskit/form/label/default';
import Select from '@atlaskit/select/default';

const SelectSingleExample = (): React.JSX.Element => (
	<>
		<Label htmlFor="single-select-example">What city do you live in?</Label>
		<Select
			inputId="single-select-example"
			testId="react-select"
			options={[
				{ label: 'Adelaide', value: 'adelaide' },
				{ label: 'Brisbane', value: 'brisbane' },
				{ label: 'Canberra', value: 'canberra' },
				{ label: 'Darwin', value: 'darwin' },
				{ label: 'Hobart', value: 'hobart' },
				{ label: 'Melbourne', value: 'melbourne' },
				{ label: 'Perth', value: 'perth' },
				{ label: 'Sydney', value: 'sydney' },
			]}
			placeholder=""
		/>
	</>
);

export default SelectSingleExample;

Testing with versions < 18.10.4

Being able to programmatically test the behavior of your components is important. Select enables this through two props className and classNamePrefix.

Typically when these two props are not defined, the dom-elements in select use emotions generated classnames. However with className and classNamePrefix, select generates semantic classnames for you to reliably search for specific dom elements in the tree.

The value specified in the className prop is reflected down to the selects container. While the value of the classNamePrefix prop is reflected down to every single dom element in the tree as a prefix.

You can see this by inspecting the following example.

What city do you live in?

import React from 'react';

import { Label } from '@atlaskit/form/label/default';
import Select from '@atlaskit/select/default';

const SelectSingleExample = (): React.JSX.Element => (
	<>
		<Label htmlFor="single-select-example">What city do you live in?</Label>
		<Select
			inputId="single-select-example"
			testId="react-select"
			options={[
				{ label: 'Adelaide', value: 'adelaide' },
				{ label: 'Brisbane', value: 'brisbane' },
				{ label: 'Canberra', value: 'canberra' },
				{ label: 'Darwin', value: 'darwin' },
				{ label: 'Hobart', value: 'hobart' },
				{ label: 'Melbourne', value: 'melbourne' },
				{ label: 'Perth', value: 'perth' },
				{ label: 'Sydney', value: 'sydney' },
			]}
			placeholder=""
		/>
	</>
);

export default SelectSingleExample;

Note here that the className of the container element has both the generated css as well as single-select the value of the className prop. Every other element in the tree also includes the generated emotion classname as well as a semantic classname preceded by react-select the value passed into the classNamePrefix.

Once you provide a classNamePrefix, these are the selectors that will be exposed to you:

[classNamePrefix]__control
[classNamePrefix]__input
[classNamePrefix]__placeholder
[classNamePrefix]__value-container
[classNamePrefix]__indicators
[classNamePrefix]__dropdown-indicator
[classNamePrefix]__clear-indicator
[classNamePrefix]__menu
[classNamePrefix]__menu-list
[classNamePrefix]__option

Providing a value for the className prop will reflect that value to the class name of the select container.

Was this page helpful?

We use this feedback to improve our documentation.