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

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

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

*_This section has not yet been updated for Vaadin Framework 8_*

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%]

[[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.newitems]]
== Allowing Adding New Items

[classname]#ComboBox# allows the user to add new items, when the user types
in a value and presses kbd:[Enter]. You need to enable this with
[methodname]#setNewItemHandler()#.

Adding new items is not possible if the selection component is read-only. An
attempt to do so may result in an exception.


=== Handling New Items

Adding new items is handled by a [interfacename]#NewItemHandler#, which gets the
item caption string as parameter for the [methodname]#accept(String)# method.


[source, java]
----
// List of planets
List<Planet> planets = new ArrayList<>();
planets.add(new Planet(1, "Mercury"));
planets.add(new Planet(2, "Venus"));
planets.add(new Planet(3, "Earth"));
planets.add(new Planet(4, "Mars"));

ComboBox<Planet> select =
    new ComboBox<>("Select or Add a Planet");
select.setItems(planets);

// Use the name property for item captions
select.setItemCaptionGenerator(Planet::getName);

// Allow adding new items and add
// handling for new items
select.setNewItemHandler(inputString -> {

    // Create a new bean - can't set all properties
    Planet newPlanet = new Planet(planets.size(), inputString);
    planets.add(newPlanet);

    // Update combobox content
    select.setItems(planets);

    // Remember to set the selection to the new item
    select.select(newPlanet);

    Notification.show("Added new planet called " +
                      inputString);
});
----

[[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.