Skip to main content

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

NameTypeDefaultRequiredDescription
childrennode
classNamestring
clearTextcustom(function)Required if clearable prop is true
clearablebooleanAdds a 'clear' option to the menu
dataTeststring'dhis2-uicore-multiselect'
denseboolean
disabledboolean
emptynode
errorcustom
filterPlaceholderstring
filterablebooleanAdds a 'filter' field to the menu
initialFocusboolean
inputMaxHeightstring
loadingboolean
loadingTextstring
maxHeightstring
noMatchTextcustom(function)Required if filterable prop is true
placeholderstring
prefixstring
selectedarrayOf(string)[]
tabIndexstring
validcustom
warningcustom
onBlurfunction
onChangefunction
onFocusfunction
onKeyDownfunction

MultiSelectField

Usage

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

import { MultiSelectField } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeShould be MultiSelectOption components
classNamestring
clearTextstring │ function() => i18n.t('Clear')Label for the button that clears selections
clearablebooleanAdds a button to the MultiSelect that clears selections when pressed
dataTeststring'dhis2-uiwidgets-multiselectfield'
densebooleanMakes the MultiSelect smaller
disabledbooleanDisables the MultiSelect
emptynode │ function() => i18n.t('No data found')Text to display when there are no options
errorcustomAdds 'error' appearance for validation feedback. Mutually exclusive with 'valid' and 'warning' props
filterPlaceholdernode │ function() => i18n.t('Type to filter options')Placeholder text to show in the filter field when it is empty
filterablebooleanAdds a field to filter options
helpTextstringUseful guiding text to display below the MultiSelect
initialFocusbooleanGrabs initial focus on the page
inputMaxHeightstringConstrains the height of the input
inputWidthstringSets the width of the input. Can be any valid CSS measurement
labelstringText for the label above the MultiSelect
loadingbooleanApplies a loading appearance to the dropdown options
loadingTextstring │ function() => i18n.t('Loading options')Text to display when loading is true
maxHeightstringConstrains height of the MultiSelect
noMatchTextstring │ function() => i18n.t('No options found')Text to display when there are no filter results
placeholderstringPlaceholder text when the MultiSelect is empty
prefixstringLeading text to prefix selections
requiredbooleanIndicates that a selection is required
selectedarrayOf(string)[]Selected items in the MultiSelect (each string should refer to the item's value attribute)
tabIndexstring
validcustomAdds 'valid' appearance for validation feedback. Mutually exclusive with 'error' and 'warning' props
validationTextstringText to provide form validation feedback. Receives styles according to validation status
warningcustomAdds 'warning' appearance for validation feedback. Mutually exclusive with 'valid' and 'error' props
onBlurfunctionCalled with signature ({ selected: [String] }, event)
onChangefunctionCalled with signature ({ selected: [String] }, event)
onFocusfunctionCalled with signature ({ selected: [String] }, event)
onKeyDownfunctionCalled 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

NameTypeDefaultRequiredDescription
labelstring*
valuestring*
activeboolean
classNamestring
dataTeststring'dhis2-uicore-multiselectoption'
disabledboolean
onClickfunction

SingleSelect

Usage

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

import { SingleSelect } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennode
classNamestring
clearTextcustom(function)Text on button that clears selection. Required if clearable prop is true
clearablebooleanAdds a button to clear selection
dataTeststring'dhis2-uicore-singleselect'
denseboolean
disabledboolean
emptynodeText or component to display when there are no options
errorcustomApplies 'error' appearance for validation feedback. Mutually exclusive with warning and valid props
filterPlaceholderstring
filterablebooleanAdds a filter field to add text to filter options
initialFocusboolean
inputMaxHeightstring
loadingboolean
loadingTextstring
maxHeightstring
noMatchTextcustom(function)Text to show when filter returns no results. Required if filterable prop is true
placeholderstring
prefixstring
selectedstring''
tabIndexstring
validcustomApplies 'valid' appearance for validation feedback. Mutually exclusive with warning and error props
warningcustomApplies 'warning' appearance for validation feedback. Mutually exclusive with valid and error props
onBlurfunction
onChangefunction
onFocusfunction
onKeyDownfunction

SingleSelectField

Usage

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

import { SingleSelectField } from '@dhis2/ui'

Props

NameTypeDefaultRequiredDescription
childrennodeShould be SingleSelectOption components
classNamestring
clearTextstring │ function() => i18n.t('Clear')Label for the button that clears selections
clearablebooleanAdds a button to the SingleSelect that clears selections when pressed
dataTeststring'dhis2-uiwidgets-singleselectfield'
densebooleanMakes the SingleSelect smaller
disabledbooleanDisables the SingleSelect
emptynode │ function() => i18n.t('No data found')Text to display when there are no options
errorcustomAdds 'error' appearance for validation feedback. Mutually exclusive with 'valid' and 'warning' props
filterPlaceholdernode │ function() => i18n.t('Type to filter options')Placeholder text to show in the filter field when it is empty
filterablebooleanAdds a field to filter options
helpTextstringUseful guiding text to display below the SingleSelect
initialFocusbooleanGrabs initial focus on the page
inputMaxHeightstringConstrains the height of the input
inputWidthstringSets the width of the input. Can be any valid CSS measurement
labelstringText for the label above the SingleSelect
loadingbooleanApplies a loading appearance to the dropdown options
loadingTextstring │ function() => i18n.t('Loading options')Text to display when loading is true
maxHeightstringConstrains height of the SingleSelect
noMatchTextstring │ function() => i18n.t('No options found')Text to display when there are no filter results
placeholderstringPlaceholder text when the SingleSelect is empty
prefixstringLeading text to prefix selections
requiredbooleanIndicates that a selection is required
selectedstring''Selected item in the SingleSelect (the string should refer to the item's value attribute)
tabIndexstring
validcustomAdds 'valid' appearance for validation feedback. Mutually exclusive with 'error' and 'warning' props
validationTextstringText to provide form validation feedback. Receives styles according to validation status
warningcustomAdds 'warning' appearance for validation feedback. Mutually exclusive with 'valid' and 'error' props
onBlurfunctionCalled with signature ({ selected: string }, event)
onChangefunctionCalled with signature ({ selected: string }, event)
onFocusfunctionCalled with signature ({ selected: string }, event)
onKeyDownfunctionCalled 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

NameTypeDefaultRequiredDescription
labelstring*
valuestring*
activeboolean
classNamestring
dataTeststring'dhis2-uicore-singleselectoption'
disabledboolean
onClickfunction