Listbox

atoms

Keyboard-navigable listbox with single/multi-select, option groups, and custom rendering. Follows WAI-ARIA Listbox pattern (1.2). Used internally by Select and TimePicker.

ARIA Role: listbox

Demo

Demo for Listbox (atoms)

Keyboard-navigable listbox with single/multi-select, option groups, and custom rendering. Follows WAI-ARIA Listbox pattern (1.2). Used internally by Select and TimePicker.

Props

Prop	Type	Required	Default	Description
`options`	`ListboxOption[]`	Yes	`—`	Array of options with value, label, disabled, group, description
`mode`	`'single' \| 'multiple'`	No	`'single'`	Single or multi-select mode
`value`	`string \| string[]`	Yes	`—`	Selected value(s)
`defaultValue`	`string \| string[]`	No	`—`	Initial uncontrolled value
`onChange`	`(value: string \| string[]) => void`	Yes	`—`	Callback when selection changes
`size`	`'sm' \| 'md' \| 'lg'`	No	`'md'`	Size variant
`variant`	`'default' \| 'bordered' \| 'flush'`	No	`'default'`	Visual style variant
`emptyMessage`	`string`	No	`'No options'`	Message shown when options array is empty
`disabled`	`boolean`	No	`false`	Disable the entire listbox
`ariaLabel`	`string`	Yes	`—`	Accessible label for the listbox
`ariaLabelledBy`	`string`	No	`—`	ID of element that labels this listbox
`maxHeight`	`number`	No	`—`	Max height in pixels before scrolling
`groups`	`Array<{ id: string; label: string }>`	No	`—`	Option group headers
`autoFocusFirstOption`	`boolean`	No	`false`	Auto-focus first option on mount
`renderOption`	`(option, state) => ReactNode`	No	`—`	Custom option renderer
`locale`	`string`	No	`—`	Locale for text formatting
`className`	`string`	No	`—`	Additional CSS classes
`id`	`string`	No	`—`	DOM id

Usage

Import

import { Listbox } from '@epasslive/design-system'

Basic

<Listbox />

With Variants

<Listbox variant="primary" size="md" />