Select

The select components are meant to be used when there are many options the user can choose from, especially when there's not much space available. These components do not support re-ordering, in that case the Transfer component might be a better fit.

Variants

Single select

⚠️⚠️⚠️
This component will be deprecated in favor of the new SimpleSingleSelect component, which is also describe in this document. We have not decided when we'll remove this component from the library to give developers the chance to migrate over time while being able to upgrade the library's version without being forced to migrate to the new component.
⚠️⚠️⚠️

Demo

<SingleSelectField label="Aggregation type">
    <SingleSelectOption label="One" value="1" />
    <SingleSelectOption label="Two" value="2" />
    <SingleSelectOption label="Three" value="3" />
</SingleSelectField>

SimpleSingleSelect

Use the <SimpleSingleSelect/> if the user can only choose one option.

Demo

<SimpleSingleSelect
    idPrefix="required-prefix-value"
    value={value}
    onChange={onChange}
    options={[
        { value: '1', label: 'One' },
        { value: '2', label: 'Two' },
        { value: '3', label: 'Three' },
    ]}
/>

Multi select

Use a multi select if the user can choose one or more options.

Demo

<MultiSelectField label="Priority" selected={['1']}>
    <MultiSelectOption label="Very low" value="1" />
    <MultiSelectOption label="High" value="4" />
    <MultiSelectOption label="Very high" value="5" />
    <MultiSelectOption label="Critical" value="6" />
</MultiSelectField>

Format

Label

• Show a label above the select to show what it's for.
• Labels should clearly describe the selection to be made. Don't use long sentences.
• A noun is often the simplest choice of label, rather than a verb. For example, Period type is more concise in a layout than Choose a period type. Only use a verb if the use of the control is ambiguous.

Placeholder

Demo

<SingleSelectField label="Label" placeholder="Choose an option">
    <SingleSelectOption label="Option one" value="1" />
    <SingleSelectOption label="Option two" value="2" />
    <SingleSelectOption label="Option three" value="3" />
</SingleSelectField>

• Only use placeholder text to clarify what kind of content is expected.
• Placeholder text shouldn't repeat the label.
• Always use placeholder text if a label isn't used.
• Placeholder text disappears when choosing an option, so make sure it's not critical.

Help text

Demo

<SingleSelectField
    label="Aggregation type"
    helpText="Choose the aggregation type to apply to imported data."
>
    <SingleSelectOption label="Option one" value="1" />
    <SingleSelectOption label="Option two" value="2" />
    <SingleSelectOption label="Option three" value="3" />
</SingleSelectField>

• Use help text to tell the user about any limitations or expectations for the content.
• Help text can also be used to clarify what the input is for if it's a complex concept.

Size

Demo

<SingleSelectField dense label="Dense sized select">
    <SingleSelectOption label="Option one" value="1" />
    <SingleSelectOption label="Option two" value="2" />
    <SingleSelectOption label="Option three" value="3" />
</SingleSelectField>

• Selects are available in two sizes, regular and dense. Regular sized selects are useful when there's space available. Use dense sized selects in compact, information-dense interfaces.

Width

• A selects width should reflect the expected content.
• Avoid full-width selects, which can be visually unclear.

Options

Filtering

Demo

<SingleSelectField filterable label="Label">
    <SingleSelectOption label="Option one" value="1" />
    <SingleSelectOption label="Option two" value="2" />
    <SingleSelectOption label="Option three" value="3" />
    <SingleSelectOption label="Option nine" value="9" />
    <SingleSelectOption label="Option ten" value="10" />
</SingleSelectField>

• A select can show a filter control that filters the available options.
• Use a filter when there's many options, more than 10, to choose from.

Clearing

Demo

<SingleSelectField clearable label="Label" selected="1">
    <SingleSelectOption label="Option one" value="1" />
    <SingleSelectOption label="Option two" value="2" />
    <SingleSelectOption label="Option three" value="3" />
    <SingleSelectOption label="Option nine" value="9" />
    <SingleSelectOption label="Option ten" value="10" />
</SingleSelectField>

• A select can show a Clear button that removes the current selection.
• Use a clearable select if there isn't a None choice in the options.

Prefix

Demo

<SingleSelectField prefix="Data type" selected="3">
    <SingleSelectOption label="Data element" value="1" />
    <SingleSelectOption label="Event data item" value="2" />
    <SingleSelectOption label="Program indicator" value="3" />
    <SingleSelectOption label="Option ten" value="10" />
</SingleSelectField>

• A select can show a label that prefixes the chosen option label.
• Use a prefix when there is limited space and a label above the select would take up too much space.
• Prefix labels should be short and clear.

State: Error

Demo

<SingleSelectField
    error
    validationText="That value is wrong. Sorry!"
    label="Label"
>
    <SingleSelectOption label="Option one" value="1" />
    <SingleSelectOption label="Option two" value="2" />
    <SingleSelectOption label="Option three" value="3" />
    <SingleSelectOption label="Option ten" value="10" />
</SingleSelectField>

• Use an error state if there's a problem with the chosen option, or if it's required but empty.
• Don't show an error too early, give the user a chance to make a choice.
• The error text should help the user fix the problem. Refer to the error writing guidelines for examples.

State: Disabled

Demo

<SingleSelectField disabled label="Label">
    <SingleSelectOption label="Option one" value="1" />
    <SingleSelectOption label="Option eight" value="8" />
    <SingleSelectOption label="Option nine" value="9" />
    <SingleSelectOption label="Option ten" value="10" />
</SingleSelectField>

• Use a disabled state if the select temporarily can't be used.
• Show a Tooltip on hover or focus to explain why the select is disabled.

API Reference

MultiSelect

Usage

To use MultiSelect, you can import the component from the @dhis2/ui library

import { MultiSelect } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
children	node
className	string
clearText	custom(function)			Required if clearable prop is true
clearable	boolean			Adds a 'clear' option to the menu
dataTest	string	'dhis2-uicore-multiselect'
dense	boolean
disabled	boolean
empty	node
error	custom
filterPlaceholder	string
filterable	boolean			Adds a 'filter' field to the menu
initialFocus	boolean
inputMaxHeight	string
loading	boolean
loadingText	string
maxHeight	string
noMatchText	custom(function)			Required if filterable prop is true
placeholder	string
prefix	string
selected	arrayOf(string)	[]
tabIndex	string
valid	custom
warning	custom
onBlur	function
onChange	function
onFocus	function
onKeyDown	function

MultiSelectField

Usage

To use MultiSelectField, you can import the component from the @dhis2/ui library

import { MultiSelectField } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
children	node			Should be MultiSelectOption components
className	string
clearText	string │ function	() => i18n.t('Clear')		Label for the button that clears selections
clearable	boolean			Adds a button to the MultiSelect that clears selections when pressed
dataTest	string	'dhis2-uiwidgets-multiselectfield'
dense	boolean			Makes the MultiSelect smaller
disabled	boolean			Disables the MultiSelect
empty	node │ function	() => i18n.t('No data found')		Text to display when there are no options
error	custom			Adds 'error' appearance for validation feedback. Mutually exclusive with 'valid' and 'warning' props
filterPlaceholder	node │ function	() => i18n.t('Type to filter options')		Placeholder text to show in the filter field when it is empty
filterable	boolean			Adds a field to filter options
helpText	string			Useful guiding text to display below the MultiSelect
initialFocus	boolean			Grabs initial focus on the page
inputMaxHeight	string			Constrains the height of the input
inputWidth	string			Sets the width of the input. Can be any valid CSS measurement
label	string			Text for the label above the MultiSelect
loading	boolean			Applies a loading appearance to the dropdown options
loadingText	string │ function	() => i18n.t('Loading options')		Text to display when loading is true
maxHeight	string			Constrains height of the MultiSelect
noMatchText	string │ function	() => i18n.t('No options found')		Text to display when there are no filter results
placeholder	string			Placeholder text when the MultiSelect is empty
prefix	string			Leading text to prefix selections
required	boolean			Indicates that a selection is required
selected	arrayOf(string)	[]		Selected items in the MultiSelect (each string should refer to the item's value attribute)
tabIndex	string
valid	custom			Adds 'valid' appearance for validation feedback. Mutually exclusive with 'error' and 'warning' props
validationText	string			Text to provide form validation feedback. Receives styles according to validation status
warning	custom			Adds 'warning' appearance for validation feedback. Mutually exclusive with 'valid' and 'error' props
onBlur	function			Called with signature ({ selected: [String] }, event)
onChange	function			Called with signature ({ selected: [String] }, event)
onFocus	function			Called with signature ({ selected: [String] }, event)
onKeyDown	function			Called with signature ({ selected: [String] }, event)

MultiSelectOption

Usage

To use MultiSelectOption, you can import the component from the @dhis2/ui library

import { MultiSelectOption } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
label	string		*
value	string		*
active	boolean
className	string
dataTest	string	'dhis2-uicore-multiselectoption'
disabled	boolean
onClick	function

SimpleSingleSelect

Usage

To use SimpleSingleSelect, you can import the component from the @dhis2/ui library

import { SimpleSingleSelect } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
name	string		*	necessary for IDs that are required for accessibility *
options	arrayOf(custom)		*	An array of options *
onChange	function		*	A callback that will be called with the new value or an empty string *
autoFocus	boolean	false		Will focus the select initially *
className	string	''		Additional class names that will be applied to the root element *
clearText	custom(function)	''		This will allow us to put an aria-label on the clear button *
clearable	boolean	false		Whether a clear button should be displayed or not *
dataTest	string	'dhis2-simplesingleselect'		A value for a data-test attribute on the root element *
dense	boolean	false		Renders a select with lower height *
disabled	boolean	false		Disables all interactions with the select (except focussing) *
empty	node	false		Text or component to display when there are no options *
error	custom	false		Applies 'error' appearance for validation feedback. Mutually exclusive with warning and valid props *
filterHelpText	string	''		Help text that will be displayed below the input *
filterLabel	string	''		Value will be used as aria-label attribute on the filter input *
filterPlaceholder	string	''		Placeholder for the filter input *
filterValue	string	''		Value of the filter input *
filterable	boolean	false		Whether the select should display a filter input *
inputMaxHeight	string │ number	''		Max height of the container displaying the selected value *
labelledBy	string	''		Should contain the id of the element that labels the select, if applicable *
loading	boolean	false		Will show a loading indicator at the end of the options-list *
menuLoadingText	string	''		Text that will be displayed next to the loading indicator *
menuMaxHeight	string	'288px'		Allows to modify the max height of the menu *
noMatchText	custom(function)	''		String that will be displayed when the select is being filtered but the options array is empty *
optionComponent	elementType	undefined		Allows to override what's rendered inside the button[role="option"]. Can be overriden on an individual option basis *
optionUpdateStrategy	'off' │ 'polite' │ 'assertive'	'polite'		For a11y: How aggressively the user should be updated about changes in options *
placeholder	string	''		String to show when there's no selected option *
prefix	string	''		String that will be displayed before the label of the selected option *
selected	{ "label": "string", "value": "string" }	{ label: '', value: '' }
tabIndex	string │ number	'0'		Standard HTML tab-index attribute that will be put on the combobox's root element *
valid	custom	false		Applies 'valid' appearance for validation feedback. Mutually exclusive with warning and valid props *
warning	custom	false		Applies 'warning' appearance for validation feedback. Mutually exclusive with warning and valid props *
onBlur	function	() => undefined		Will be called when the combobox is loses focus *
onClear	function	() => undefined		Will be called when the combobox is loses focus *
onEndReached	function	() => undefined		Will be called when the last option is scrolled into the visible area *
onFilterChange	function	() => undefined		Will be called when the filter value changes *
onFocus	function	() => undefined		Will be called when the combobox is being focused *

SimpleSingleSelectField

Usage

To use SimpleSingleSelectField, you can import the component from the @dhis2/ui library

import { SimpleSingleSelectField } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
label	string		*	Label displayed above the input *
name	string		*	necessary for IDs that are required for accessibility *
options	arrayOf(custom)		*	An array of options *
onChange	function		*	A callback that will be called with the new value or an empty string *
autoFocus	boolean			Will focus the select initially *
className	string			Additional class names that will be applied to the root element *
clearText	custom(function)			This will allow us to put an aria-label on the clear button *
clearable	boolean			Whether a clear button should be displayed or not *
dataTest	string			A value for a data-test attribute on the root element *
dense	boolean			Renders a select with lower height *
disabled	boolean			Disables all interactions with the select (except focussing) *
empty	node			Text or component to display when there are no options *
error	custom			Applies 'error' appearance for validation feedback. Mutually exclusive with warning and valid props *
filterHelpText	string			Help text that will be displayed below the input *
filterLabel	string			Value will be used as aria-label attribute on the filter input *
filterPlaceholder	string			Placeholder for the filter input *
filterValue	string			Value of the filter input *
filterable	boolean			Whether the select should display a filter input *
helpText	string			Help text, displayed below the input *
loading	boolean			Will show a loading indicator at the end of the options-list *
menuLoadingText	string			Text that will be displayed next to the loading indicator *
menuMaxHeight	string			Allows to modify the max height of the menu *
noMatchText	custom(function)			String that will be displayed when the select is being filtered but the options array is empty *
optionComponent	elementType			Allows to override what's rendered inside the button[role="option"]. Can be overriden on an individual option basis *
optionUpdateStrategy	'off' │ 'polite' │ 'assertive'			For a11y: How aggressively the user should be updated about changes in options *
placeholder	string			String to show when there's no value and no valueLabel *
prefix	string			String that will be displayed before the label of the selected option *
required	boolean			Whether a value is required or not *
tabIndex	string │ number			Standard HTML tab-index attribute that will be put on the combobox's root element *
valid	custom			Applies 'valid' appearance for validation feedback. Mutually exclusive with warning and valid props *
validationText	string			Text shown below input when props.error is true *
value	string			As of now, this component does not support being uncontrolled *
valueLabel	custom(function)			When the option is not in the options list (e.g. not loaded or list is filtered), but a selected value needs to be displayed, then this prop can be used to supply the text to be shown.
warning	custom			Applies 'warning' appearance for validation feedback. Mutually exclusive with warning and valid props *
onBlur	function			Will be called when the combobox is loses focus *
onEndReached	function			Will be called when the last option is scrolled into the visible area *
onFilterChange	function			Will be called when the filter value changes *
onFocus	function			Will be called when the combobox is being focused *

SingleSelect

Usage

To use SingleSelect, you can import the component from the @dhis2/ui library

import { SingleSelect } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
children	node
className	string
clearText	custom(function)			Text on button that clears selection. Required if clearable prop is true
clearable	boolean			Adds a button to clear selection
dataTest	string	'dhis2-uicore-singleselect'
dense	boolean
disabled	boolean
empty	node			Text or component to display when there are no options
error	custom			Applies 'error' appearance for validation feedback. Mutually exclusive with warning and valid props
filterPlaceholder	string
filterable	boolean			Adds a filter field to add text to filter options
initialFocus	boolean
inputMaxHeight	string
loading	boolean
loadingText	string
maxHeight	string
noMatchText	custom(function)			Text to show when filter returns no results. Required if filterable prop is true
placeholder	string
prefix	string
selected	string	''
tabIndex	string
valid	custom			Applies 'valid' appearance for validation feedback. Mutually exclusive with warning and error props
warning	custom			Applies 'warning' appearance for validation feedback. Mutually exclusive with valid and error props
onBlur	function
onChange	function
onFocus	function
onKeyDown	function

SingleSelectField

Usage

To use SingleSelectField, you can import the component from the @dhis2/ui library

import { SingleSelectField } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
children	node			Should be SingleSelectOption components
className	string
clearText	string │ function	() => i18n.t('Clear')		Label for the button that clears selections
clearable	boolean			Adds a button to the SingleSelect that clears selections when pressed
dataTest	string	'dhis2-uiwidgets-singleselectfield'
dense	boolean			Makes the SingleSelect smaller
disabled	boolean			Disables the SingleSelect
empty	node │ function	() => i18n.t('No data found')		Text to display when there are no options
error	custom			Adds 'error' appearance for validation feedback. Mutually exclusive with 'valid' and 'warning' props
filterPlaceholder	node │ function	() => i18n.t('Type to filter options')		Placeholder text to show in the filter field when it is empty
filterable	boolean			Adds a field to filter options
helpText	string			Useful guiding text to display below the SingleSelect
initialFocus	boolean			Grabs initial focus on the page
inputMaxHeight	string			Constrains the height of the input
inputWidth	string			Sets the width of the input. Can be any valid CSS measurement
label	string			Text for the label above the SingleSelect
loading	boolean			Applies a loading appearance to the dropdown options
loadingText	string │ function	() => i18n.t('Loading options')		Text to display when loading is true
maxHeight	string			Constrains height of the SingleSelect
noMatchText	string │ function	() => i18n.t('No options found')		Text to display when there are no filter results
placeholder	string			Placeholder text when the SingleSelect is empty
prefix	string			Leading text to prefix selections
required	boolean			Indicates that a selection is required
selected	string	''		Selected item in the SingleSelect (the string should refer to the item's value attribute)
tabIndex	string
valid	custom			Adds 'valid' appearance for validation feedback. Mutually exclusive with 'error' and 'warning' props
validationText	string			Text to provide form validation feedback. Receives styles according to validation status
warning	custom			Adds 'warning' appearance for validation feedback. Mutually exclusive with 'valid' and 'error' props
onBlur	function			Called with signature ({ selected: string }, event)
onChange	function			Called with signature ({ selected: string }, event)
onFocus	function			Called with signature ({ selected: string }, event)
onKeyDown	function			Called with signature ({ selected: string }, event)

SingleSelectOption

Usage

To use SingleSelectOption, you can import the component from the @dhis2/ui library

import { SingleSelectOption } from '@dhis2/ui'

Props

Name	Type	Default	Required	Description
label	string		*
value	string		*
active	boolean
className	string
dataTest	string	'dhis2-uicore-singleselectoption'
disabled	boolean
onClick	function