List Box

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

Usage
Styling

Dividers
Disabled Items
Selection
Custom Item Presentation
Best Practices
Related Components

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

Source code

ListBoxBasic.javapackage com.vaadin.demo.component.listbox;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.listbox.MultiSelectListBox;
import com.vaadin.flow.router.Route;

@Route("list-box-basic")
public class ListBoxBasic extends Div {

    private final String SHOW_ASSIGNEE = "Show assignee";
    private final String SHOW_DUE_DATE = "Show due date";
    private final String SHOW_STATUS = "Show status";

    public ListBoxBasic() {
        // tag::snippet[]
        MultiSelectListBox<String> listBox = new MultiSelectListBox<>();
        listBox.setItems(SHOW_ASSIGNEE, SHOW_DUE_DATE, SHOW_STATUS);
        listBox.select(SHOW_ASSIGNEE, SHOW_STATUS);
        // end::snippet[]
        add(listBox);
    }

}
list-box-basic.tsximport React from 'react';
import { Item } from '@vaadin/react-components/Item.js';
import { ListBox } from '@vaadin/react-components/ListBox.js';

function Example() {
  return (
    // tag::snippet[]
    <ListBox multiple selectedValues={[0, 2]}>
      <Item>Show assignee</Item>
      <Item>Show due date</Item>
      <Item>Show status</Item>
    </ListBox>
    // end::snippet[]
  );
}

list-box-basic.tsimport '@vaadin/item';
import '@vaadin/list-box';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('list-box-basic')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <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>
      <!-- end::snippet[] -->
    `;
  }
}

Although functionally similar to Checkbox Group and Radio Button Group, List Box is designed to be used as a lightweight scrollable selection list, rather than as a form input field.

Dividers

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

Open in a
new tab

Source code

ListBoxSeparators.javapackage com.vaadin.demo.component.listbox;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Hr;
import com.vaadin.flow.component.listbox.MultiSelectListBox;
import com.vaadin.flow.router.Route;

@Route("list-box-separators")
public class ListBoxSeparators extends Div {

    private final String SHOW_ASSIGNEE = "Show assignee";
    private final String SHOW_DUE_DATE = "Show due date";
    private final String SHOW_STATUS = "Show status";
    private final String SHOW_THUMBNAIL = "Show thumbnail";
    private final String SHOW_PREVIEW = "Show preview";

    public ListBoxSeparators() {
        MultiSelectListBox<String> listBox = new MultiSelectListBox<>();
        // tag::snippet[]
        listBox.setItems(SHOW_ASSIGNEE, SHOW_DUE_DATE, SHOW_STATUS,
                SHOW_THUMBNAIL, SHOW_PREVIEW);
        listBox.addComponents(SHOW_STATUS, new Hr());
        // end::snippet[]
        listBox.select(SHOW_ASSIGNEE, SHOW_STATUS, SHOW_THUMBNAIL);
        add(listBox);
    }

}
list-box-separators.tsximport React from 'react';
import { Item } from '@vaadin/react-components/Item.js';
import { ListBox } from '@vaadin/react-components/ListBox.js';

function Example() {
  return (
    // tag::snippet[]
    <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>
    // end::snippet[]
  );
}

list-box-separators.tsimport '@vaadin/item';
import '@vaadin/list-box';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('list-box-separators')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <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>
      <!-- end::snippet[] -->
    `;
  }
}

Disabled Items

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

Open in a
new tab

Source code

ListBoxDisabledItems.javapackage com.vaadin.demo.component.listbox;

import com.vaadin.flow.component.Text;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.listbox.ListBox;
import com.vaadin.flow.data.renderer.ComponentRenderer;
import com.vaadin.flow.router.Route;

@Route("list-box-disabled-items")
public class ListBoxDisabledItems extends Div {

    private class Status {

        private String name;
        private int count;

        Status(String name, int count) {
            this.name = name;
            this.count = count;
        }

        public String getDisplayName() {
            return this.name + " (" + this.count + ")";
        }

        public String getName() {
            return name;
        }

        public int getCount() {
            return count;
        }
    }

    private Status inProgress = new Status("In progress", 2);
    private Status done = new Status("Done", 4);
    private Status cancelled = new Status("Cancelled", 0);

    public ListBoxDisabledItems() {
        // tag::snippet[]
        ListBox<Status> listBox = new ListBox<>();
        listBox.setItems(inProgress, done, cancelled);
        listBox.setItemEnabledProvider(status -> status.getCount() > 0);
        // end::snippet[]
        listBox.setRenderer(new ComponentRenderer<>(
                status -> new Text(status.getDisplayName())));
        listBox.setValue(inProgress);
        add(listBox);
    }

}
list-box-disabled-items.tsximport React from 'react';
import { Item } from '@vaadin/react-components/Item.js';
import { ListBox } from '@vaadin/react-components/ListBox.js';

function Example() {
  return (
    // tag::snippet[]
    <ListBox selected={0}>
      <Item>In progress (2)</Item>
      <Item>Done (4)</Item>
      <Item disabled>Cancelled (0)</Item>
    </ListBox>
    // end::snippet[]
  );
}

list-box-disabled-items.tsimport '@vaadin/item';
import '@vaadin/list-box';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('list-box-disabled-items')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <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>
      <!-- end::snippet[] -->
    `;
  }
}

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

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.

Single

Open in a
new tab

Source code

ListBoxSingleSelection.javapackage com.vaadin.demo.component.listbox;

import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.listbox.ListBox;
import com.vaadin.flow.router.Route;

@Route("list-box-single-selection")
public class ListBoxSingleSelection extends Div {

    private final String IN_PROGRESS = "In progress";
    private final String DONE = "Done";
    private final String CANCELLED = "Cancelled";

    public ListBoxSingleSelection() {
        // tag::snippet[]
        ListBox<String> listBox = new ListBox<>();
        listBox.setItems(IN_PROGRESS, DONE, CANCELLED);
        listBox.setValue(IN_PROGRESS);
        // end::snippet[]
        add(listBox);
    }

}
list-box-single-selection.tsximport React from 'react';
import { Item } from '@vaadin/react-components/Item.js';
import { ListBox } from '@vaadin/react-components/ListBox.js';

function Example() {
  return (
    // tag::snippet[]
    <ListBox selected={0}>
      <Item>In progress</Item>
      <Item>Done</Item>
      <Item>Cancelled</Item>
    </ListBox>
    // end::snippet[]
  );
}

list-box-single-selection.tsimport '@vaadin/item';
import '@vaadin/list-box';
import { html, LitElement } from 'lit';
import { customElement } from 'lit/decorators.js';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('list-box-single-selection')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-list-box selected="0">
        <vaadin-item>In progress</vaadin-item>
        <vaadin-item>Done</vaadin-item>
        <vaadin-item>Cancelled</vaadin-item>
      </vaadin-list-box>
      <!-- end::snippet[] -->
    `;
  }
}

Multi

Open in a
new tab

Source code

ListBoxMultiSelection.javapackage com.vaadin.demo.component.listbox;

import com.vaadin.demo.domain.DataService;
import com.vaadin.demo.domain.Person;
import com.vaadin.flow.component.Text;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.listbox.MultiSelectListBox;
import com.vaadin.flow.data.renderer.ComponentRenderer;
import com.vaadin.flow.router.Route;

import java.util.List;

@Route("list-box-multi-selection")
public class ListBoxMultiSelection extends Div {

    private List<Person> items = DataService.getPeople(20);

    public ListBoxMultiSelection() {
        // tag::snippet[]
        MultiSelectListBox<Person> listBox = new MultiSelectListBox<>();
        listBox.setItems(items);
        listBox.select(items.get(0), items.get(3));
        // end::snippet[]
        listBox.setRenderer(new ComponentRenderer<>(
                person -> new Text(person.getFullName())));
        listBox.setHeight("200px");
        add(listBox);
    }

}
list-box-multi-selection.tsximport React, { useEffect } from 'react';
import { useSignal } from '@vaadin/hilla-react-signals';
import { Item } from '@vaadin/react-components/Item.js';
import { ListBox } from '@vaadin/react-components/ListBox.js';
import { getPeople } from 'Frontend/demo/domain/DataService';
import type Person from 'Frontend/generated/com/vaadin/demo/domain/Person';

function Example() {
  const items = useSignal<Person[]>([]);
  const selectedValues = useSignal<number[]>([0, 3]);

  useEffect(() => {
    getPeople({ count: 20 }).then(({ people }) => {
      items.value = people;
    });
  }, []);

  return (
    // tag::snippet[]
    <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>
    // end::snippet[]
  );
}

list-box-multi-selection.tsimport '@vaadin/item';
import '@vaadin/list-box';
import { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import { getPeople } from 'Frontend/demo/domain/DataService';
import type Person from 'Frontend/generated/com/vaadin/demo/domain/Person';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('list-box-multi-selection')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private items: Person[] = [];

  protected override async firstUpdated() {
    const { people } = await getPeople({ count: 20 });
    this.items = people;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <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>
      <!-- end::snippet[] -->
    `;
  }
}

Custom Item Presentation

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.

Open in a
new tab

Source code

ListBoxCustomItemPresentation.javapackage com.vaadin.demo.component.listbox;

import com.vaadin.demo.domain.DataService;
import com.vaadin.demo.domain.Person;
import com.vaadin.flow.component.avatar.Avatar;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Span;
import com.vaadin.flow.component.listbox.MultiSelectListBox;
import com.vaadin.flow.component.orderedlayout.FlexComponent;
import com.vaadin.flow.component.orderedlayout.HorizontalLayout;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.data.renderer.ComponentRenderer;
import com.vaadin.flow.router.Route;

import java.util.List;

@Route("list-box-custom-item-presentation")
public class ListBoxCustomItemPresentation extends Div {

    private List<Person> items = DataService.getPeople(5);

    public ListBoxCustomItemPresentation() {
        MultiSelectListBox<Person> listBox = new MultiSelectListBox<>();
        listBox.setItems(items);
        // tag::snippet[]
        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;
        }));
        // end::snippet[]
        listBox.select(items.get(0), items.get(2));
        add(listBox);
    }

}
list-box-custom-item-presentation.tsximport React, { useEffect } from 'react';
import { useSignal } from '@vaadin/hilla-react-signals';
import { Avatar } from '@vaadin/react-components/Avatar.js';
import { HorizontalLayout } from '@vaadin/react-components/HorizontalLayout.js';
import { Item } from '@vaadin/react-components/Item.js';
import { ListBox } from '@vaadin/react-components/ListBox.js';
import { VerticalLayout } from '@vaadin/react-components/VerticalLayout.js';
import { getPeople } from 'Frontend/demo/domain/DataService';
import type Person from 'Frontend/generated/com/vaadin/demo/domain/Person';

function Example() {
  const selectedValues = useSignal([0, 2]);
  const items = useSignal<Person[]>([]);
  useEffect(() => {
    getPeople({ count: 5 }).then(({ people }) => {
      items.value = people;
    });
  }, []);

  return (
    // tag::snippet[]
    <ListBox
      multiple
      selectedValues={selectedValues.value}
      onSelectedValuesChanged={(e) => {
        selectedValues.value = e.detail.value;
      }}
    >
      {items.value.map((person) => (
        <Item
          value={String(items.value.indexOf(person))}
          style={{ lineHeight: 'var(--lumo-line-height-m)' }}
          key={items.value.indexOf(person)}
        >
          <HorizontalLayout style={{ alignItems: 'center' }} theme="spacing">
            <Avatar img={person.pictureUrl} name={`${person.firstName} ${person.lastName}`} />
            <VerticalLayout>
              <span>
                {person.firstName} {person.lastName}
              </span>
              <span
                style={{
                  color: 'var(--lumo-secondary-text-color)',
                  fontSize: 'var(--lumo-font-size-s)',
                }}
              >
                {person.profession}
              </span>
            </VerticalLayout>
          </HorizontalLayout>
        </Item>
      ))}
    </ListBox>
    // end::snippet[]
  );
}

list-box-custom-item-presentation.tsimport '@vaadin/avatar';
import '@vaadin/horizontal-layout';
import '@vaadin/item';
import '@vaadin/list-box';
import '@vaadin/vaadin-lumo-styles/typography';
import '@vaadin/vertical-layout';
import { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import { getPeople } from 'Frontend/demo/domain/DataService';
import type Person from 'Frontend/generated/com/vaadin/demo/domain/Person';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('list-box-custom-item-presentation')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private items: Person[] = [];

  protected override async firstUpdated() {
    const { people } = await getPeople({ count: 5 });
    this.items = people;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-list-box multiple .selectedValues="${[0, 2]}">
        ${this.items.map(
          (person) => html`
            <vaadin-item style="line-height: var(--lumo-line-height-m);">
              <vaadin-horizontal-layout style="align-items: center;" theme="spacing">
                <vaadin-avatar
                  .img="${person.pictureUrl}"
                  .name="${`${person.firstName} ${person.lastName}`}"
                ></vaadin-avatar>
                <vaadin-vertical-layout>
                  <span> ${person.firstName} ${person.lastName} </span>
                  <span
                    style="color: var(--lumo-secondary-text-color); font-size: var(--lumo-font-size-s);"
                  >
                    ${person.profession}
                  </span>
                </vaadin-vertical-layout>
              </vaadin-horizontal-layout>
            </vaadin-item>
          `
        )}
      </vaadin-list-box>
      <!-- end::snippet[] -->
    `;
  }
}

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.

Component	Usage recommendations
Checkbox Group	Input field for selecting multiple options from a list.
Combo Box	Select a value from a filterable overlay. Appropriate for large sets of options. Supports lazy loading and entry of custom values.
Radio Button Group	Select a single option from a list. Optimal accessibility, as all options are visible without any user action.
Select	Input field for selecting a value from a overlay. More compact than a Radio Button Group.
Grid	A more advanced list component for cases where multiple columns, filtering or lazy loading is required.

Component

Usage recommendations

Checkbox Group

Input field for selecting multiple options from a list.

Combo Box

Select a value from a filterable overlay. Appropriate for large sets of options. Supports lazy loading and entry of custom values.

Radio Button Group

Select a single option from a list. Optimal accessibility, as all options are visible without any user action.

Select

Input field for selecting a value from a overlay. More compact than a Radio Button Group.

Grid

A more advanced list component for cases where multiple columns, filtering or lazy loading is required.

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

Docs

Docs

List Box

Dividers

Disabled Items

Selection

Single

Multi

Custom Item Presentation

Best Practices

Docs

Dividers

Disabled Items

Selection

Single

Multi

Custom Item Presentation

Best Practices

Related Components