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. Usedense
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 |
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 |