Combo Box
Combo Box allows the user to choose a value from a filterable list of options presented in an overlay. It supports lazy loading and can be configured to accept custom typed values.
new tab
<vaadin-combo-box
label="Country"
item-label-path="name"
item-value-path="id"
.items="${this.items}"
></vaadin-combo-box>The overlay opens when the user clicks the field using a pointing device. Using the Up/Down arrow keys or typing a character (found in at least one of the options) when the field is focused also opens the popup.
Custom Value Entry
Combo Box can be configured to allow entering custom values that are not included in the list of options.
new tab
<vaadin-combo-box
allow-custom-value
label="Browser"
helper-text="Select or type a browser"
.items="${this.items}"
></vaadin-combo-box>Allowing custom entry is useful when you need to present the most common choices but still give users the freedom to enter their own options.
Custom values can also be stored and added to the list of options:
new tab
<vaadin-combo-box
allow-custom-value
@custom-value-set="${(e: CustomEvent) => (this.items = [...this.items, e.detail])}"
label="Browser"
helper-text="Select or type a browser"
.items="${this.items}"
></vaadin-combo-box>Custom Item Presentation
Items can be customised to display more information than a single line of text.
new tab
<vaadin-combo-box
label="Choose doctor"
item-label-path="displayName"
.filteredItems="${this.filteredItems}"
.renderer="${this.renderer}"
style="--vaadin-combo-box-overlay-width: 16em"
@filter-changed="${this.filterChanged}"
></vaadin-combo-box>
...
// NOTE
// We are using inline styles here to keep the example simple.
// We recommend placing CSS in a separate style sheet and
// encapsulating the styling in a new component.
private renderer: ComboBoxRenderer<Person> = (root, _, { item: person }) => {
render(
html`
<div style="display: flex;">
<img
style="height: var(--lumo-size-m); margin-right: var(--lumo-space-s);"
src="${person.pictureUrl}"
alt="Portrait of ${person.firstName} ${person.lastName}"
/>
<div>
${person.firstName} ${person.lastName}
<div
style="font-size: var(--lumo-font-size-s); color: var(--lumo-secondary-text-color);"
>
${person.profession}
</div>
</div>
</div>
`,
root
);
};
Use a custom filter to allow the user to search by the rendered properties. It is recommended to make filtering case insensitive.
Auto Open
The overlay opens automatically when the field is focused using a pointer (mouse or touch), or when the user types in the field. You can disable that to only open the overlay when the toggle button or Up/Down arrow keys are pressed.
new tab
<vaadin-combo-box
auto-open-disabled
label="Country"
item-label-path="name"
item-value-path="id"
.items="${this.items}"
></vaadin-combo-box>Popup Width
The width of the popup is, by default, the same width as the input field. The popup width can be overridden to any fixed width in cases where the default width is too narrow.
new tab
<vaadin-combo-box
style="--vaadin-combo-box-overlay-width: 350px"
label="Employee"
item-label-path="displayName"
item-value-path="id"
.items="${this.items}"
></vaadin-combo-box>Placeholder
Use the placeholder feature to provide an inline text prompt for the field. Do not create, or use, a separate item for this purpose.
new tab
<vaadin-combo-box
placeholder="Select employee"
label="Employee"
item-label-path="displayName"
item-value-path="id"
.items="${this.items}"
></vaadin-combo-box>Custom Filtering
Combo Box’s filtering, by default, is configured to only show items that contain the entered value:
new tab
<vaadin-combo-box
label="Country"
item-label-path="name"
item-value-path="id"
.items="${this.items}"
></vaadin-combo-box>Custom filtering is also possible. For example, if we only want to show items that start with the user’s input:
new tab
@customElement('combo-box-filtering-2')
export class Example extends LitElement {
protected createRenderRoot() {
const root = super.createRenderRoot();
// Apply custom theme (only supported if your app uses one)
applyTheme(root);
return root;
}
@state()
private allItems: Country[] = [];
@state()
private filteredItems: Country[] = [];
async firstUpdated() {
this.allItems = this.filteredItems = await getCountries();
}
render() {
return html`
<vaadin-combo-box
label="Country"
item-label-path="name"
item-value-path="id"
.filteredItems="${this.filteredItems}"
@filter-changed="${this.filterChanged}"
></vaadin-combo-box>
`;
}
private filterChanged(e: CustomEvent) {
const filter = e.detail.value as string;
this.filteredItems = this.allItems.filter((country) => {
return country.name.toLowerCase().startsWith(filter.toLowerCase());
});
}
}Usage as Autocomplete Field
As the user is typing, the Combo Box will filter out the options that don’t match. Once the correct value has been found, the user can use the Up/Down arrow keys to navigate the list and the Enter key to set the value, essentially using the Combo Box as an autocomplete field.
Best Practices
Combo Box supports lazy loading for large datasets. It reduces the initial load time, consumes less bandwidth and resources.
Note | Do not use as a menu
Combo Box is an input field component, not a generic menu component.
Use the Menu Bar component to create overlays for actions.
|
Related Components
| Component | Usage recommendations |
|---|---|
Simpler overlay selection field without filtering, lazy loading or custom value entry. | |
Better accessibility than Combo Box, as all options are visible without user interaction. | |
Scrollable inline list of options. Supports single and multi-select. | |
Overlay menus for items that trigger actions. |