vaadin-framework/documentation/components/components-combobox.asciidoc

---
title: ComboBox
order: 16
layout: page
---

[[components.combobox]]
= [classname]#ComboBox#

ifdef::web[]
[.sampler]
image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/multiple-value/combo-box"]
endif::web[]

[classname]#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
<<dummy/../../../framework/components/components-selection#components.selection,"Selection
Components">>.

.The [classname]#ComboBox# Component
image::img/combobox-basic.png[width=35%, scaledwidth=50%]

[classname]#ComboBox# supports adding new items when the user presses
kbd:[Enter].
ifdef::web[]
See <<dummy/../../../framework/components/components-selection#components.selection.newitems,"Allowing Adding New Items">>.
endif::web[]

[[components.combobox.filtering]]
== Filtered Selection

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

[[figure.components.combobox.filter]]
.Filtered Selection in [classname]#ComboBox#
image::img/combobox-filtering.png[width=35%, scaledwidth=50%]

Pressing kbd:[Enter] will complete the item in the input box. Pressing kbd:[Up] and kbd:[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
[methodname]#setFilteringMode()#.


[source, java]
----
cb.setFilteringMode(FilteringMode.CONTAINS);
----
See the http://demo.vaadin.com/book-examples-vaadin7/book#component.select.combobox.filtering[on-line example, window="_blank"].

The modes defined in the [classname]#FilteringMode# enum are as follows:

[parameter]#CONTAINS#:: Matches any item that contains the string given in the text field part of the
component.

[parameter]#STARTSWITH#:: Matches only items that begin with the given string.

[parameter]#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 <<figure.components.combobox.filter>>
below, when we type some text in the input area, the drop-down list will show
all the matching items.


[[components.combobox.css]]
== CSS Style Rules


[source, css]
----
.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 [classname]#ComboBox#
component is visible. The entire component is enclosed in
[literal]#++v-filterselect++# style (a legacy remnant), the input field has
[literal]#++v-filterselect-input++# style and the button in the right end that
opens and closes the drop-down result list has
[literal]#++v-filterselect-button++# style.

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