# Bootstrap 6 List Box
> A keyboard-driven list of values built on the ARIA listbox pattern: single, multiple or no selection, a select-all header, sections, descriptions, links, an empty state and an aria-activedescendant mode that keeps the focus in your own input.
## Overview
_Added in 6.0.0._
A list box presents a set of values and lets the user pick from them. `.list-box` is the container and the plugin's root; the list of choices lives in a `.list-box-options` child, which is what carries `role="listbox"` and the accessible name. The plugin owns the roles, the selection state and the keyboard: it writes `role="option"` on every `.list-box-option`, keeps `aria-selected` in step with the selection, moves a roving `tabindex` as the highlight moves, and scrolls the highlighted option into view. Before the highlight has moved that `tabindex` sits on the first navigable entry, which is a selectable section label when one comes first, so Tab enters the list where the arrows would.
```html
Lettuce
Tomato
Onion
Cheese
```
Every option carries its value in `data-coreui-value`; an option without one is worth its text. Values are what the methods take and what the events report, so an option can be hidden, moved or re-rendered without disturbing the selection.
The options element is not a scroll container — a list with no height grows with its content. Cap it where you want one: `
`. The plugin keeps the highlighted option in view either way, with `scrollIntoView({ block: 'nearest' })`.
### When to use
| Component | Use it for |
| --- | --- |
| List box | Choosing a value — the choice stays on screen and is reported back to you. |
| [Menu](https://coreui.io/bootstrap/docs/components/menu/) | Running an action — the surface opens, something happens, it closes. |
| [List group](https://coreui.io/bootstrap/docs/components/list-group/) | Displaying content — a list of things to read, not to pick from. |
A list box is also the primitive the picker components are built from, so its markup and classes carry over to them.
## Selection
`selectionMode` decides what a click and Space do. In `single` (the default) one option is selected at a time and picking another replaces it.
```html
Lettuce
Tomato
Onion
```
In `multiple` a click toggles one option, Shift extends the selection from the last one, Ctrl (Cmd on macOS) adds one without clearing the rest, and Ctrl + A takes everything. `aria-multiselectable` is written for you.
```html
Lettuce
Tomato
Onion
Cheese
```
With `none` nothing is ever selected and no `aria-selected` is written; activating an option fires `action.coreui.list-box` instead, which turns the list into a keyboard-navigable list of commands.
```html
Copy
Rename
Delete
```
### Select all
A `.list-box-select-all` button marked `data-coreui-select-all`, anywhere in the container, switches the whole list. It is not an option — it never takes an `option` role, never appears in `getSelectedValues()` and is reached with Tab rather than with the arrows. The plugin keeps its `aria-pressed` in step with the list (`true`, `false` or `mixed`) and points its `aria-controls` at the options element; clicking it selects everything or, when everything visible is already selected, drops that same set. Its own text is its name, so it needs no label.
`.list-box-header` is the strip above the options it usually sits in: a plain `
`, a flex row that takes whatever content belongs there — a title (`.list-box-title`), a counter (`.list-box-subtitle`), a button of your own — next to or instead of the switch.
```html
Lettuce
Tomato
Onion
Cheese
```
"Everything" means the options the user can actually reach — `selectAll()`, Ctrl + A and the button take the visible, enabled options and leave anything `hidden` or `disabled` alone, and the same set decides which values a second click drops, so a value the filter hid stays selected. The button reads as pressed once that set is selected, or once the values of it you selected fill what `selectionLimit` leaves after the values selected outside it, hidden by the filter or missing from the items; a click then drops the visible values. Pass an explicit list to `selectAll(values)` to select beyond the filter, and call `clear()` to empty the selection whatever the filter shows.
### Selection limit
`selectionLimit` caps how many options can be selected at once in `multiple` mode. Once the cap is reached the plugin refuses any further selection — from a click, Space, a range, Ctrl + A, the select-all button or the API — and fires `selectionLimit.coreui.list-box` once per interaction, with `event.limit` and `event.value` (the first refused value). Options are never disabled and deselecting always works, so the user picks what to give up rather than being locked out. A selected value the list does not show, because the filter hid it or an external answer does not carry it, still counts: the user gives it up once the list shows it again, and `clear()` drops it at any time. A range, Ctrl + A and the select-all button take options in document order until the cap is reached.
```html
Lettuce
Tomato
Onion
Cheese
```
With a limit, the select-all button counts as pressed once the visible, enabled options it selected fill the room the limit leaves after the values selected outside them, `mixed` while some are selected below that and not pressed while none is; clicking it while pressed drops the visible, enabled options it had selected.
## Items from configuration
Instead of writing every option by hand, hand the plugin an `items` array and it renders the list — the same markup the sections above document, so every class, role and attribute is where you would have put it. An item is `{ value, label, description, disabled, selected }`; an entry with its own `items` array is a section, and its `label` becomes the `.list-box-section-label` the group is named by.
Labels are text: they land as `textContent`, so a label carrying markup shows up as characters. Set `html: true` to have them parsed instead — the result runs through the sanitizer first, and `sanitize`, `sanitizeFn` and `allowList` steer it the same way they do everywhere else.
Leave an empty `.list-box-options` in the markup so you can name it; the plugin appends one when it is missing, but then the list has no accessible name. Options already written inside it are replaced — `items` owns the list from the moment it is set.
```html
```
```js
const element = document.getElementById('listBoxItems')
coreui.ListBox.getOrCreateInstance(element, {
items: [
{
label: 'Veggies',
items: [
{ value: 'lettuce', label: 'Lettuce' },
{ value: 'tomato', label: 'Tomato', description: 'Ripe' },
{ value: 'onion', label: 'Onion', disabled: true }
]
},
{
label: 'Protein',
items: [
{ value: 'ham', label: 'Ham', selected: true },
{ value: 'tuna', label: 'Tuna', description: 'Line caught' }
]
}
]
})
```
## Remote data
`setItems(items)` rebuilds the list at any time and leaves the selection alone. A value the new items no longer carry stays selected, counts against `selectionLimit`, and comes off with `deselect()`, `clear()` or the next pick in single mode. An item marked `selected` joins a multiple selection up to `selectionLimit` and fires `change.coreui.list-box` once, and the first one the limit leaves out fires `selectionLimit.coreui.list-box`; in single mode it is taken only while nothing is selected. Otherwise nothing fires, so re-fetching the same page or answering a search costs the user nothing. `getItems()` hands back the normalized array.
A list that depends on another field, such as the cities of the chosen country, sets `resetSelectionOnItemsChange: true`. Whenever the values of the new items differ from the ones before, `setItems` then starts from an empty selection and takes the items marked `selected`, so the city of the previous country never travels on with the next one. The same values again, in any order, keep the selection. Leave it off with `search: 'external'`, where every answer brings different values and would drop the pick.
`loading` covers the wait: it writes `aria-busy="true"` on the options element, shows a row with a spinner and the `loadingLabel` text below the options, announces that text to screen readers when the wait starts or the list shows up waiting, and holds the empty state back, so "No results" never flashes before the answer arrives. The options stay as they are and can still be picked, so a choice from the shown results counts. `setLoading(value)` turns it on and off around the request.
```html
No users
```
```js
const element = document.getElementById('listBoxRemote')
const listBox = coreui.ListBox.getOrCreateInstance(element, { loading: true })
const loadUsers = async () => {
listBox.setLoading(true)
try {
const response = await fetch('https://apitest.coreui.io/demos/users?limit=10')
const { records } = await response.json()
listBox.setItems(records.map(user => ({
value: user.id,
label: `${user.first_name} ${user.last_name}`,
description: user.email
})))
} catch (error) {
console.error('Error fetching users:', error)
listBox.setItems([])
} finally {
listBox.setLoading(false)
}
}
loadUsers()
document.getElementById('listBoxReload').addEventListener('click', loadUsers)
```
## Search
`search` puts a search field between the header and the options. It hides what does not match, and because a hidden option leaves the navigation, everything downstream follows: the arrows skip it, the select-all button takes only what is left on screen, and the empty state appears when nothing matches. The selection itself survives filtering — filter something out and it stays selected.
The field is a `.form-control.list-box-search` carrying `data-coreui-list-box-search`, built for you unless the markup already has an input with that attribute — put one there and it is used as it is, wherever you placed it. `searchPlaceholder` fills the placeholder and `ariaSearchLabel` the accessible name; `--cui-list-box-search-margin` sets how it sits between the two.
```html
Apple
Apricot
Banana
Blueberry
Cherry
Cranberry
No fruit matches
```
### External search
`search: 'external'` builds the same field and filters nothing. Every keystroke fires `search.coreui.list-box` with the `query`, and you answer with `setItems()` — the list shows what you hand it, so the query is yours to interpret. What the user picked stays picked while the results change, also when the next answer does not carry it. Debounce the request and put `setLoading()` around it, so the loading row shows while the answer is on its way and the options already shown can still be picked.
```html
No users
```
```js
const element = document.getElementById('listBoxExternalSearch')
const listBox = coreui.ListBox.getOrCreateInstance(element, {
loading: true,
search: 'external',
searchPlaceholder: 'Search users'
})
const loadUsers = async (query = '') => {
listBox.setLoading(true)
try {
const response = await fetch(`https://apitest.coreui.io/demos/users?first_name=${query}&limit=10`)
const { records } = await response.json()
listBox.setItems(records.map(user => ({
value: String(user.id),
label: `${user.first_name} ${user.last_name}`,
description: user.email
})))
} catch (error) {
console.error('Error fetching users:', error)
listBox.setItems([])
} finally {
listBox.setLoading(false)
}
}
let debounceTimer = null
element.addEventListener('search.coreui.list-box', event => {
clearTimeout(debounceTimer)
debounceTimer = setTimeout(() => loadUsers(event.query), 200)
})
loadUsers()
```
## Filtering from your own field
The built-in search field is not the only way in. `filter(query)` runs the same text filter from wherever you like — a field elsewhere on the page, a chip bar, a URL parameter — and everything downstream follows it: the arrows skip what is hidden, a section left without a match is hidden with its label, the select-all button takes only what is on screen, and the empty state appears when nothing is left. `filter(null)` clears it and shows every option again. The selection is untouched throughout: filter a selected value out and it stays selected, it just leaves the list.
```html
Apple
Apricot
Banana
Cherry
No fruit matches
```
```js
const field = document.getElementById('listBoxOwnField')
const element = document.getElementById('listBoxOwnFieldList')
const listBox = coreui.ListBox.getOrCreateInstance(element, {
indicator: 'checkbox',
selectionMode: 'multiple'
})
field.addEventListener('input', () => {
listBox.filter(field.value)
})
document.getElementById('listBoxOwnFieldReset').addEventListener('click', () => {
field.value = ''
listBox.filter(null)
})
```
## Checkboxes
Nothing marks the selection on its own — `aria-selected` and the `.selected` background carry it. Set `indicator: 'checkbox'` and the plugin puts a checkbox in front of every option and keeps it in step with the selection.
```html
Lettuce
Tomato
Onion
Cheese
```
The checkbox is a decorative ``, not an input, so it never takes the focus and never has a state of its own — the `.selected` and `.indeterminate` classes drive it. The select-all button gets the same indicator, its own `mixed` state included, and stays a button: focusable, operable, and named by its text.
## Counter
`counter` puts a `{selected}/{available} selected` readout in the header — the last child of `.list-box-header`, a `.list-box-subtitle` carrying `data-coreui-list-box-counter`. There is no header in the markup? One is created. Bring your own element with that attribute and the plugin writes into it wherever you put it.
Both numbers read the same set — the options that are visible and enabled, which is also what the select-all button works on — so the counter always describes what is on screen. Filter the list and the denominator drops with it, and a selected value the filter hid drops out of the numerator too: it stays selected, it just stops being counted, so `2/4` can become `1/1` without anything being deselected. A disabled option never appears in either number. `selectedLabel` builds the whole text, so a translated list reads in its own language and its own word order: pass a function of `(count, total)`, or a string in which `{count}` and `{total}` are replaced.
```html
Apple
Apricot
Banana
Blueberry
Cherry
No fruit matches
```
## Sections
Group options in a `.list-box-section` and name it with a `.list-box-section-label`. The plugin adds `role="group"`; point `aria-labelledby` at the label so the group is announced with its name.
```html
Veggies
Lettuce
Tomato
Protein
Ham
Tuna
```
### Selectable sections
`sectionsSelectable` turns every section label into a tri-state button that toggles its own section: `aria-pressed` reads `false`, `mixed` or `true`, and with `indicator: 'checkbox'` the label carries the same checkbox as the options. It works in `multiple` mode and covers the section's visible, enabled options only, so a filtered list toggles what is on screen; `selectionLimit` still applies, with the same reading as the select-all button. A label whose section has no such option carries `aria-disabled="true"`, leaves the arrow-key order and shows the state of the section's disabled options. The labels join the arrow-key order in document position, so ↓ walks label, options, next label.
```html
Veggies
Lettuce
Tomato
Protein
Ham
Tuna
```
## Descriptions
An option can carry a second line. Wrap the name in `.list-box-option-label` and the explanation in `.list-box-option-description` — typeahead then matches the label alone, so typing skips the description text.
```html
FreeOne project, community support
TeamUnlimited projects, shared billing
```
Descriptions and the checkbox indicator work together: the indicator stays centred against the whole option and both lines of the text start past it, so a two-line option keeps the same left column as the select-all button above.
```html
```
## Disabled items
`.disabled` (with `aria-disabled="true"` for assistive technology) keeps the user out: it takes an option out of the keyboard order and out of every selection the user makes, the arrows, a click, a section label, a range and select all. Your code is not kept out of the values it sets, as with a native `