path: root/documentation/components/components-selection.asciidoc

---
title: Selection Components
order: 5
layout: page
---

[[components.selection]]
= Selection Components

For a better overview on how selection works, see link:../datamodel/datamodel-selection.asciidoc[Selecting items]

Vaadin offers many alternative ways for selecting one or more items. The core
library includes the following selection components, all based on either
`AbstractSingleSelect` or `AbstractMultiSelect` class:

// TODO Only use section numbers here, prefixed with "Section", not include section title

[classname]#ComboBox# (<<components-combobox#components.combobox,"ComboBox">>)::
A drop-down list with a text box, where the user can type text to find matching items.
The component also provides a placeholder and the user can enter new items.

[classname]#ListSelect# (<<components-listselect#components.listselect,"ListSelect">>)::
A vertical list box for selecting items in either single or multiple selection mode.

[classname]#NativeSelect# (<<components-nativeselect#components.nativeselect, "NativeSelect">>)::
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 [literal]#++<select>++# element in HTML.

[classname]#RadioButtonGroup# (<<components-optiongroups#components.optiongroups,"CheckBoxGroup and RadioButtonGroup">>)::
Shows the items as a vertically arranged group of radio buttons in single selection mode.

[classname]#CheckBoxGroup# (<<components-optiongroups#components.optiongroups,"CheckBoxGroup and RadioButtonGroup">>)::
Shows the items as a vertically arranged group of check boxes in multiple selection mode.

[classname]#TwinColSelect# (<<components-twincolselect#components.twincolselect, "TwinColSelect">>)::
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 [classname]#Grid# component allows user selection.

[[components.selection.databinding]]
== Binding Selection Components to Data

The selection components are typically bound to list of items obtained from backend system.
You can give the list of items in the constructor or set it with
[methodname]#setItems()#. Read more in
<<dummy/../../../framework/datamodel/datamodel-overview.asciidoc#datamodel.overview,"Binding
Components to Data">>.

You can get the current selection as the
value of the selection component using [methodname]#getValue# defined in
[interfacename]#HasValue# interface. Selection changes are handled as value change or
selection events, as is described later.


[[components.selection.captions]]
== Item Captions

The items are typically a strings, in which case they can be used as the
caption, but can be any object type. We could as well have given Planet instances
for the items and use captions generated based on them
[methodname]#setItemCaptionGenerator()# method.

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

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

// Add an items to the ComboBox
select.setItems(planets);

select.setItemCaptionGenerator(planet -> planet.getName());
// or even select.setItemCaptionGenerator(Planet::getName);

// Select the first
select.setSelectedItem(planets.get(0));
// or
select.setValue(planets.get(0));
----

In addition to a caption, an item can have an icon. The icon is set with
[methodname]#setItemIconGenerator()#.

Typical use cases for captions are:

Using the items as the caption: the caption is
retrieved with [methodname]#toString()# method from the item. This is useful
for simple objects like String or Integers, but also for objects that have
human readable output for [methodname]#toString()# .

[source, java]
----
ComboBox<Planet> select = new ComboBox<>("Inner Planets");

// A class that implements toString()
class Planet implements Serializable {
    String planetName;

    Planet(String name) {
        planetName = name;
    }

    public String toString () {
        return "The Planet " + planetName;
    }
}

// Use such objects as items
List<Planet> planets = new ArrayList<>();
planets.add(new Planet("Mercury"));
planets.add(new Planet("Venus"));
planets.add(new Planet("Earth"));

select.setItems(planets);
----

Using a field of a item as caption: the caption is retrieved using the
[interfacename]#ItemCaptionGenerator# typically given as Java 8 lambda.

[source, java]
----
// A class that implements toString()
class Planet implements Serializable {
    Integer id;
    String planetName;

    Planet(Integer id, String name) {
        this.id = id
        this.planetName = name;
    }

    public String toString () {
        return "The Planet " + planetName;
    }

    public Integer getId () {
        return id;
    }


    public String getName () {
        return planetName;
    }

}

// Put some example data
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"));

// Create a selection component
ComboBox<Planet> select =
    new ComboBox<>("Planets");

// Set the caption generator to read the
// caption directly from the 'name'
// property of the bean
select.setItemCaptionGenerator(Planet::getName);
----


[[components.selection.item-icons]]
== Item Icons

You can set an icon for each item with [methodname]#setItemIconGenerator()#,
in a fashion similar to captions. Notice, however, that icons are not
supported in [classname]#NativeSelect#, [classname]#TwinColSelect#, and
some other selection components and modes. This is because HTML does not
support images inside the native [literal]#++select++#
elements.


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

[[components.selection.newitems.handling]]
=== 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.

ifdef::web[]

[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(0, 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.selection.getset]]
== Getting and Setting Selection

For a better overview on how selection works, see link:../datamodel/datamodel-selection.asciidoc[Selecting items]

You can get selected the item with [methodname]#getValue()# of the
[classname]#HasValue# interface that returns either a single selected item
(case of `SingleSelect`) or a collection of selected items (case of `MultiSelect`).
You can select an item with the corresponding [methodname]#setValue()# method.

The [classname]#ComboBox# and [classname]#NativeSelect# will show empty
selection when no actual item is selected.


[[components.selection.valuechange]]
== Handling Selection Changes

You can access the currently selected item with the [methodname]#getValue()# (`SingleSelect`) or
[methodname]#getSelectedItems()# (`MultiSelect`) method of the component. Also, when
handling selection changes with a
[classname]#SelectionListener#, the
[classname]#SelectionEvent# will have the selected items of the event. Single- and Multiselect
components have their own more specific listener and event types, `SingleSelectionListener` for `SingleSelectionEvent` and `MultiSelectionListener` for `MultiSelectionEvent` respectively. Both can be added with the `addSelectionListener` method.


[source, java]
----
// Create a selection component with some items
ComboBox<String> select = new ComboBox<>("My Select");
select.setItems("Io", "Europa", "Ganymedes", "Callisto");

// Handle selection change
select.addSelectionListener(event ->
    layout.addComponent(new Label("Selected " +
        event.getSelectedItem().orElse("none")));
----

The result of user interaction is shown in
<<figure.components.selection.valuechange>>.

[[figure.components.selection.valuechange]]
.Selected Item
image::img/select-selected1.png[width=30%, scaledwidth=40%]


----
endif::web[]


[[components.selection.multiple]]
== Multiple Selection

For a better overview on how selection works, see link:../datamodel/datamodel-selection.asciidoc[Selecting items]

Some selection components, such as [classname]#CheckBoxGroup#,
[classname]#ListSelect# and [classname]#TwinColSelect# are multiselect components,
they extend [classname]#AbstractMultiSelect# class.


Multiselect components use the `MultiSelect` interface which extends `HasValue`.
This provides more fine grained API for selection. You can get and set the selection with the [methodname]#MultiSelect.getSelectedItems()# and
[methodname]#SelectionModel.Multi.selectItems()# methods.

A change in the selection will trigger a [classname]#SelectionChange#, which
you can handle with a [classname]#SelectionChangeListener#. The
following example shows how to handle selection changes with a listener.


[source, java]
----
// A selection component with some items
ListSelect<String> select = new ListSelect<>("My Selection");
select.setItems("Mercury", "Venus", "Earth",
    "Mars", "Jupiter", "Saturn", "Uranus", "Neptune");

// Feedback on value changes
select.addSelectionListener(event -> {
        // Some feedback
        layout.addComponent(new Label("Selected: " +
            event.getNewSelection()));
    }
});

----