Combo Box

Combo Box allows the user to choose a value from a filterable list of options presented in an overlay.

Usage
Styling

Custom Value Entry
Custom Item Presentation
Item Class Names
Auto Open
Popup Width
Custom Filtering
Basic Features
Validation
Read-Only & Disabled
Style Variants
Usage as Autocomplete Field
Best Practices
Related Components

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.

Open in a
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 aren’t included in the list of options.

Open in a
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:

Open in a
new tab
<vaadin-combo-box
  allow-custom-value
  label="Browser"
  helper-text="Select or type a browser"
  .items="${this.items}"
  @custom-value-set="${(event: ComboBoxCustomValueSetEvent) => {
    this.items = [...this.items, event.detail];
  }}"
></vaadin-combo-box>

Custom Item Presentation

See Select, Custom Item Presentation.

Items can be customized to display more information than a single line of text.

Open in a
new tab
<vaadin-combo-box
  label="Choose doctor"
  item-label-path="displayName"
  .filteredItems="${this.filteredItems}"
  style="--vaadin-combo-box-overlay-width: 16em"
  @filter-changed="${this.filterChanged}"
  ${comboBoxRenderer(this.renderer, [])}
></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: ComboBoxLitRenderer<Person> = (person) => 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>
`;

Use a custom filter to allow the user to search by the rendered properties. It’s recommended to make filtering case insensitive.

Item Class Names

Items can be styled dynamically, based on application logic and the data in the combo box, through custom class names.

Open in a
new tab
protected override render() {
  return html`
    <vaadin-combo-box
      label="Fruit"
      .items="${this.items}"
      .itemClassNameGenerator="${this.classNameGenerator}"
    ></vaadin-combo-box>
  `;
}

protected classNameGenerator(item: string): string {
  switch (item) {
    case 'Apple':
      return 'coral';
    case 'Banana':
      return 'gold';
    case 'Orange':
      return 'orange';
    case 'Pear':
      return 'yellowgreen';
    default:
      return '';
  }
}

Auto Open

The overlay opens automatically when the field is focused using a pointer (i.e., mouse or touch), or when the user types in the field. You can disable this so that the overlay opens only when the toggle button or the Up/Down arrow keys are pressed.

Open in a
new tab
<vaadin-combo-box
  auto-open-disabled
  label="Country"
  item-label-path="name"
  item-value-path="id"
  .items="${this.items}"
></vaadin-combo-box>

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.

Open in a
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>

Custom Filtering

Combo Box’s filtering, by default, is configured to show only items that contain the entered value:

Open in a
new tab
<ComboBox label="Country" itemLabelPath="name" itemValuePath="id" items={items.value} />

Custom filtering is also possible. For example, if you only want to show items that start with the user’s input you could do something like this:

Open in a
new tab
@customElement('combo-box-filtering-2')
export class Example extends LitElement {
  protected override 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[] = [];

  protected override async firstUpdated() {
    const countries = await getCountries();
    this.allItems = countries;
    this.filteredItems = countries;
  }

  protected override 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(event: ComboBoxFilterChangedEvent) {
    const filter = event.detail.value;
    this.filteredItems = this.allItems.filter(({ name }) =>
      name.toLowerCase().startsWith(filter.toLowerCase())
    );
  }
}

Basic Features

The following features, common to most input field components, are supported:

Label

The label is used to identify the input field. It supports plain-text content, and its length is limited to the width of the field. Helpers and Tooltips can be used to provide additional information that doesn’t fit into the label.

Visible labels are strongly recommended for all input fields. In cases where the built-in label cannot be used, an external element can be associated as the field’s label through the aria-labelledby attribute. Fields without any visible label should include an invisible label for assistive technologies with the aria-label attribute.

Helper

Helpers are used to provide additional information that the user may need to enter in the field, such as format requirements or explanations of the field’s purpose below the field.

A style variant is available for rendering the helper above the field.

In addition to plain text, helpers can contain components and HTML elements. However, complex and interactive content is likely to have accessibility issues.

Placeholder

The placeholder is text that’s displayed when the field is empty. Its primary purpose is to provide a short input hint (e.g., the expected format) in situations where a Helper cannot be used.

Placeholders should not be used as a replacement for a visible label. They can be mistaken for a manually entered value. See Label for alternatives to the built-in field label.

Clear Button

The clear button — which is displayed when the field is not empty — clears the field’s current value. Although the button itself is not keyboard focusable, the clear action can be taken with the Esc key, when the field has focus. The clear button can be especially useful in search and filter fields, where users often need to clear the value. They’re less useful, however, in regular forms.

Prefix

A prefix element — rendered at the start of the field — can be used to display units, icons, and similar visual cues to the field’s purpose or format.

Prefix elements typically don’t work well with assistive technologies like screen readers. Therefore, the information communicated by them should also be conveyed through other means, such as in a Label, a Helper or through ARIA attributes on the field itself.

External & Invisible Labels (ARIA)

Visible labels are strongly recommended for all input fields. In situations where the built-in label cannot be used, an external element can be associated as the field’s label through its element id. Fields without any visible label should be provided an invisible label for assistive technologies like screen readers.

<!-- Associates external element as label: -->
<label id="external-label">This is the label</label>
<vaadin-combo-box accessible-name-ref="external-label">...

<!-- Invisible label for screen readers: -->
<vaadin-combo-box accessible-name="This is the label">...

Open in a
new tab
<vaadin-combo-box
  label="Label"
  helper-text="Helper text"
  placeholder="Placeholder"
  clear-button-visible
  .items="${['Value']}"
>
  <vaadin-tooltip slot="tooltip" text="Tooltip text"></vaadin-tooltip>
  <vaadin-icon slot="prefix" icon="vaadin:search"></vaadin-icon>
</vaadin-combo-box>

Validation

Combo Box provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation occurs typically when the user initiates a value change, for example by selecting an item from the overlay or through text input followed by Enter. If the value is invalid, the field is highlighted in red, and an error message appears underneath the input. Certain constraints, however, can proactively prevent users from entering characters that would result in an invalid value.

Below is a list of supported constraints with more detailed information:

Required

Required fields are marked with an indicator next to the label, and become invalid if their value is first entered and then cleared.

An instruction text at the top of the form explaining the required indicator is recommended. The indicator itself can be customized with the --lumo-required-field-indicator style property.

Allowed Characters

A separate single-character, regular expression can be used to restrict the characters that can be entered into the field. Characters that don’t match the expression are rejected. However, values set programmatically are not subject to this restriction, even if they contain disallowed characters.

Open in a
new tab
<vaadin-combo-box
  required
  allowed-char-pattern="[A-Z]"
  label="Country code"
  helper-text="2-letter uppercase ISO country code"
  error-message="Field is required"
  allow-custom-value
  .items="${['DE', 'FI', 'US']}"
></vaadin-combo-box>

Note	Data Binding & Custom Validation Flow and Hilla offer an advanced API called Binder that allows you to bind data and add custom validation rules for multiple fields, creating forms. You can learn more about Binder from the corresponding Flow and Hilla articles.

Read-Only & Disabled

Fields used to display values should be set to read-only mode to prevent editing. Read-only fields are focusable and visible to screen readers. They can display tooltips. Their values can be selected and copied.

Fields that are currently unavailable should be disabled. The reduced contrast of disabled fields makes them inappropriate for displaying information. They can’t be focused or display tooltips. They’re invisible to screen readers, and their values cannot be selected and copied.

Disabled fields can be useful in situations where they can become enabled based on some user action. Consider hiding fields entirely if there’s nothing the user can do to make them editable.

Open in a
new tab
<vaadin-combo-box readonly label="Read-only" .items="${['Value']}" value="Value">
</vaadin-combo-box>

<vaadin-combo-box disabled label="Disabled"></vaadin-combo-box>

Style Variants

The following style variants can be applied:

Text Alignment

Three different text alignments are supported: left, which is the default; center; and right.

Right-alignment is recommended for numerical values when presented in vertical groups. This tends to aid interpretation and comparison of values.

Small Variant

The small variant can be used to make individual fields more compact. The default size of fields can be customized with style properties.

Helper Above Field

The helper can be rendered above the field, and below the label.

Borders

Borders can be applied to the field surface by providing a value (e.g., 1px) to the --vaadin-input-field-border-width CSS property. This can be applied globally to all input fields using the html selector, or to individual component instances. Borders are required to achieve WCAG 2.1 level AA conformant color contrast with the default Lumo styling of fields.

You can override the default border color with the --vaadin-input-field-border-color property.

Open in a
new tab
<vaadin-combo-box
  theme="align-right small helper-above-field"
  label="Label"
  helper-text="Helper text"
  .items="${['Value']}"
  value="Value"
  style="--vaadin-input-field-border-width: 1px;"
>
</vaadin-combo-box>

Usage as Autocomplete Field

As the user is typing, the Combo Box filters 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, and consumes less bandwidth and resources.

Note	Don’t 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.

Component	Usage Recommendation
Select	Simpler overlay selection field without filtering, lazy loading or custom value entry.
Radio Button	Better accessibility than Combo Box, as all options are visible without user interaction.
List Box	Scrollable inline list of options. Supports single and multi-select.
Menu Bar	Overlay menus for items that trigger actions.

Component

Usage Recommendation

Select

Simpler overlay selection field without filtering, lazy loading or custom value entry.

Radio Button

Better accessibility than Combo Box, as all options are visible without user interaction.

List Box

Scrollable inline list of options. Supports single and multi-select.

Menu Bar

Overlay menus for items that trigger actions.

1DFB67E2-2A7B-4339-8C20-FC546C664BB2

Docs

Docs

Combo Box

Custom Value Entry

Custom Item Presentation

Item Class Names

Auto Open

Custom Filtering

Basic Features

Validation

Read-Only & Disabled

Style Variants

Usage as Autocomplete Field

Best Practices

Docs

Custom Value Entry

Custom Item Presentation

Item Class Names

Auto Open

Popup Width

Custom Filtering

Basic Features

Validation

Read-Only & Disabled

Style Variants

Usage as Autocomplete Field

Best Practices

Related Components