> Markdown version of [Select](https://vaadin.com/docs/v14/ds/components/select). Section index: [llms.txt](https://vaadin.com/docs/v14/ds/llms.txt)

# Select

Select allows users to choose a single value from a list of options presented in an overlay.

`SelectBasic.java`

```java
Select<String> select = new Select<>();
select.setLabel("Sort by");
select.setItems("Most recent first", "Rating: high to low",
  "Rating: low to high", "Price: high to low", "Price: low to high");
select.setValue("Most recent first");

add(select);
```

The dropdown can be opened with a click, up/down arrow keys, or by typing the initial character for one of the options.

## <a id="common-input-field-features"></a>Common Input Field Features

Select includes all Text Field and shared input field features.

- [See Text Field features](https://vaadin.com/docs/v14/ds/components/text-field.md)

- [See shared input field features](https://vaadin.com/docs/v14/ds/components/input-fields.md)

## <a id="dividers"></a>Dividers

Dividers can be used to group related options. Use dividers sparingly to avoid creating unnecessary visual clutter.

`SelectDividers.java`

```java
Select<String> select = new Select<>();
select.setLabel("Sort by");
select.setItems("Most recent first", "Rating: high to low",
  "Rating: low to high", "Price: high to low", "Price: low to high");
select.addComponents("Most recent first", new Hr());
select.addComponents("Rating: low to high", new Hr());
select.setValue("Most recent first");

add(select);
```

> **Note: Use Combo Box for long lists**
>
> Please note that for large data sets it is preferable to use Combo Box instead of Select, as it allows users to filter the list of options.

## <a id="disabled-items"></a>Disabled Items

Items can be disabled. This prevents users from selecting them, while still showing that these items would be available for selection under different circumstances.

`SelectDisabled.java`

```java
Select<String> select = new Select<>();
select.setLabel("Size");
select.setItems("XS (out of stock)", "S", "M", "L", "XL");
select.setItemEnabledProvider(item -> !"XS (out of stock)".equals(item));
select.setValue("XL");

add(select);
```

> **Caution: Accessibility**
>
> Some assistive technologies might not announce disabled options.

## <a id="placeholder"></a>Placeholder

Use the placeholder feature to provide an inline text prompt for the field. Do not create, or use, a separate item for this purpose.

`SelectPlaceholder.java`

```java
Select<String> select = new Select<>();
select.setLabel("Size");
select.setItems("XS", "S", "M", "L", "XL");
select.setPlaceholder("Select size");

add(select);
```

## <a id="empty-selection-item"></a>Empty Selection Item

An empty item can be set as the first option. Use it in cases where you want to allow users to clear their selection. The value of the empty item is represented as `null`.

`SelectEmptySelection.java`

```java
select.setEmptySelectionAllowed(true);
```

### <a id="customizing-empty-selection-caption"></a>Customizing Empty Selection Caption

The label for the empty item is customizable.

The caption set replaces the placeholder for the empty selection item.

`SelectEmptySelectionCaption.java`

```java
select.setEmptySelectionAllowed(true);
select.setEmptySelectionCaption("Unknown size");
```

## <a id="custom-item-label"></a>Custom Item Label

When using complex values, a label can be set to represent the item value as plain text.

`SelectComplexValueLabel.java`

```java
Select<Person> select = new Select<>();
select.setLabel("Assignee");
// Display full name of the person as item text and selected value label
select.setItemLabelGenerator(Person::getFullName);

List<Person> people = DataService.getPeople(5);
select.setItems(people);
```

`Person.java`

```java
public class Person {

  private String firstName;

  private String lastName;

  private String email;

  private Date birthday;

  private Integer id;

  private boolean subscriber;

  private String membership;

  private String pictureUrl;

  private String profession;

  private Address address;

  private Integer managerId;

  private boolean manager;

  private String status;

  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }

  public String getFullName() {
    return firstName + " " + lastName;
  }

  public String getEmail() {
    return email;
  }

  public void setEmail(String email) {
    this.email = email;
  }

  public Date getBirthday() {
    return birthday;
  }

  public void setBirthday(Date birthday) {
    this.birthday = birthday;
  }

  public boolean isSubscriber() {
    return subscriber;
  }

  public void setSubscriber(boolean subscriber) {
    this.subscriber = subscriber;
  }

  public String getMembership() {
    return membership;
  }

  public void setMembership(String membership) {
    this.membership = membership;
  }

  public String getPictureUrl() {
    return pictureUrl;
  }

  public void setPictureUrl(String pictureUrl) {
    this.pictureUrl = pictureUrl;
  }

  public String getProfession() {
    return profession;
  }

  public void setProfession(String profession) {
    this.profession = profession;
  }

  public Address getAddress() {
    return address;
  }

  public void setAddress(Address address) {
    this.address = address;
  }

  public Integer getId() {
    return id;
  }

  public void setId(Integer id) {
    this.id = id;
  }

  @Override
  public int hashCode() {
    return id;
  }

  @Override
  public boolean equals(Object obj) {
    if (this == obj) {
      return true;
    }
    if (!(obj instanceof Person)) {
      return false;
    }
    Person other = (Person) obj;
    return id == other.id;
  }

  public Integer getManagerId() {
    return managerId;
  }

  public void setManagerId(Integer managerId) {
    this.managerId = managerId;
  }

  public boolean isManager() {
    return manager;
  }

  public void setManager(boolean manager) {
    this.manager = manager;
  }

  public String getStatus() {
    return status;
  }

  public void setStatus(String status) {
    this.status = status;
  }
}
```

When using custom item renderers with rich content, a label can be set to represent the item value when it is selected.

`SelectCustomRendererLabel.java`

```java
Select<Person> select = new Select<>();
select.setLabel("Assignee");
// Use a custom renderer for items in the dropdown
select.setRenderer(SelectCustomRendererLabel.createPersonRenderer());
// Display full name of the person as selected value label
select.setItemLabelGenerator(Person::getFullName);

List<Person> people = DataService.getPeople(5);
select.setItems(people);
```

`Person.java`

```java
public class Person {

  private String firstName;

  private String lastName;

  private String email;

  private Date birthday;

  private Integer id;

  private boolean subscriber;

  private String membership;

  private String pictureUrl;

  private String profession;

  private Address address;

  private Integer managerId;

  private boolean manager;

  private String status;

  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }

  public String getFullName() {
    return firstName + " " + lastName;
  }

  public String getEmail() {
    return email;
  }

  public void setEmail(String email) {
    this.email = email;
  }

  public Date getBirthday() {
    return birthday;
  }

  public void setBirthday(Date birthday) {
    this.birthday = birthday;
  }

  public boolean isSubscriber() {
    return subscriber;
  }

  public void setSubscriber(boolean subscriber) {
    this.subscriber = subscriber;
  }

  public String getMembership() {
    return membership;
  }

  public void setMembership(String membership) {
    this.membership = membership;
  }

  public String getPictureUrl() {
    return pictureUrl;
  }

  public void setPictureUrl(String pictureUrl) {
    this.pictureUrl = pictureUrl;
  }

  public String getProfession() {
    return profession;
  }

  public void setProfession(String profession) {
    this.profession = profession;
  }

  public Address getAddress() {
    return address;
  }

  public void setAddress(Address address) {
    this.address = address;
  }

  public Integer getId() {
    return id;
  }

  public void setId(Integer id) {
    this.id = id;
  }

  @Override
  public int hashCode() {
    return id;
  }

  @Override
  public boolean equals(Object obj) {
    if (this == obj) {
      return true;
    }
    if (!(obj instanceof Person)) {
      return false;
    }
    Person other = (Person) obj;
    return id == other.id;
  }

  public Integer getManagerId() {
    return managerId;
  }

  public void setManagerId(Integer managerId) {
    this.managerId = managerId;
  }

  public boolean isManager() {
    return manager;
  }

  public void setManager(boolean manager) {
    this.manager = manager;
  }

  public String getStatus() {
    return status;
  }

  public void setStatus(String status) {
    this.status = status;
  }
}
```

> **Note: Ensure item label generator handles null values**
>
> When using `setItemLabelGenerator` in combination with `setEmptySelectionAllowed`, ensure that the implementation is capable of handling null values, as the empty selection item has the value `null`.
>
> ```java
> select.setEmptySelectionAllowed(true);
> select.setItemLabelGenerator(person -> {
>   if (person == null) {
>       return "No assignee";
>   }
>   return person.getFullName();
> });
> ```
>
> The same applies when using a data source that may contain null values.

## <a id="custom-item-presentation"></a>Custom Item Presentation

Items can be rendered with rich content instead of plain text. This can be useful to provide information in a more legible fashion than appending it to the item text.

`SelectPresentation.java`

```java
Select<Person> select = new Select<>();
select.setLabel("Choose doctor");
select.setRenderer(new ComponentRenderer<>(person -> {
    FlexLayout wrapper = new FlexLayout();
    wrapper.setAlignItems(Alignment.CENTER);

    // NOTE
    // We are using inline styles here to keep the example simple.
    // We recommend placing CSS in a separate style sheet and to
    // encapsulating the styling in a new component.

    Image image = new Image();
    image.setSrc(person.getPictureUrl());
    image.setAlt("Portrait of " + person.getFirstName() + " " + person.getLastName());
    image.setWidth("var(--lumo-size-m)");
    image.getStyle().set("margin-right", "var(--lumo-space-s)");

    Div info = new Div();
    info.setText(person.getFirstName() + " " + person.getLastName());

    Div profession = new Div();
    profession.setText(person.getProfession());
    profession.getStyle().set("font-size", "var(--lumo-font-size-s)");
    profession.getStyle().set("color", "var(--lumo-secondary-text-color)");
    info.add(profession);

    wrapper.add(image, info);
    return wrapper;
}));
select.setItems(items);
add(select);
```

## <a id="best-practices"></a>Best Practices

### <a id="set-a-default-value"></a>Set a Default Value

When applicable, set the most common choice as the default value.

### <a id="do-not-use-as-a-menu"></a>Do Not Use as a Menu

Select is an input field component, not a generic menu component. Use [Menu Bar](https://vaadin.com/docs/v14/ds/components/menu-bar.md) to create overlays for actions.

## <a id="related-components"></a>Related Components

| Component                                                                 | Usage recommendations                                                                                            |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| [Radio Button](https://vaadin.com/docs/v14/ds/components/radio-button.md) | Better accessibility than Select, as all options are visible without user interaction.                           |
| [Combo Box](https://vaadin.com/docs/v14/ds/components/combo-box.md)       | Filterable list of options. Appropriate for large sets of options. Supports lazy loading entry of custom values. |
| [List Box](https://vaadin.com/docs/v14/ds/components/list-box.md)         | Scrollable inline list of options. Supports single and multi-select.                                             |
| [Menu Bar](https://vaadin.com/docs/v14/ds/components/menu-bar.md)         | Overlay menus for items that trigger actions.                                                                    |

`86761DF6-1C96-47B2-8311-E777A11405C6`