vaadin-framework/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
[classname]#AbstractSingleSelect# or [classname]#AbstractMultiSelect# class:

[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::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()# .

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


[[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.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
[interfacename]#HasValue# interface that returns either a single selected item
(case of [interfacename]#SingleSelect#) or a collection of selected items (case of [interfacename]#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 Events

You can access the currently selected item with the [methodname]#getValue()# ([interfacename]#SingleSelect#) or
[methodname]#getSelectedItems()# ([interfacename]#MultiSelect#) method of the component. Also, when
handling selection events 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, [interfacename]#SingleSelectionListener# for [classname]#SingleSelectionEvent# and [interfacename]#MultiSelectionListener# for [classname]#MultiSelectionEvent# respectively. Both can be added with the [methodname]#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 event
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%]


[[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 [interfacename]#MultiSelect# interface which extends [interfacename]#HasValue#.
This provides more fine grained API for selection. You can get and set the selection with the [methodname]#getSelectedItems()# and
[methodname]#select()# methods.

A change in the selection will trigger a [classname]#SelectionEvent#, which
you can handle with a [classname]#SelectionListener#. 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()));
    }
});

----