useListbox

Hook that manages listbox selection state, keyboard navigation, and option search.

basic-demo

Usage#

import { useListbox, useListboxOption } from '@primereact/headless/listbox';
 
const listbox = useListbox({ options: cities, optionLabel: 'name' });
 
return (
    <div {...listbox.rootProps}>
        <ul {...listbox.listProps}>
            {listbox.getOptions().map((option, index) => {
                const { optionProps, state } = useListboxOption({ option, index, context: listbox });
                return <li {...optionProps}>{listbox.getOptionLabel(option)}</li>;
            })}
        </ul>
    </div>
);

useListbox manages value state, keyboard focus cycling, type-ahead search, and ARIA attributes for option lists — see Primitive for a component-based API.

Features#

rootProps, listProps, and filterProps return spread-ready props including ref for each container element
useListboxOption child hook returns optionProps with ARIA attributes, data-selected/data-focused/data-disabled states, and mouse/touch handlers
getOptionLabel(option), getOptionValue(option), isSelected(option), isOptionDisabled(option) for reading option metadata
Type-ahead search: typing characters moves focus to the matching option
onOptionSelect(event, option, index) and onClearClick(event) for imperative selection control

Behavior#

Default Value#

Set defaultValue for uncontrolled selection.

const listbox = useListbox({ options: cities, optionLabel: 'name', defaultValue: 'NY' });

Controlled#

Pass value and onValueChange for controlled usage.

const [selected, setSelected] = React.useState(null);
 
const listbox = useListbox({
    options: cities,
    optionLabel: 'name',
    value: selected,
    onValueChange: (e) => setSelected(e.value)
});

Multiple Selection#

Set multiple to allow selecting more than one item. The value becomes an array.

const listbox = useListbox({ options: cities, optionLabel: 'name', multiple: true });

Meta Key Selection#

Enable metaKeySelection with multiple to require Ctrl/Cmd for additive selection.

const listbox = useListbox({ options: cities, optionLabel: 'name', multiple: true, metaKeySelection: true });

Focus Behavior#

Use autoOptionFocus to automatically focus the first option, selectOnFocus to select while navigating, and focusOnHover to move focus with mouse hover.

const listbox = useListbox({ options: cities, optionLabel: 'name', autoOptionFocus: true, selectOnFocus: true });

Option Groups#

Set optionGroupLabel and optionGroupChildren to organize options into groups. Use useListboxOption with group to detect group headers.

const listbox = useListbox({
    options: groupedCities,
    optionLabel: 'label',
    optionGroupLabel: 'label',
    optionGroupChildren: 'items'
});
 
// Inside map:
const { optionProps, groupProps, state } = useListboxOption({ option, index, context: listbox });
if (state.group) return <div {...groupProps}>{listbox.getOptionGroupLabel(option)}</div>;

Disabled#

Set disabled to prevent all interaction.

const listbox = useListbox({ options: cities, optionLabel: 'name', disabled: true });

Custom Styling with Data Attributes#

[data-scope='listbox'][data-part='option'][data-selected] {
    background-color: #eff6ff;
    color: #1d4ed8;
}
[data-scope='listbox'][data-part='option'][data-focused] {
    outline: 1px solid #3b82f6;
}
[data-scope='listbox'][data-part='option'][data-disabled] {
    opacity: 0.6;
    pointer-events: none;
}

API#

useListbox#

Name	Type	Default
`value`	`unknown`	—
The current value of the listbox. For single selection, this is a single value. For multiple selection, this is an array of values.
`defaultValue`	`unknown`	—
The default value of the listbox when used in uncontrolled mode.
`options`	`T[]`	—
An array of options to display in the listbox.
`optionKey`	`string`	—
Unique key for each option.
`optionLabel`	`string`	—
Label field for each option.
`optionValue`	`string`	—
Value field for each option.
`optionDisabled`	`string`	—
Field to check if an option is disabled.
`optionGroupLabel`	`string`	—
Label field for option groups.
`optionGroupChildren`	`string`	—
Field that contains the children options in a group.
`disabled`	`boolean`	—
When present, it specifies that the listbox should be disabled.
`invalid`	`boolean`	—
When present, it specifies that the component should have invalid state style.
`locale`	`string`	—
The locale to use for localization. Used for accessibility labels.
`multiple`	`boolean`	—
When present, allows selecting multiple options.
`metaKeySelection`	`boolean`	—
When enabled, requires holding the meta key (Ctrl/Cmd) to select/deselect items in multiple selection mode.
`autoOptionFocus`	`boolean`	—
When enabled, the focused option is automatically highlighted.
`selectOnFocus`	`boolean`	—
When enabled, the focused option is automatically selected.
`focusOnHover`	`boolean`	—
When enabled, the focused option changes on hover.
`tabIndex`	`number`	—
Index of the element in tabbing order.
`onValueChange`	`(event: useListboxValueChangeEvent) => void`	—
Callback to invoke when the value changes.

useListboxOption#

Name	Type	Default
`option`	`unknown`	—
The option data object.
`index`	`number`	—
The index of the option in the list.
`group`	`boolean`	`false`
Whether the option is a group header.
`disabled`	`boolean`	`false`
Whether the option is disabled.
`context`	`useListboxInstance`	—
The parent listbox instance providing state and methods.

Accessibility#

See Listbox Primitive for WAI-ARIA compliance details and keyboard support.