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

# List Box

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

**Lit** — `list-box-basic.ts`

```html
<vaadin-list-box multiple .selectedValues="${[0, 2]}">
  <vaadin-item>Show assignee</vaadin-item>
  <vaadin-item>Show due date</vaadin-item>
  <vaadin-item>Show status</vaadin-item>
</vaadin-list-box>
```

**Flow** — `ListBoxBasic.java`

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

**React** — `list-box-basic.tsx`

```tsx
<ListBox multiple selectedValues={[0, 2]}>
  <Item>Show assignee</Item>
  <Item>Show due date</Item>
  <Item>Show status</Item>
</ListBox>
```

Although functionally similar to [Checkbox Group](https://vaadin.com/docs/latest/components/checkbox.md) and [Radio Button Group](https://vaadin.com/docs/latest/components/radio-button.md), List Box is designed to be used as a lightweight scrollable selection list, rather than as 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.

**Lit** — `list-box-separators.ts`

```html
<vaadin-list-box multiple .selectedValues="${[0, 2, 3]}">
  <vaadin-item>Show assignee</vaadin-item>
  <vaadin-item>Show due date</vaadin-item>
  <vaadin-item>Show status</vaadin-item>
  <hr />
  <vaadin-item>Show thumbnail</vaadin-item>
  <vaadin-item>Show preview</vaadin-item>
</vaadin-list-box>
```

**Flow** — `ListBoxSeparators.java`

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

**React** — `list-box-separators.tsx`

```tsx
<ListBox multiple selectedValues={[0, 2, 3]}>
  <Item>Show assignee</Item>
  <Item>Show due date</Item>
  <Item>Show status</Item>
  <hr />
  <Item>Show thumbnail</Item>
  <Item>Show preview</Item>
</ListBox>
```

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

Disable items to show that they are currently unavailable for selection.

**Lit** — `list-box-disabled-items.ts`

```html
<vaadin-list-box selected="0">
  <vaadin-item>In progress (2)</vaadin-item>
  <vaadin-item>Done (4)</vaadin-item>
  <vaadin-item disabled>Cancelled (0)</vaadin-item>
</vaadin-list-box>
```

**Flow** — `ListBoxDisabledItems.java`

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

**React** — `list-box-disabled-items.tsx`

```tsx
<ListBox selected={0}>
  <Item>In progress (2)</Item>
  <Item>Done (4)</Item>
  <Item disabled>Cancelled (0)</Item>
</ListBox>
```

> **Note: Accessibility**
>
> Some assistive technologies don’t announce disabled items.

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

List Box supports both single and multiple selection. Single selection allows the user to select only one item, whereas multiple selection enables more than one item to be selected.

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

**Lit** — `list-box-single-selection.ts`

```html
<vaadin-list-box selected="0">
  <vaadin-item>In progress</vaadin-item>
  <vaadin-item>Done</vaadin-item>
  <vaadin-item>Cancelled</vaadin-item>
</vaadin-list-box>
```

**Flow** — `ListBoxSingleSelection.java`

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

**React** — `list-box-single-selection.tsx`

```tsx
<ListBox selected={0}>
  <Item>In progress</Item>
  <Item>Done</Item>
  <Item>Cancelled</Item>
</ListBox>
```

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

**Lit** — `list-box-multi-selection.ts`

```html
<vaadin-list-box multiple .selectedValues="${[0, 3]}" style="height: 200px">
  ${this.items.map(
    (person) => html`<vaadin-item>${person.firstName} ${person.lastName}</vaadin-item> `
  )}
</vaadin-list-box>
```

**Flow** — `ListBoxMultiSelection.java`

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

**React** — `list-box-multi-selection.tsx`

```tsx
<ListBox
  multiple
  selectedValues={selectedValues.value}
  onSelectedValuesChanged={(e) => {
    selectedValues.value = e.detail.value;
  }}
  style={{ height: '200px' }}
>
  {items.value.map((person, index) => (
    <Item key={index}>
      {person.firstName} {person.lastName}
    </Item>
  ))}
</ListBox>
```

## <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 -->

**Lit** — `list-box-custom-item-presentation.ts`

```typescript
<vaadin-list-box multiple .selectedValues="${[0, 2]}">
  ${this.items.map(
    (person) => html`
      <vaadin-item>
        <div class="person-item">
          <vaadin-avatar
            .img="${person.pictureUrl}"
            .name="${`${person.firstName} ${person.lastName}`}"
          ></vaadin-avatar>
          <span>${person.firstName} ${person.lastName}</span>
          <span>${person.profession}</span>
        </div>
      </vaadin-item>
    `
  )}
</vaadin-list-box>
```

**Flow** — `ListBoxCustomItemPresentation.java`

```java
listBox.setRenderer(new ComponentRenderer<>(person -> {
    Avatar avatar = new Avatar(person.getFullName(),
            person.getPictureUrl());
    Span name = new Span(person.getFullName());
    Span profession = new Span(person.getProfession());

    Div personItem = new Div(avatar, name, profession);
    personItem.addClassName("person-item");
    return personItem;
}));
```

**React** — `list-box-custom-item-presentation.tsx`

```tsx
<ListBox
  multiple
  selectedValues={selectedValues.value}
  onSelectedValuesChanged={(e) => {
    selectedValues.value = e.detail.value;
  }}
>
  {items.value.map((person) => (
    <Item value={String(items.value.indexOf(person))} key={items.value.indexOf(person)}>
      <div className="person-item">
        <Avatar img={person.pictureUrl} name={`${person.firstName} ${person.lastName}`} />
        <span>
          {person.firstName} {person.lastName}
        </span>
        <span>{person.profession}</span>
      </div>
    </Item>
  ))}
</ListBox>
```

`person-item.css`

```css
.person-item {
    display: grid;
    grid-template-columns: min-content auto;
    grid-template-rows: auto auto;
    grid-template-areas:
        "avatar name"
        "avatar title";
    gap: 0 var(--vaadin-gap-s);
    align-items: center;
    line-height: 1.2;

    & > :is(vaadin-avatar, img) {
        grid-area: avatar;
    }

    & > span:first-of-type {
        grid-area: name;
    }

    & > span:last-of-type {
        grid-area: title;
        font-size: 0.875rem;
        font-weight: 400;
        color: var(--vaadin-text-color-secondary);
    }
}
```

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

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

The List Box API supports using a `DataProvider` as its data source. However, List Box does not support lazy loading: all items are fetched from the data provider at once. For large data sets, consider using Virtual List or Grid for displaying items, or Combo Box or Multi-Select Combo Box when selection is required.

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

| Component                                                                                     | Usage recommendations                                                                                                              |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [Checkbox Group](https://vaadin.com/docs/latest/components/checkbox.md)                       | Input field for selecting multiple options from a list.                                                                            |
| [Combo Box](https://vaadin.com/docs/latest/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. |
| [Multi-Select Combo Box](https://vaadin.com/docs/latest/components/multi-select-combo-box.md) | Select multiple values from a filterable overlay. Appropriate for large sets of options and supports lazy loading.                 |
| [Radio Button Group](https://vaadin.com/docs/latest/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/latest/components/select.md)                                 | Input field for selecting a value from a overlay. More compact than a Radio Button Group.                                          |
| [Grid](https://vaadin.com/docs/latest/components/grid.md)                                     | A more advanced list component for cases where multiple columns, filtering or lazy loading is required.                            |
| [Virtual List](https://vaadin.com/docs/latest/components/virtual-list.md)                     | Display a large, scrollable list of items with lazy loading and custom item rendering.                                             |

`30C8BEB8-5F4C-4CF7-B292-AE67C4151CBC`