Overview
Value: {}
A select dropdown component that allows users to select an item from a range of options. The options are specified with a value and a label for that value to display to the user. Additionally, the component can take slots to customize the display of each option.
Usage
Select dropdowns are used alongside form components such as text fields and radio selects. They can also be used to filter options in lists and tables.
Specifications
Default width:
- As a filter for lists and tables: 150px
- In a form: 300px
Increase or decrease this width to fit appropriately with other components in forms or filter groups.
The select label should be very short and descriptive. Stick to using one word to describe the field, if possible.
Guidelines
Consider using a select when there are 4 or more options available to select for a field. With fewer options, consider using radios or checkboxes.
Forms
Sometimes the same select field is used in forms for different variations of an editable object (e.g. the “completion” field of a PDF document vs a video file). If a select option for a particular variation of an editable object is not applicable or will create a confusing or negative user experience, it should be hidden from the select. If all options will create the same adverse experience, the entire select should be hidden from that form.
Hiding is better than disabling in this case because there is no condition where it would benefit the user experience to be selectable for that object.
Filters
For design guidance on using selects for filtering, see the Filters page .
Props
| Name | Description | Type | Default | Required |
|---|---|---|---|---|
value | Object currently selected | object | — | true |
options | Array of option objects { value, label, disabled }.
Disabled key is optional | array | — | true |
placeholder | Sets the placeholder value | string |
''
| — |
label | Specifies the label text. Default is empty if not provided. | string |
null
| — |
floatingLabel | Floating Label | boolean |
true
| — |
multiple | Whether multiple options can be selected or not | boolean |
false
| — |
multipleDelimiter | Delimiter for multiple selected options | string |
', '
| — |
noResultsText | Text displayed if no results | string |
''
| — |
keys | Object that defines the label, value and image keys in objects of the options prop.
Default: { label: 'label', value: 'value', image: 'image' } | object |
config.data.UiSelect.keys
| — |
invalid | Whether invalid or not | boolean |
false
| — |
invalidText | Text displayed if invalid | string |
null
| — |
help | Help text | string |
null
| — |
disabled | Whether disabled or not | boolean |
false
| — |
clearable | Whether to turn into a clearable state
when an option has been selected. | boolean |
false
| — |
clearText | Defines the tooltip and aria-label of the clear button if the select is clearable. | string |
''
| — |
inline | Whether or not display as inline block | boolean |
false
| — |
Events
| Name | Description |
|---|---|
dropdown-open | Emit on opening dropdown |
dropdown-close | Emit on closing dropdown |
query-change | Emits whenever the query value changes. |
change | Emitted when the value is changed |
input | Emits an 'input' event with the new value when the selection is updated. |
select | Emitted when an option is selected by the user. Will not be emitted if the selection is
changed programmatically. |
touch | — |
focus | Emitted when the select gets focus |
blur | Emitted when the select loses focus |
Slots
| Name | Description |
|---|---|
default | Optional slot as alternative to label prop |
display | Optional slot to override the display of the selected value |
option | Optional slot to override the display of |
no-results | Optional slot as alternative to noResultsText prop |
error | Optional slot as alternative to invalidText prop |
help | Optional slot as alternative to help prop |
Methods
| Name | Description |
|---|---|
reset | Resets the selected values of dropdown |