Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

ComboBox

Live Demo

ComboBox is a selection component allows selecting an item from a drop-down list. The component also has a text field area, which allows entering search text by which the items shown in the drop-down list are filtered. Common selection component features are described in "Selection Components".

combobox basic
The ComboBox Component

ComboBox supports adding new items when the user presses Enter. See "Allowing Adding New Items".

Filtered Selection

ComboBox allows filtering the items available for selection in the drop-down list by the text entered in the input box.

combobox filtering
Filtered Selection in ComboBox

Pressing Enter will complete the item in the input box. Pressing Up and Down arrow keys can be used for selecting an item from the drop-down list. The drop-down list is paged and clicking on the scroll buttons will change to the next or previous page. The list selection can also be done with the arrow keys on the keyboard. The shown items are loaded from the server as needed, so the number of items held in the component can be quite large. The number of matching items is displayed by the drop-down list.

Filtering is enabled by setting a filtering mode with setFilteringMode().

cb.setFilteringMode(FilteringMode.CONTAINS);

See the on-line example.

The modes defined in the FilteringMode enum are as follows:

CONTAINS

Matches any item that contains the string given in the text field part of the component.

STARTSWITH

Matches only items that begin with the given string.

OFF (default)

Filtering is by default off and all items are shown all the time.

The above example uses the containment filter that matches to all items containing the input string. As shown in Filtered Selection in ComboBox below, when we type some text in the input area, the drop-down list will show all the matching items.

CSS Style Rules

.v-filterselect { }
  .v-filterselect-input { }
  .v-filterselect-button { }

// Under v-overlay-container
.v-filterselect-suggestpopup { }
  .popupContent { }
    .v-filterselect-prevpage,
      .v-filterselect-prevpage-off { }
    .v-filterselect-suggestmenu { }
      .gwt-MenuItem { }
    .v-filterselect-nextpage,
      .v-filterselect-nextpage-off { }
    .v-filterselect-status { }

In its default state, only the input field of the ComboBox component is visible. The entire component is enclosed in v-filterselect style (a legacy remnant), the input field has v-filterselect-input style and the button in the right end that opens and closes the drop-down result list has v-filterselect-button style.

The drop-down result list has an overall v-filterselect-suggestpopup style. It contains the list of suggestions with v-filterselect-suggestmenu style. When there are more items that fit in the menu, navigation buttons with v-filterselect-prevpage and v-filterselect-nextpage styles are shown. When they are not shown, the elements have -off suffix. The status bar in the bottom that shows the paging status has v-filterselect-status style.