Select

Selects are used to choose one or more items from a list of options.

Demo

Usage

When to use

Choosing one or several options from a list of many. Use a select if there are many options to choose from, especially in compact layouts.

When not to use

Ordering selections. Don't use a select to choose options when their order is important. Use a Transfer instead.

Variants

Single select

Demo

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

Use a single select if the user can only choose one option.

Multi select

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>

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

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	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	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
label	string		*
value	string		*
active	boolean
className	string
dataTest	string	`'dhis2-uicore-multiselectoption'`
disabled	boolean
onClick	function

SingleSelect

Usage

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

import { SingleSelect } from '@dhis2/ui'

Props

Name	Type	Default	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	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
label	string		*
value	string		*
active	boolean
className	string
dataTest	string	`'dhis2-uicore-singleselectoption'`
disabled	boolean
onClick	function

Usage​

When to use​

When not to use​

Variants​

Single select​

Multi select​

Format​

Label​

Placeholder​

Help text​

Size​

Width​

Options​

Filtering​

Clearing​

Prefix​

State: Error​

State: Disabled​

API Reference​

MultiSelect​

Usage​

Props​

MultiSelectField​

Usage​

Props​

MultiSelectOption​

Usage​

Props​

SingleSelect​

Usage​

Props​

SingleSelectField​

Usage​

Props​

SingleSelectOption​

Usage​

Props​

Usage

When to use

When not to use

Variants

Single select

Multi select

Format

Label

Placeholder

Help text

Size

Width

Options

Filtering

Clearing

Prefix

State: Error

State: Disabled

API Reference

MultiSelect

Usage

Props

MultiSelectField

Usage

Props

MultiSelectOption

Usage

Props

SingleSelect

Usage

Props

SingleSelectField

Usage

Props

SingleSelectOption

Usage

Props