Listbox

Listboxes display a persistent list of options from which users select one or more.

Option 1

Option 2

Option 3

Overview

A listbox shows all of its options at once and lets users pick one or more of them. Unlike a select, whose options appear in a popup, a listbox stays open in the page, so users can scan, compare, and change a selection without extra clicks. It suits settings, filters, and pick lists where the choices are few enough to display together.

Listboxes are form controls, so they are often placed inside a form or card, and can be paired with another listbox to move options between lists.

Usage

forge-listbox contains forge-option and forge-option-group children. Use value to read or set the selection, multiple to allow more than one option, allowDeselect to let users clear a single selection, and dense, disabled, and readonly to change presentation and interactivity. It is form-associated, so name and required work with native forms, and it dispatches change and input events when the selection changes. Use a listbox when the options should always be visible; for a compact control with a popup, use a select instead.

Rules

Use a listbox when users benefit from seeing every option at once.

Keep option labels short and easy to scan.

Set multiple when users can pick more than one option.

Group related options with forge-option-group and a label slot.

Set a name so the selection is submitted with the surrounding form.

Don't

Don't use a listbox for long lists — use a select or autocomplete instead.

Don't use a listbox for a binary choice — use a checkbox or switch.

Don't rely on icons alone to distinguish options.

Basic usage

Each forge-option has a value, and the listbox’s value reflects the selected option.

A listbox with three options.

Multiple

Set multiple to let users select more than one option. value becomes an array.

A listbox that allows multiple selections.

Dense

Set dense to reduce the height of each option and fit more of them in the same space.

A listbox with compact options.

With option groups

Wrap related options in forge-option-group, and label each group with an element in its label slot.

A listbox whose options are organized into labeled groups.

With icons

Place a forge-icon in an option’s start slot to reinforce its meaning alongside the label.

A listbox with a leading icon on each option.

Reorderable

Set reorderable so users can drag options to change their order. Update the DOM in a forge-listbox-drop handler to apply the new order.

A listbox whose options can be reordered.

Drag and drop

Link two listboxes by setting each one’s drag-link and drop-link to the other’s id, so users can move options between them. Handle forge-listbox-drag-out and forge-listbox-drop to move the option in the DOM.

Two linked listboxes that exchange options by dragging.

Disabled

Set disabled on a forge-option to prevent that option from being selected, or on the listbox to disable all of its options.

A listbox with one disabled option.

Listboxes allow users to select one or more options from a list.

import "@tylertech/forge/listbox";

Properties

Property	Attribute	Type	Default	Description
`value`	`value`	`string \| string[]`	`''`	The selected value(s).
`name`	`name`	`string`	`''`	The name of the listbox, submitted with form data.
`required`	`required`	`boolean`	`false`	Whether a selection is required for the listbox to be considered valid.
`readonly`	`readonly`	`boolean`	`false`	Whether the listbox is readonly. When readonly, the listbox can still be focused and its value is still submitted with a form, but the user cannot change the selection.
`multiple`	`multiple`	`boolean`	`false`	Whether multiple options can be selected.
`reorderable`	`reorderable`	`boolean`	`false`	Whether options can be reordered within the listbox via drag and drop.
`dropLink`	`drop-link`	`string`	`''`	A space-separated list of the ids of listboxes that are allowed to drop options into this listbox. Works together with `dropLink` on the linked listbox - a drop is only allowed when both listboxes mutually opt in to the link.
`dropLinkElements`	—	`ListboxComponent[]`	`[]`	An array of listbox elements that are allowed to drop options into this listbox. Takes precedence over `dropLink` when set explicitly.
`dragLink`	`drag-link`	`string`	`''`	A space-separated list of the ids of listboxes that options in this listbox are allowed to be dragged out to. Works together with `dropLink` on the linked listbox - a drop is only allowed when both listboxes mutually opt in to the link.
`dragLinkElements`	—	`ListboxComponent[]`	`[]`	An array of listbox elements that options in this listbox are allowed to be dragged out to. Takes precedence over `dragLink` when set explicitly.
`disabled`	`disabled`	`boolean`	`false`	Whether the listbox is disabled.
`allowDeselect`	`allow-deselect`	`boolean`	`false`	Whether the listbox allows deselecting a selection to be cleared when `multiple` is false.
`dense`	`dense`	`boolean`	`false`	Whether the listbox's options use a dense layout.

Events

Name	Type	Description
`forge-listbox-drop`	`CustomEvent<IListboxDropData>`	Dispatches when an option is dropped into the listbox. Contains the dropped option element, the index where it was dropped, and the source listbox element.
`input`	`Event`	Dispatches when the selection changes.
`change`	`Event`	Dispatches when the selection changes.
`forge-listbox-drag-out`	`CustomEvent<OptionComponent>`	Dispatches when an option is dragged out of the listbox. Contains the dragged option element.

Slots

Name	Description
`(default)`	The listbox options and option groups.

CSS Parts

Name	Description
`::part(root)`	The root element.

CSS Custom Properties

Name	Description
`--forge-listbox-divider-margin`	The margin around a slotted divider.
`--forge-listbox-group-margin`	The spacing between slotted option groups.

Methods

Name	Returns	Description
`shiftSelectedOptionUp()`	`void`	Shifts the selected option up within the listbox, swapping it with the previous sibling if possible.
`shiftSelectedOptionDown()`	`void`	Shifts the selected option down within the listbox, swapping it with the next sibling if possible.

Listbox and option roles

forge-listbox has the listbox role with a vertical orientation, and each forge-option has the option role. The listbox sets aria-multiselectable when multiple is set, aria-disabled when disabled is set, and aria-readonly when readonly is set.

Keyboard interaction

A listbox has a single tab stop. Tab moves focus into the list, and the arrow keys move between options. Selection follows the keys below.

Key	Action
Arrow up / Arrow down	Moves focus to the previous or next option.
Home / End	Moves focus to the first or last option.
Enter / Space	Selects the focused option.
Shift + Arrow up / down	Moves focus and adds the option to the selection (`multiple` only).
Shift + Space	Selects the range from the last selected option to the focused option (`multiple` only).
Ctrl/Cmd + Shift + Home / End	Selects from the focused option to the first or last option (`multiple` only).
Ctrl/Cmd + A	Selects every enabled option (`multiple` only).
Printable characters	Moves focus to the next option whose label starts with the typed text.

Labeling

Give the listbox an accessible name with aria-label, or point aria-labelledby at a visible heading or label. Without one, screen readers announce only “listbox”. Give forge-option-group a visible label through its label slot so groups are announced by name.

Disabled options are skipped by selection but remain perceivable. Don’t use color or an icon alone to convey an option’s meaning; include it in the label.

Drag and drop

Dragging requires a pointer. Provide another way to reorder or move options for keyboard users, such as buttons that dispatch the listbox’s --shift-up and --shift-down commands.