ListBox

A headless selectable list primitive with keyboard navigation, single and multiple selection, and controlled or uncontrolled state.

Selected: banana

Anatomy

ListBox.Root is the container that owns selection state and keyboard interactions; each option is a ListBox.Item with a unique id.

<script>
	import { ListBox } from '@human-kit/ui';
</script>

<ListBox.Root aria-label="Options">
	<ListBox.Item id="1">Option 1</ListBox.Item>
</ListBox.Root>

Multiple selection

Set selectionMode="multiple" to allow more than one selected item. selectionBehavior controls what happens on repeat selection: "toggle" (default) deselects, "replace" always replaces the selection. Press Ctrl+A to select everything.

2 selected

Disabled items

Use disabled on ListBox.Item (or disabledKeys on the root) to make individual options non-interactive. Disabled items are skipped by keyboard navigation and styled through data-disabled.

Usage guidelines

Use ListBox.Root as the container for selection state and keyboard interactions, and render each option with ListBox.Item.
Use value / onChange for controlled selection and defaultValue for uncontrolled initial selection. Values are sets of item ids.
Use selectionBehavior="replace" when picking an option should always replace the current selection instead of toggling it.
Use disabled on individual items or disabledKeys on the root to make options non-selectable.
Provide aria-label on the root when there is no visible label.

Accessibility

ListBox.Root renders role="listbox" with aria-multiselectable in multiple mode; each ListBox.Item renders role="option" with aria-selected.
Arrow keys move focus between items; Home / End jump to the first or last item.
Space / Enter select the focused item; Ctrl+A selects all items in multiple mode.
Every visual state (data-selected, data-focused, data-focus-visible, data-hovered, data-pressed, data-disabled) is exposed as a data attribute for styling.

API reference

Root

The listbox container. Manages option registration, selection state, focus, and keyboard navigation.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description

data-empty-placeholder Identifies the placeholder option rendered when the list has no items.

data-focus-within Present while focus is inside the listbox.

data-listbox-spacer Identifies the element holding the full scroll height while virtualised.

data-listbox-window Identifies the element holding the rows currently rendered by the virtualiser.

Item

A selectable option. Registers itself with the root and exposes selected, focused, hovered, pressed, and disabled states through data attributes.

Prop Type Default

* required. Native HTML attributes of the underlying element are also accepted.

Data attribute Description

data-disabled Present when the item is disabled.

data-focus-visible Present while focus should be visibly indicated (keyboard modality).

data-focused Present while the item is focused.

data-hovered Present while the pointer is over the item.

data-item-id The item id used for selection.

data-item-id-type Whether the item id is a "string" or a "number".

data-navigation-item Identifies the item as a keyboard-navigation target.

data-pressed Present while the item is actively pressed.

data-selected Present while the item is selected.