5.15. Selecting Items

Vaadin gives many alternatives for selecting one or more items from a list, using drop-down and regular lists, radio button and check box groups, tables, trees, and so on.

The core library includes the following selection components, all based on the AbstractSelect class:

A drop-down list for single selection. The component also provides an input prompt and the user can enter new items.
A vertical list box for selecting items in either single or multiple selection mode.
Provides selection using the native selection component of the browser, typically a drop-down list for single selection and a multi-line list in multiselect mode. This uses the <select> element in HTML.
Shows the items as a vertically arranged group of radio buttons in the single selection mode and of check boxes in multiple selection mode.
Shows two list boxes side by side where the user can select items from a list of available items and move them to a list of selected items using control buttons.

In addition, the Tree, Table, and TreeTable components allow special forms of selection. They also inherit the AbstractSelect.

5.15.1. Binding Selection Components to Data

The selection components are strongly coupled with the Vaadin Data Model. The selectable items in all selection components are objects that implement the Item interface and are contained in a Container. The current selection is bound to the Property interface.

Even though the data model is used, the selection components allow simple use in the most common cases. Each selection component is bound to a default container type, which supports management of items without need to implement a container.

See Chapter 9, Binding Components to Data for a detailed description of the data model, its interfaces, and built-in implementations.

Adding New Items

New items are added with the addItem() method defined in the Container interface.

// Create a selection component
ComboBox select = new ComboBox("My ComboBox");

// Add items with given item IDs

The addItem() method creates an empty Item, which is identified by its item identifier (IID) object, given as the parameter. This item ID is by default used also as the caption of the item, as described in more detail later.

We emphasize that addItem() is a factory method that takes an item ID, not the actual item as the parameter - the item is returned by the method. The item is of a type that is specific to the container and has itself little relevance for most selection components, as the properties of an item may not be used in any way (except in Table), only the item ID.

The item identifier is typically a string, in which case it can be used as the caption, but can be any object type. We could as well have given integers for the item identifiers and set the captions explicitly with setItemCaption(). You could also add an item with the parameterless addItem(), which returns an automatically generated item ID.

// Create a selection component
ComboBox select = new ComboBox("My Select");

// Add an item with a generated ID
Object itemId = select.addItem();
select.setItemCaption(itemId, "The Sun");

// Select the item

Some container types may support passing the actual data object to the add method. For example, you can add items to a BeanItemContainer with addBean(). Such implementations can use a separate item ID object, or the data object itself as the item ID, as is done in addBean(). In the latter case you can not depend on the default way of acquiring the item caption; see the description of the different caption modes later.

The following section describes the different options for determining the item captions.

Item Captions

The displayed captions of items in a selection component can be set explicitly with setItemCaption() or determined from the item IDs or item properties. The caption determination is defined with the caption mode, any of the modes in the AbstractSelect.ItemCaptionMode enum, which you can set with setItemCaptionMode(). The default mode is EXPLICIT_DEFAULTS_ID, which uses the item identifiers for the captions, unless given explicitly.

In addition to a caption, an item can have an icon. The icon is set with setItemIcon().

Caption Modes for Selection Components


This is the default caption mode and its flexibility allows using it in most cases. By default, the item identifier will be used as the caption. The identifier object does not necessarily have to be a string; the caption is retrieved with toString() method. If the caption is specified explicitly with setItemCaption(), it overrides the item identifier.

// Create a selection component
ComboBox select = new ComboBox("Moons of Mars");

// Use the item ID also as the caption of this item
select.addItem(new Integer(1));

// Set item caption for this item explicitly
select.addItem(2); // same as "new Integer(2)"
select.setItemCaption(2, "Deimos");

Captions must be explicitly specified with setItemCaption(). If they are not, the caption will be empty. Such items with empty captions will nevertheless be displayed in the selection component as empty items. If they have an icon, they will be visible.


Only icons are shown, captions are hidden.


String representation of the item identifier object is used as caption. This is useful when the identifier is a string, and also when the identifier is an complex object that has a string representation. For example:

ComboBox select = new ComboBox("Inner Planets");

// A class that implements toString()
class PlanetId extends Object implements Serializable {
    private static final long serialVersionUID = -7452707902301121901L;

    String planetName;
    PlanetId (String name) {
        planetName = name;
    public String toString () {
        return "The Planet " + planetName;

// Use such objects as item identifiers
String planets[] = {"Mercury", "Venus", "Earth", "Mars"};
for (int i=0; i<planets.length; i++)
    select.addItem(new PlanetId(planets[i]));

Index number of item is used as caption. This caption mode is applicable only to data sources that implement the Container.Indexed interface. If the interface is not available, the component will throw a ClassCastException. The AbstractSelect itself does not implement this interface, so the mode is not usable without a separate data source. An IndexedContainer, for example, would work.


String representation of item, acquired with toString(), is used as the caption. This is applicable mainly when using a custom Item class, which also requires using a custom Container that is used as a data source for the selection component.


Item captions are read from the String representation of the property with the identifier specified with setItemCaptionPropertyId(). This is useful, for example, when you have a container that you use as the data source for the selection component, and you want to use a specific property for caption.

In the example below, we bind a selection component to a bean container and use a property of the bean as the caption.

/* A bean with a "name" property. */
public class Planet implements Serializable {
    String name;

    public Planet(String name) {
        this.name = name;

    public void setName(String name) {
        this.name = name;

    public String getName() {
        return name;

void propertyModeExample(VerticalLayout layout) {
    // Have a bean container to put the beans in
    BeanItemContainer<Planet> container =
        new BeanItemContainer<Planet>(Planet.class);

    // Put some example data in it
    container.addItem(new Planet(1, "Mercury"));
    container.addItem(new Planet(2, "Venus"));
    container.addItem(new Planet(3, "Earth"));
    container.addItem(new Planet(4, "Mars"));

    // Create a selection component bound to the container
    ComboBox select = new ComboBox("Planets", container);

    // Set the caption mode to read the caption directly
    // from the 'name' property of the bean


Getting and Setting Selection

A selection component provides the current selection as the property of the component (with the Property interface). The property value is an item identifier object that identifies the selected item. You can get the identifier with getValue() of the Property interface.

You can select an item with the corresponding setValue() method. In multiselect mode, the property will be an unmodifiable set of item identifiers. If no item is selected, the property will be null in single selection mode or an empty collection in multiselect mode.

The ComboBox and NativeSelect will show empty selection when no actual item is selected. This is the null selection item identifier. You can set an alternative ID with setNullSelectionItemId(). Setting the alternative null ID is merely a visual text; the getValue() will still return null value if no item is selected, or an empty set in multiselect mode.

The item identifier of the currently selected item will be set as the property of the selection component. You can access it with the getValue() method of the Property interface of the component. Also, when handling selection changes with a Property.ValueChangeListener, the ValueChangeEvent will have the selected item as the property of the event, accessible with the getProperty() method.

Figure 5.35. Selected Item

Selected Item

5.15.2. ComboBox

The ComboBox 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.

Figure 5.36. The ComboBox Component

The ComboBox Component

Filtered Selection

ComboBox allows filtering the items available for selection in the drop-down list by the text entered in the input box. Pressing Enter will complete the item in the input box. Pressing Up- and Down-arrows 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 filtering is done according to the the filtering mode defined in the FilteringMode enum. They are as follows:


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


Matches only items that begin with the given string.

OFF (default)

Filtering is by default off.

ComboBox combobox = new ComboBox("Enter containing substring");

// Set the filtering mode

// Fill the component with some items
final String[] planets = new String[] {
        "Mercury", "Venus", "Earth", "Mars",
        "Jupiter", "Saturn", "Uranus", "Neptune" };
for (int i = 0; i < planets.length; i++)
    for (int j = 0; j < planets.length; j++) {
        combobox.addItem(planets[j] + " to " + planets[i]);

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

Figure 5.37. Filtered Selection

Filtered Selection

CSS Style Rules

.v-filterselect { }
.v-filterselect-input { }
.v-filterselect-button { }
.v-filterselect-suggestpopup { }
.v-filterselect-prefpage-off { }
.v-filterselect-suggestmenu { }
.v-filterselect-status { }
.v-select { }
.v-select-select { }

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 and a status bar in the bottom with v-filterselect-status style. The list of suggestions is padded with an area with v-filterselect-prefpage-off style above and below the list.

5.15.3. ListSelect

The ListSelect component is list box that shows the selectable items in a vertical list. If the number of items exceeds the height of the component, a scrollbar is shown. The component allows both single and multiple selection modes, which you can set with setMultiSelect(). It is visually identical in both modes.

// Create the selection component
ListSelect select = new ListSelect("My Selection");
// Add some items


// Show 5 items and a scrollbar if there are more

The number of visible items is set with setRows().

Figure 5.38. The ListSelect Component

The ListSelect Component

CSS Style Rules

.v-select {}
  .v-select-select {}
    option {}

The component has an overall v-select style. The native select element has v-select-select style.

5.15.4. Native Selection Component NativeSelect

NativeSelect is a drop-down selection component implemented with the native selection input of web browsers, using the HTML <select> element.

// Create the selection component
final NativeSelect select = new NativeSelect("Native Selection");
// Add some items
// Set the width in "columns" as in TextField

The setColumns() allows setting the width of the list as "columns", which is a measure that depends on the browser.

Figure 5.39. The NativeSelect Component

The NativeSelect Component

Multiple selection mode is not allowed; you should use the ListSelect component instead. Also adding new items, which would be enabled with setNewItemsAllowed(), is not allowed.

CSS Style Rules

.v-select {}
.v-select-select {}

The component has a v-select overall style. The native select element has v-select-select style.

5.15.5. Radio Button and Check Box Groups with OptionGroup

The OptionGroup class provides selection from alternatives using a group of radio buttons in single selection mode. In multiple selection mode, the items show up as check boxes.

OptionGroup optiongroup = new OptionGroup("My Option Group");

// Use the multiple selection mode.

Figure 5.40, “Option Button Group in Single and Multiple Selection Mode” shows the OptionGroup in both single and multiple selection mode.

Figure 5.40. Option Button Group in Single and Multiple Selection Mode

Option Button Group in Single and Multiple Selection Mode

You can create check boxes individually using the CheckBox class, as described in Section 5.14, “CheckBox. The advantages of the OptionGroup component are that as it maintains the individual check box objects, you can get an array of the currently selected items easily, and that you can easily change the appearance of a single component.

Disabling Items

You can disable individual items in an OptionGroup with setItemEnabled(). The user can not select or deselect disabled items in multi-select mode, but in single-select mode the use can change the selection from a disabled to an enabled item. The selections can be changed programmatically regardless of whether an item is enabled or disabled. You can find out whether an item is enabled with isItemEnabled().

The setItemEnabled() identifies the item to be disabled by its item ID.

// Have an option group
OptionGroup group = new OptionGroup("My Disabled Group");

// Disable one item
group.setItemEnabled("Two", false);

The item IDs are also used for the captions in this example. The result is shown in Figure 5.41, “OptionGroup with a Disabled Item”.

Figure 5.41. OptionGroup with a Disabled Item

OptionGroup with a Disabled Item

Setting an item as disabled turns on the v-disabled style for it.

CSS Style Rules

.v-select-optiongroup {}
.v-select-option.v-checkbox {}
.v-select-option.v-radiobutton {}

The v-select-optiongroup is the overall style for the component. Each check box will have the v-checkbox style, borrowed from the CheckBox component, and each radio button the v-radiobutton style. Both the radio buttons and check boxes will also have the v-select-option style that allows styling regardless of the option type. Disabled items have additionally the v-disabled style.

The options are normally laid out vertically. You can use horizontal layout by setting display: inline-block for the options. The nowrap setting for the overall element prevents wrapping if there is not enough horizontal space in the layout, or if the horizontal width is undefined.

/* Lay the options horizontally */
.v-select-optiongroup-horizontal .v-select-option {
    display: inline-block;

/* Avoid wrapping if the layout is too tight */
.v-select-optiongroup-horizontal {
    white-space: nowrap;

/* Some extra spacing is needed */
  .v-select-option.v-radiobutton {
    padding-right: 10px;

Use of the above rules requires setting a custom horizontal style name for the component. The result is shown in Figure 5.42, “Horizontal OptionGroup.

Figure 5.42. Horizontal OptionGroup

Horizontal OptionGroup

5.15.6. Twin Column Selection with TwinColSelect

The TwinColSelect field provides a multiple selection component that shows two lists side by side, with the left column containing unselected items and the right column the selected items. The user can select items from the list on the left and click on the ">>" button to move them to the list on the right. Items can be deselected by selecting them in the right list and clicking on the "<<" button.

TwinColSelect is always in multi-select mode, so its property value is always a collection of the item IDs of the selected items, that is, the items in the right column.

The selection columns can have their own captions, separate from the overall component caption, which is managed by the containing layout. You can set the column captions with setLeftColumnCaption() and setRightColumnCaption().

final TwinColSelect select =
    new TwinColSelect("Select Targets to Destroy");

// Set the column captions (optional)
select.setLeftColumnCaption("These are left");
select.setRightColumnCaption("These are done for");
// Put some data in the select
String planets[] = {"Mercury", "Venus", "Earth", "Mars",
        "Jupiter", "Saturn", "Uranus", "Neptune"};
for (int pl=0; pl<planets.length; pl++)

// Set the number of visible items

The resulting component is shown in Figure 5.43, “Twin Column Selection”.

Figure 5.43. Twin Column Selection

Twin Column Selection

The setRows() method sets the height of the component by the number of visible items in the selection boxes. Setting the height with setHeight() to a defined value overrides the rows setting.

CSS Style Rules

.v-select-twincol {}
  .v-select-twincol-options-caption {}
  .v-select-twincol-selections-caption {}
  .v-select-twincol-options {}
  .v-select-twincol-buttons {}
    .v-button {}
      .v-button-wrap {}
        .v-button-caption {}
    .v-select-twincol-deco {}
.v-select-twincol-selections {}

The TwinColSelect component has an overall v-select-twincol style. If set, the left and right column captions have v-select-twincol-options-caption and v-select-twincol-options-caption style names, respectively. The left box, which displays the unselected items, has v-select-twincol-options-caption style and the right box, which displays the selected items, has v-select-twincol-options-selections style. Between them is the button area, which has overall v-select-twincol-buttons style; the actual buttons reuse the styles for the Button component. Between the buttons is a divider element with v-select-twincol-deco style.

5.15.7. Allowing Adding New Items

The selection components allow the user to add new items, with a user interface similar to combo boxes in desktop user interfaces. You need to enable the newItemsAllowed mode with the setNewItemsAllowed() method.


The user interface for adding new items depends on the selection component and the selection mode. The regular ComboBox component allows you to simply type the new item in the combo box and hit Enter to add it. In most other selection components, a text field that allows entering new items is shown below the selection list, and clicking the + button will add the item in the list, as illustrated in Figure 5.44, “ComboBox with Adding New Items Allowed”.

Figure 5.44. ComboBox with Adding New Items Allowed

ComboBox with Adding New Items Allowed

The identifier of an item added by the user will be a String object identical to the caption of the item. You should consider this if the item identifier of automatically filled items is some other type or otherwise not identical to the caption.

Adding new items may not be possible if the ComboBox is bound to an external Container that does not allow adding new items.

5.15.8. Multiple Selection

Some selection components, such as OptionGroup and ListSelect support a multiple selection mode, which you can enable with setMultiSelect(). For TwinColSelect, which is especially intended for multiple selection, it is enabled by default.


As in single selection mode, the property value of the component indicates the selection. In multiple selection mode, however, the property value is a Collection of the item IDs of the currently selected items. You can get and set the property with the getValue() and setValue() methods as usual.

A change in the selection will trigger a ValueChangeEvent, which you can handle with a Propery.ValueChangeListener. As usual, you should use setImmediate(true) to trigger the event immediately when the user changes the selection. The following example shows how to handle selection changes with a listener.

// A selection component with some items
ListSelect select = new ListSelect("My Selection");
for (String planet: new String[]{"Mercury", "Venus",
        "Earth", "Mars", "Jupiter", "Saturn", "Uranus",

// Multiple selection mode

// Feedback on value changes
    new Property.ValueChangeListener() {
    public void valueChange(ValueChangeEvent event) {
        // Some feedback
        layout.addComponent(new Label("Selected: " +

5.15.9. Other Common Features

Item Icons

You can set an icon for each item with setItemIcon(), or define an item property that provides the icon resource with setItemIconPropertyId(), in a fashion similar to captions. Notice, however, that icons are not supported in NativeSelect, TwinColSelect, and some other selection components and modes. This is because HTML does not support images inside the native select elements. Icons are also not really visually applicable.

I. Introduction
1. Introduction
1.1. Overview
1.2. Example Application Walkthrough
1.3. Support for the Eclipse IDE
1.4. Goals and Philosophy
1.5. Background
2. Getting Started with Vaadin
2.1. Overview
2.2. Setting up the Development Environment
2.3. Overview of Vaadin Libraries
2.4. Installing Vaadin Plugin for Eclipse
2.5. Creating and Running a Project with Eclipse
2.6. Using Vaadin with Maven
2.7. Creating a Project with NetBeans IDE
2.8. Creating a Project with IntelliJ IDEA
2.9. Vaadin Installation Package
2.10. Using Vaadin with Scala
3. Architecture
3.1. Overview
3.2. Technological Background
3.3. Client-Side Engine
3.4. Events and Listeners
II. Server-Side Framework
4. Writing a Server-Side Web Application
4.1. Overview
4.2. Building the UI
4.3. Handling Events with Listeners
4.4. Images and Other Resources
4.5. Handling Errors
4.6. Notifications
4.7. Application Lifecycle
4.8. Deploying an Application
5. User Interface Components
5.1. Overview
5.2. Interfaces and Abstractions
5.3. Common Component Features
5.4. Field Components
5.5. Component Extensions
5.6. Label
5.7. Link
5.8. TextField
5.9. TextArea
5.10. PasswordField
5.11. RichTextArea
5.12. Date and Time Input with DateField
5.13. Button
5.14. CheckBox
5.15. Selecting Items
5.16. Table
5.17. Tree
5.18. MenuBar
5.19. Embedded Resources
5.20. Upload
5.21. ProgressBar
5.22. Slider
5.23. Calendar
5.24. Component Composition with CustomComponent
5.25. Composite Fields with CustomField
6. Managing Layout
6.1. Overview
6.2. UI, Window, and Panel Content
6.3. VerticalLayout and HorizontalLayout
6.4. GridLayout
6.5. FormLayout
6.6. Panel
6.7. Sub-Windows
6.8. HorizontalSplitPanel and VerticalSplitPanel
6.9. TabSheet
6.10. Accordion
6.11. AbsoluteLayout
6.12. CssLayout
6.13. Layout Formatting
6.14. Custom Layouts
7. Visual User Interface Design with Eclipse
7.1. Overview
7.2. Creating a New Composite
7.3. Using The Visual Editor
7.4. Structure of a Visually Editable Component
8. Themes
8.1. Overview
8.2. Introduction to Cascading Style Sheets
8.3. Syntactically Awesome Stylesheets (Sass)
8.4. Creating and Using Themes
8.5. Creating a Theme in Eclipse
8.6. Responsive Themes
9. Binding Components to Data
9.1. Overview
9.2. Properties
9.3. Holding properties in Items
9.4. Creating Forms by Binding Fields to Items
9.5. Collecting Items in Containers
10. Vaadin SQLContainer
10.1. Architecture
10.2. Getting Started with SQLContainer
10.3. Filtering and Sorting
10.4. Editing
10.5. Caching, Paging and Refreshing
10.6. Referencing Another SQLContainer
10.7. Using FreeformQuery and FreeformStatementDelegate
10.8. Non-implemented methods of Vaadin container interfaces
10.9. Known Issues and Limitations
11. Advanced Web Application Topics
11.1. Handling Browser Windows
11.2. Embedding UIs in Web Pages
11.3. Debug Mode and Window
11.4. Request Handlers
11.5. Shortcut Keys
11.6. Printing
11.7. Google App Engine Integration
11.8. Common Security Issues
11.9. Navigating in an Application
11.10. Advanced Application Architectures
11.11. Managing URI Fragments
11.12. Drag and Drop
11.13. Logging
11.14. JavaScript Interaction
11.15. Accessing Session-Global Data
11.16. Server Push
12. Portal Integration
12.1. Overview
12.2. Creating a Portlet Project in Eclipse
12.3. Portlet UI
12.4. Deploying to a Portal
12.5. Installing Vaadin in Liferay
12.6. Handling Portlet Requests
12.7. Handling Portlet Mode Changes
12.8. Non-Vaadin Portlet Modes
12.9. Vaadin IPC for Liferay
III. Client-Side Framework
13. Client-Side Vaadin Development
13.1. Overview
13.2. Installing the Client-Side Development Environment
13.3. Client-Side Module Descriptor
13.4. Compiling a Client-Side Module
13.5. Creating a Custom Widget
13.6. Debugging Client-Side Code
14. Client-Side Applications
14.1. Overview
14.2. Client-Side Module Entry-Point
14.3. Compiling and Running a Client-Side Application
14.4. Loading a Client-Side Application
15. Client-Side Widgets
15.1. Overview
15.2. GWT Widgets
15.3. Vaadin Widgets
16. Integrating with the Server-Side
16.1. Overview
16.2. Starting It Simple With Eclipse
16.3. Creating a Server-Side Component
16.4. Integrating the Two Sides with a Connector
16.5. Shared State
16.6. RPC Calls Between Client- and Server-Side
16.7. Component and UI Extensions
16.8. Styling a Widget
16.9. Component Containers
16.10. Creating Add-ons
16.11. Migrating from Vaadin 6
16.12. Integrating JavaScript Components and Extensions
IV. Vaadin Add-ons
17. Using Vaadin Add-ons
17.1. Overview
17.2. Downloading Add-ons from Vaadin Directory
17.3. Installing Add-ons in Eclipse with Ivy
17.4. Using Add-ons in a Maven Project
17.5. Troubleshooting
18. Vaadin Charts
18.1. Overview
18.2. Installing Vaadin Charts
18.3. Basic Use
18.4. Chart Types
18.5. Chart Configuration
18.6. Chart Data
18.7. Advanced Uses
18.8. Timeline
19. Vaadin JPAContainer
19.1. Overview
19.2. Installing
19.3. Defining a Domain Model
19.4. Basic Use of JPAContainer
19.5. Entity Providers
19.6. Filtering JPAContainer
19.7. Querying with the Criteria API
19.8. Automatic Form Generation
19.9. Using JPAContainer with Hibernate
20. Mobile Applications with TouchKit
20.1. Overview
20.2. Considerations Regarding Mobile Browsing
20.3. Installing Vaadin TouchKit
20.4. Importing the Vornitologist Demo
20.5. Creating a New TouchKit Project
20.6. Elements of a TouchKit Application
20.7. Mobile User Interface Components
20.8. Advanced Mobile Features
20.9. Offline Mode
20.10. Building an Optimized Widget Set
20.11. Testing and Debugging on Mobile Devices
21. Vaadin TestBench
21.1. Overview
21.2. Installing Vaadin TestBench
21.3. Preparing an Application for Testing
21.4. Using Vaadin TestBench Recorder
21.5. Developing JUnit Tests
21.6. Taking and Comparing Screenshots
21.7. Running Tests in a Distributed Environment
21.8. Headless Testing
21.9. Known Issues
A. Songs of Vaadin