--- title: Select description: Select element: vaadin-select --- ## Description `` is a Web Component for selecting values from a list of items. ### Items Use the `items` property to define possible options for the select: ```html ``` ```js const select = document.querySelector('#select'); select.items = [ { label: 'Most recent first', value: 'recent' }, { component: 'hr' }, { label: 'Rating: low to high', value: 'rating-asc', className: 'asc' }, { label: 'Rating: high to low', value: 'rating-desc', className: 'desc' }, { component: 'hr' }, { label: 'Price: low to high', value: 'price-asc', disabled: true }, { label: 'Price: high to low', value: 'price-desc', disabled: true } ]; ``` ### Rendering Alternatively, the content of the select can be populated by using the renderer callback function. The renderer function provides `root`, `select` arguments. Generate DOM content, append it to the `root` element and control the state of the host element by accessing `select`. ```js const select = document.querySelector('#select'); select.renderer = function(root, select) { const listBox = document.createElement('vaadin-list-box'); // append 3 elements ['Jose', 'Manolo', 'Pedro'].forEach(function(name) { const item = document.createElement('vaadin-item'); item.textContent = name; item.setAttribute('label', name) listBox.appendChild(item); }); // update the content root.appendChild(listBox); }; ``` Renderer is called on initialization of new select and on its opening. DOM generated during the renderer call can be reused in the next renderer call and will be provided with the `root` argument. On first call it will be empty. * Hint: By setting the `label` property of inner vaadin-items you will be able to change the visual representation of the selected value in the input part. ### Styling The following custom properties are available for styling: Custom property | Description | Default ---------------------------------|-----------------------------|-------- `--vaadin-field-default-width` | Default width of the field | `12em` `--vaadin-select-overlay-width` | Width of the overlay | The following shadow DOM parts are available for styling: Part name | Description ---------------------|---------------- `label` | The label element `input-field` | The element that wraps prefix, value and toggle button `field-button` | Set on the toggle button `error-message` | The error message element `helper-text` | The helper text element wrapper `required-indicator` | The `required` state indicator element `toggle-button` | The toggle button `backdrop` | Backdrop of the overlay `overlay` | The overlay container `content` | The overlay content The following state attributes are available for styling: Attribute | Description ---------------------|--------------------------------- `disabled` | Set when the element is disabled `has-value` | Set when the element has a value `has-label` | Set when the element has a label `has-helper` | Set when the element has helper text or slot `has-error-message` | Set when the element has an error message `invalid` | Set when the element is invalid `focused` | Set when the element is focused `focus-ring` | Set when the element is keyboard focused `readonly` | Set when the element is readonly `opened` | Set when the overlay is opened `phone` | Set when the overlay is shown in phone mode ### Internal components In addition to `` itself, the following internal components are themable: - `` - has the same API as [``](/elements/vaadin-button). - `` - has the same API as [``](/elements/vaadin-list-box). - `` - has the same API as [``](/elements/vaadin-item). See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation. ## Properties ### accessibleName **Type:** `string | null | undefined` String used to label the component to screen reader users. ### accessibleNameRef **Type:** `string | null | undefined` Id of the element used as label of the component to screen reader users. ### autofocus **Type:** `boolean` Specify that this control should have input focus when the page loads. ### disabled **Type:** `boolean` If true, the user cannot interact with this element. ### errorMessage **Type:** `string | null | undefined` Error to show when the field is invalid. ### helperText **Type:** `string | null | undefined` String used for the helper text. ### invalid **Type:** `boolean` Set to true when the field is invalid. ### items **Type:** `SelectItem[] | null | undefined` An array containing items that will be rendered as the options of the select. #### Example ```js select.items = [ { label: 'Most recent first', value: 'recent' }, { component: 'hr' }, { label: 'Rating: low to high', value: 'rating-asc', className: 'asc' }, { label: 'Rating: high to low', value: 'rating-desc', className: 'desc' }, { component: 'hr' }, { label: 'Price: low to high', value: 'price-asc', disabled: true }, { label: 'Price: high to low', value: 'price-desc', disabled: true } ]; ``` Note: each item is rendered by default as the internal `` that is an extension of ``. To render the item with a custom component, provide a tag name by the `component` property. See also: [SelectItem](#selectitem) ### label **Type:** `string | null | undefined` The label text for the input node. When no light dom defined via [slot=label], this value will be used. ### manualValidation **Type:** `boolean` Set to true to enable manual validation mode. This mode disables automatic constraint validation, allowing you to control the validation process yourself. You can still trigger constraint validation manually with the `validate()` method or use `checkValidity()` to assess the component's validity without affecting the invalid state. In manual validation mode, you can also manipulate the `invalid` property directly through your application logic without conflicts with the component's internal validation. ### name **Type:** `string | null | undefined` The name of this element. ### noVerticalOverlap **Type:** `boolean` Defines whether the overlay should overlap the target element in the y-axis, or be positioned right above/below it. ### opened **Type:** `boolean` Set when the select is open ### placeholder **Type:** `string | null | undefined` A hint to the user of what can be entered in the control. The placeholder will be displayed in the case that there is no item selected, or the selected item has an empty string label, or the selected item has no label and it's DOM content is empty. ### readonly **Type:** `boolean` When present, it specifies that the element is read-only. ### renderer **Type:** `SelectRenderer | undefined` Custom function for rendering the content of the ``. Receives two arguments: - `root` The internal container DOM element. Append your content to it. - `select` The reference to the `` element. See also: [SelectRenderer](#selectrenderer) ### required **Type:** `boolean` Specifies that the user must fill in a value. ### value **Type:** `string` The `value` property of the selected item, or an empty string if no item is selected. On change or initialization, the component finds the item which matches the value and displays it. If no value is provided to the component, it selects the first item without value or empty value. Hint: If you do not want to select any item by default, you can either set all the values of inner vaadin-items, or set the vaadin-select value to an inexistent value in the items list. ## Methods ### checkValidity **Type:** `() => boolean` Returns true if the current value satisfies all constraints (if any) ### requestContentUpdate **Type:** `() => void` Requests an update for the content of the select. While performing the update, it invokes the renderer passed in the `renderer` property. It is not guaranteed that the update happens immediately (synchronously) after it is requested. ### validate **Type:** `() => boolean` Validates the field and sets the `invalid` property based on the result. The method fires a `validated` event with the result of the validation. ## Events ### change **Type:** [SelectChangeEvent](#selectchangeevent) Fired when the user commits a value change. ### invalid-changed **Type:** [SelectInvalidChangedEvent](#selectinvalidchangedevent) Fired when the `invalid` property changes. ### opened-changed **Type:** [SelectOpenedChangedEvent](#selectopenedchangedevent) Fired when the `opened` property changes. ### validated **Type:** [SelectValidatedEvent](#selectvalidatedevent) Fired whenever the field is validated. ### value-changed **Type:** [SelectValueChangedEvent](#selectvaluechangedevent) Fired when the `value` property changes. ## Types ### SelectChangeEvent ```ts /** * Fired when the user commits a value change. */ export type SelectChangeEvent = Event & { target: Select; }; ``` ### SelectInvalidChangedEvent ```ts /** * Fired when the `invalid` property changes. */ export type SelectInvalidChangedEvent = CustomEvent<{ value: boolean }>; ``` ### SelectItem ```ts export interface SelectItem { label?: string; value?: string; component?: string; disabled?: boolean; className?: string; } ``` ### SelectOpenedChangedEvent ```ts /** * Fired when the `opened` property changes. */ export type SelectOpenedChangedEvent = CustomEvent<{ value: boolean }>; ``` ### SelectRenderer ```ts /** * Function for rendering the content of the ``. * Receives two arguments: * * - `root` The internal container DOM element. Append your content to it. * - `select` The reference to the `` element. */ export type SelectRenderer = (root: HTMLElement, select: Select) => void; ``` ### SelectValidatedEvent ```ts /** * Fired whenever the field is validated. */ export type SelectValidatedEvent = CustomEvent<{ valid: boolean }>; ``` ### SelectValueChangedEvent ```ts /** * Fired when the `value` property changes. */ export type SelectValueChangedEvent = CustomEvent<{ value: string }>; ```