> Markdown version of [List Box](https://vaadin.com/docs/v14/ds/components/list-box). Section index: [llms.txt](https://vaadin.com/docs/v14/ds/llms.txt)

# List Box

List Box allows the user to select one or more values from a scrollable list of items.

`ListBoxBasic.java`

```java
MultiSelectListBox<String> listBox = new MultiSelectListBox<>();
listBox.setItems(SHOW_ASSIGNEE, SHOW_DUE_DATE, SHOW_STATUS);
listBox.select(SHOW_ASSIGNEE, SHOW_STATUS);
```

Although functionally similar to [Checkbox Group](https://vaadin.com/docs/v14/ds/components/checkbox.md) and [Radio Button Group](https://vaadin.com/docs/v14/ds/components/radio-button.md), List Box is designed to be used as a lightweight scrollable selection list rather than a form input field.

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

You can use dividers to group related items. Use them sparingly to avoid creating unnecessary visual clutter.

`ListBoxSeparators.java`

```java
listBox.setItems(
    SHOW_ASSIGNEE, SHOW_DUE_DATE, SHOW_STATUS, SHOW_THUMBNAIL, SHOW_PREVIEW
);
listBox.addComponents(SHOW_STATUS, new Hr());
```

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

Disable items to show that they are unavailable for selection at the moment.

`ListBoxDisabledItems.java`

```java
ListBox<Status> listBox = new ListBox<>();
listBox.setItems(inProgress, done, cancelled);
listBox.setItemEnabledProvider(status -> status.getCount() > 0);
```

> **Note: Accessibility**
>
> Some assistive technologies do not announce disabled items.

## <a id="selection"></a>Selection

List Box supports both single and multiple selection. The former allows the user to select only one item while the latter enables multiple items to be selected.

### <a id="single"></a>Single

`ListBoxSingleSelection.java`

```java
ListBox<String> listBox = new ListBox<>();
listBox.setItems(IN_PROGRESS, DONE, CANCELLED);
listBox.setValue(IN_PROGRESS);
```

### <a id="multi"></a>Multi

`ListBoxMultiSelection.java`

```java
MultiSelectListBox<Person> listBox = new MultiSelectListBox<>();
listBox.setItems(items);
listBox.select(items.get(0), items.get(3));
```

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

<!-- vale Vaadin.TooWordy = NO -->

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

<!-- vale Vaadin.TooWordy = YES -->

`ListBoxCustomItemPresentation.java`

```java
listBox.setRenderer(new ComponentRenderer<>(person -> {
    HorizontalLayout row = new HorizontalLayout();
    row.setAlignItems(FlexComponent.Alignment.CENTER);

    Avatar avatar = new Avatar();
    avatar.setName(person.getFullName());
    avatar.setImage(person.getPictureUrl());

    Span name = new Span(person.getFullName());
    Span profession = new Span(person.getProfession());
    profession.getStyle()
        .set("color", "var(--lumo-secondary-text-color)")
        .set("font-size", "var(--lumo-font-size-s)");

    VerticalLayout column = new VerticalLayout(name, profession);
    column.setPadding(false);
    column.setSpacing(false);

    row.add(avatar, column);
    row.getStyle().set("line-height", "var(--lumo-line-height-m)");
    return row;
}));
```

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

List Box is not designed to be used as an input field in forms, and lacks features like label, helper, and validation errors. See related components below for better options for use in forms. List Box is best suited to be used as a lightweight, scrollable, single-column list for single or multi-selection of items.

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

| Component                                                                       | Usage recommendations                                                                                                              |
| ------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [Checkbox Group](https://vaadin.com/docs/v14/ds/components/checkbox.md)         | Input field for selecting multiple options from a list.                                                                            |
| [Combo Box](https://vaadin.com/docs/v14/ds/components/combo-box.md)             | Select a value from a filterable overlay. Appropriate for large sets of options. Supports lazy loading and entry of custom values. |
| [Radio Button Group](https://vaadin.com/docs/v14/ds/components/radio-button.md) | Select a single option from a list. Optimal accessibility, as all options are visible without any user action.                     |
| [Select](https://vaadin.com/docs/v14/ds/components/select.md)                   | Input field for selecting a value from a overlay. More compact than a Radio Button Group.                                          |
| [Grid](https://vaadin.com/docs/v14/ds/components/grid.md)                       | A more advanced list component for cases where multiple columns, filtering or lazy loading is required.                            |

`73F9ECAA-AF05-4C79-B015-D7C1AC0F91B9`