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

---
title: TwinColSelect
order: 20
layout: page
---

[[components.twincolselect]]
= TwinColSelect

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

The [classname]#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.

[[figure.components.twincolselect.basic]]
.Twin Column Selection
image::img/twincolselect-basic.png[width=50%, scaledwidth=80%]

[classname]#TwinColSelect# is always in multi-select mode, so its selection
is always a collection of the selected 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 [methodname]#setLeftColumnCaption()# and
[methodname]#setRightColumnCaption()#.


[source, java]
----
TwinColSelect<String> select =
    new TwinColSelect<>("Select Targets");

// Put some items in the select
select.setItems("Mercury", "Venus", "Earth", "Mars",
        "Jupiter", "Saturn", "Uranus", "Neptune");

// Few items, so we can set rows to match item count
select.setRows(select.size());

// Preselect a few items
select.select("Venus", "Earth", "Mars");

// Handle value changes
select.addSelectionListener(event ->
    layout.addComponent(
        new Label("Selected: " + event.getNewSelection())));
----

The resulting component is shown in <<figure.components.twincolselect.basic>>.

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

[WARNING]
The [classname]#TwinColSelect# does not provide lazy loading mechanism.
Hence it will slow down significantly if used with large itemsets.
The lazy loading feature could be implemented using two single column Grids instead.

Common selection component features are described in
<<components-selection#components.selection,"Selection
Components">>.

== CSS Style Rules


[source, css]
----
.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 [classname]#TwinColSelect# component has an overall
[literal]#++v-select-twincol++# style. If set, the left and right column
captions have [literal]#++v-select-twincol-options-caption++# and
[literal]#++v-select-twincol-options-caption++# style names, respectively. The
left box, which displays the unselected items, has
[literal]#++v-select-twincol-options-caption++# style and the right box, which
displays the selected items, has
[literal]#++v-select-twincol-options-selections++# style. Between them is the
button area, which has overall [literal]#++v-select-twincol-buttons++# style;
the actual buttons reuse the styles for the [classname]#Button# component.
Between the buttons is a divider element with
[literal]#++v-select-twincol-deco++# style.