List Box
List Box allows the user to select one or more values from a scrollable list of items.
new tab
<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>
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.
new tab
<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>
Disabled Items
Disable items to show that they are currently unavailable for selection.
new tab
<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>
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
new tab
<vaadin-list-box selected="0">
<vaadin-item>In progress</vaadin-item>
<vaadin-item>Done</vaadin-item>
<vaadin-item>Cancelled</vaadin-item>
</vaadin-list-box>
Multi
new tab
<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>
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.
new tab
<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>
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.
Related Components
Component | Usage recommendations |
---|---|
Input field for selecting multiple options from a list. | |
Select a value from a filterable overlay. Appropriate for large sets of options. Supports lazy loading and entry of custom values. | |
Select a single option from a list. Optimal accessibility, as all options are visible without any user action. | |
Input field for selecting a value from a overlay. More compact than a Radio Button Group. | |
A more advanced list component for cases where multiple columns, filtering or lazy loading is required. |
30C8BEB8-5F4C-4CF7-B292-AE67C4151CBC