Skip to main content

Select

<ui5-select> | Since 0.8.0

The ui5-select component is used to create a drop-down list.

Usage​

There are two main usages of the ui5-select>.

  1. With Option (ui5-option) web component:

The available options of the Select are defined by using the Option component. The Option comes with predefined design and layout, including icon, text and additional-text.

  1. With OptionCustom (ui5-option-custom) web component.

Options with custom content are defined by using the OptionCustom component The OptionCustom component comes with no predefined layout and it expects consumers to define it.

Keyboard Handling​

The ui5-select provides advanced keyboard handling.

  • [F4] / [Alt] + [Up] / [Alt] + [Down] / [Space] or [Enter] - Opens/closes the drop-down.
  • [Up] or [Down] - If the drop-down is closed - changes selection to the next or the previous option. If the drop-down is opened - moves focus to the next or the previous option.
  • [Space], [Enter] - If the drop-down is opened - selects the focused option.
  • [Escape] - Closes the drop-down without changing the selection.
  • [Home] - Navigates to first option
  • [End] - Navigates to the last option

ES6 Module Import​

import "@ui5/webcomponents/dist/Select";

import "@ui5/webcomponents/dist/Option"; import "@ui5/webcomponents/dist/OptionCustom";

Basic Sample​

Properties​

disabled​

DescriptionDefines whether the component is in disabled state.
Note: A disabled component is noninteractive.
Typeboolean
Defaultfalse

name​

DescriptionDetermines the name by which the component will be identified upon submission in an HTML form.
Note: This property is only applicable within the context of an HTML Form element.
Typestring | undefined
Defaultundefined

valueState​

DescriptionDefines the value state of the component.
Type"None" | "Positive" | "Critical" | "Negative" | "Information"
Default"None"

required​

DescriptionDefines whether the component is required.
Typeboolean
Defaultfalse
Since1.0.0-rc.9

readonly​

DescriptionDefines whether the component is read-only.
Note: A read-only component is not editable, but still provides visual feedback upon user interaction.
Typeboolean
Defaultfalse
Since1.21.0

accessibleName​

DescriptionDefines the accessible ARIA name of the component.
Typestring | undefined
Defaultundefined
Since1.0.0-rc.9

accessibleNameRef​

DescriptionReceives id(or many ids) of the elements that label the select.
Typestring | undefined
Defaultundefined
Since1.0.0-rc.15

value​

DescriptionDefines the value of the component:
- when get - returns the value of the component, e.g. the value property of the selected option or its text content.
- when set - selects the option with matching value property or text content.
Note: If the given value does not match any existing option, the first option will get selected.
Typestring
Default""
Since1.20.0

selectedOption​

DescriptionCurrently selected ui5-option element.
TypeIOption | undefined
Defaultundefined
Readonlytrue

Slots​

default​

DescriptionDefines the component options.
Note: Only one selected option is allowed. If more than one option is defined as selected, the last one would be considered as the selected one.
Note: Use the ui5-option component to define the desired options.
TypeArray<IOption>

valueStateMessage​

DescriptionDefines the value state message that will be displayed as pop up under the component.
Note: If not specified, a default text (in the respective language) will be displayed.
Note: The valueStateMessage would be displayed, when the component is in Information, Critical or Negative value state.
Note: If the component has suggestionItems, the valueStateMessage would be displayed as part of the same popover, if used on desktop, or dialog - on phone.
TypeArray<HTMLElement>

label​

DescriptionDefines the HTML element that will be displayed in the component input part, representing the selected option.
Note: If not specified and ui5-option-custom is used, either the option's display-text or its textContent will be displayed.
Note: If not specified and ui5-option is used, the option's textContent will be displayed.
TypeArray<HTMLElement>
Since1.17.0

Events​

change​

DescriptionFired when the selected option changes.
TypeCustomEvent<SelectChangeEventDetail>
ParametersselectedOption: IOption
the selected option.
BubblesYes
CancelableYes - via preventDefault()

live-change​

DescriptionFired when the user navigates through the options, but the selection is not finalized, or when pressing the ESC key to revert the current selection.
TypeCustomEvent<SelectLiveChangeEventDetail>
ParametersselectedOption: IOption
the selected option.
Since1.17.0
BubblesYes
CancelableNo

open​

DescriptionFired after the component's dropdown menu opens.
TypeCustomEvent
BubblesYes
CancelableNo

close​

DescriptionFired after the component's dropdown menu closes.
TypeCustomEvent
BubblesNo
CancelableNo

Methods​

No methods available for this component.

CSS Parts​

NameDescription
popoverUsed to style the popover element

More Samples​

States​

Select supports several semantic value states, readonly, disabled, etc.

Options with additional text​

Options can dispplay additional text.

Custom Options​

You can define completely custom options via the ui5-option-custom (providing custom content) component.