Skip to main content

Select

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 SelectMenu (ui5-select-menu) and SelectMenuOption (ui5-select-menu-option) web components:

The SelectMenu can be used as alternative to define the Select's dropdown and can be used via the menu property of the Select to reference SelectMenu by its ID. The component gives the possibility to customize the Select's dropdown by slotting entirely custom options (via the SelectMenuOption component) and adding custom styles.

Note: SelectMenu is a popover and placing it top-level in the HTML page is recommended, because some page styles (for example transitions) can misplace the SelectMenu.

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"; (comes with ui5-select)

Basic Sample​

Properties​

DescriptionDefines a reference (ID or DOM element) of component's menu of options as alternative to define the select's dropdown.
Note: Usage of ui5-select-menu is recommended.
TypeHTMLElement | string | undefined
Defaultundefined
Since1.17.0

disabled​

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

name​

DescriptionDetermines the name with which the component will be submitted in an HTML form. The value of the component will be the value of the currently selected ui5-option.
Important: For the name property to have effect, you must add the following import to your project: import "@ui5/webcomponents/dist/features/InputElementsFormSupport.js";
Note: When set, a native input HTML element will be created inside the ui5-select so that it can be submitted as part of an HTML form. Do not use this property unless you need to submit a form.
Typestring
Default""

valueState​

DescriptionDefines the value state of the component.
Type"None" | "Success" | "Warning" | "Error" | "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
Default""
Since1.0.0-rc.9

accessibleNameRef​

DescriptionReceives id(or many ids) of the elements that label the select.
Typestring
Default""
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, Warning or Error 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-select-menu-option 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.

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

open​

DescriptionFired after the component's dropdown menu opens.
TypeCustomEvent

close​

DescriptionFired after the component's dropdown menu closes.
TypeCustomEvent

Methods​

No methods available for this component.

CSS Parts​

No CSS parts available for this component.

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-select-menu (defining external dropdown) and ui5-select-menu-option (providing custom content) components.