Listbox

An unstyled listbox component with keyboard navigation, type-ahead search, and single or multiple selection.

Build fully custom option lists with complete control over layout and styling.

basic-demo

Pre-styled Versions

Choose a pre-styled library to use Listbox with ready-made designs.

Styled

Theme-based styling with CSS variables

Tailwind

Utility-first styling with Tailwind CSS

For hook-based usage without components, see the Headless API.

Features#

Compound component API with sub-components: Root, List, Option, OptionIndicator, Header, Filter, Empty, Footer
Single and multiple selection with keyboard focus cycling and type-ahead search
Option grouping with group header rendering
Built-in filter input integration with customizable filtering logic

Usage#

import { Listbox } from 'primereact/listbox';

<Listbox.Root>
    <Listbox.Header>
        <Listbox.Filter />
    </Listbox.Header>
    <Listbox.List>
        <Listbox.Option>
            <Listbox.OptionIndicator />
        </Listbox.Option>
    </Listbox.List>
    <Listbox.Empty />
    <Listbox.Footer />
</Listbox.Root>

Behavior#

Polymorphic Rendering#

Use as on any sub-component to change the rendered HTML element.

<Listbox.Root as="section">
    <Listbox.List as="div">...</Listbox.List>
</Listbox.Root>

Render Function Children#

Listbox.List accepts a render function as children, providing access to the component instance for custom option rendering.

<Listbox.List>
    {(instance) =>
        instance.options?.map((option, index) => (
            <Listbox.Option key={index} index={index}>
                {instance.listbox?.getOptionLabel(option)}
            </Listbox.Option>
        ))
    }
</Listbox.List>

Pass Through#

Some parts may not be visible in the preview depending on the component's current state.

/* Select a part to see its CSS selector for custom styling */

API#

ListboxRoot#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ListboxRootInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ListboxRootInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ListboxRootInstance<T>`	—
The instance to pass to the component.
`pt`	`SafeRecord<ListboxRootPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ListboxRootInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`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.
`onValueChange`	`(event: useListboxValueChangeEvent) => void`	—
Callback to invoke when the value changes.
`tabIndex`	`number`	—
Index of the element in tabbing order.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of Listbox component.

label	type	description
root	ListboxRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.
hiddenElement	ListboxRootPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the hidden sentinel element's DOM element.
header	ListboxRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the header's DOM element.
footer	ListboxRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the footer's DOM element.
list	ListboxRootPassThroughType<HTMLAttributes<HTMLUListElement>>	Used to pass attributes to the list's DOM element.
empty	ListboxRootPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the empty message's DOM element.
optionGroup	ListboxRootPassThroughType<HTMLAttributes<HTMLLIElement>>	Used to pass attributes to the option group's DOM element.
option	ListboxRootPassThroughType<HTMLAttributes<HTMLLIElement>>	Used to pass attributes to the option's DOM element.
optionIndicator	ListboxRootPassThroughType<HTMLAttributes<HTMLElement>>	Used to pass attributes to the option indicator's DOM element.
filter	ListboxRootPassThroughType<HTMLAttributes<HTMLElement>>	Used to pass attributes to the filter's DOM element.

ListboxList#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ListboxListInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ListboxListInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ListboxListInstance<T>`	—
The instance to pass to the component.
`pt`	`SafeRecord<ListboxListPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ListboxListInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of ListboxList component.

label	type	description
root	ListboxListPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

ListboxOption#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ListboxOptionInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ListboxOptionInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ListboxOptionInstance<T>`	—
The instance to pass to the component.
`pt`	`SafeRecord<ListboxOptionPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ListboxOptionInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`group`	`boolean`	—
When enabled, renders the option as a group header.
`uKey`	`PropertyKey`	—
Unique key for the option. Used for identification and selection.
`index`	`number`	—
Index of the option in the list.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-selected`	Present when selected
`data-unselected`	Present when unselected
`data-focused`	Present when focused
`data-disabled`	Present when disabled

Defines passthrough(pt) options of ListboxOption component.

label	type	description
root	ListboxOptionPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

ListboxOptionIndicator#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ListboxOptionIndicatorInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ListboxOptionIndicatorInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ListboxOptionIndicatorInstance<T>`	—
The instance to pass to the component.
`pt`	`SafeRecord<ListboxOptionIndicatorPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ListboxOptionIndicatorInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`match`	`"always"` \| `"selected"` \| `"unselected"`	—
Determines the visibility of the indicator based on the selection state of the option. - "always": Indicator is always visible. - "selected": Indicator is visible only when the option is selected. - "unselected": Indicator is visible only when the option is not selected.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Attribute	Value
`data-selected`	Present when selected
`data-unselected`	Present when unselected

Defines passthrough(pt) options of ListboxOptionIndicator component.

label	type	description
root	ListboxOptionIndicatorPassThroughType<HTMLAttributes<HTMLElement>>	Used to pass attributes to the root's DOM element.

ListboxHeader#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ListboxHeaderInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ListboxHeaderInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ListboxHeaderInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ListboxHeaderPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ListboxHeaderInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of ListboxHeader component.

label	type	description
root	ListboxHeaderPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

ListboxFilter#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ListboxFilterInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ListboxFilterInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ListboxFilterInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ListboxFilterPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ListboxFilterInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of ListboxFilter component.

label	type	description
root	ListboxFilterPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

ListboxEmpty#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ListboxEmptyInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ListboxEmptyInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ListboxEmptyInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ListboxEmptyPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ListboxEmptyInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of ListboxEmpty component.

label	type	description
root	ListboxEmptyPassThroughType<HTMLAttributes<HTMLSpanElement>>	Used to pass attributes to the root's DOM element.

ListboxFooter#

Name	Type	Default
`ref`	`Ref<unknown>`	—
The reference to the component instance.
`pIf`	`boolean`	`true`
Whether the component should be rendered.
`style`	`CSSProperties` \| `((instance?: ListboxFooterInstance) => CSSProperties)`	—
The style to apply to the component.
`className`	`string` \| `((instance?: ListboxFooterInstance) => string)`	—
The class name to apply to the component.
`as`	`string` \| `number` \| `bigint` \| `boolean` \| `ComponentClass<any, any>` \| `FunctionComponent<any>` \| `ReactElement<unknown, string` \| `JSXElementConstructor<any>>` \| `Iterable<ReactNode, any, any>` \| `ReactPortal` \| `Promise<AwaitedReactNode>`	—
The component type to render.
`asChild`	`boolean`	`false`
Whether the component should be rendered as a child component.
`instance`	`ListboxFooterInstance`	—
The instance to pass to the component.
`pt`	`SafeRecord<ListboxFooterPassThrough>`	—
The pass-through props to pass to the component.
`ptOptions`	`PassThroughOptions`	—
The pass-through options to pass to the component.
`unstyled`	`boolean`	—
Whether the component should be rendered without classes.
`dt`	`unknown`	—
The design token to use for the component.
`styles`	`StylesOptions<ComponentInstance>`	—
The styles to use for the component.
`render`	`(instance: ListboxFooterInstance) => ReactNode`	—
The render function to render the component with instance access.
`children`	`any`	—
The children to render. Accepts `React.ReactNode` for static content or a render function `(instance: I) => React.ReactNode` for instance access. Typed as `any` to avoid JSX type errors when used directly in templates.
`[key: string]`	`any`	—
`pt-{optionName}-*`	`-`	—
Pass through attributes for customizing component. For more info, see Pass Through tab.

Defines passthrough(pt) options of ListboxFooter component.

label	type	description
root	ListboxFooterPassThroughType<HTMLAttributes<HTMLDivElement>>	Used to pass attributes to the root's DOM element.

Accessibility#

A value to describe the component can be provided with aria-labelledby or aria-label props. The list element has a listbox role with aria-multiselectable set to true when multiple selection is enabled. Each list item has an option role with aria-selected and aria-disabled attributes.

When metaKeySelection is enabled, pointer-based multi-selection requires a platform meta key (Ctrl on Windows/Linux and Cmd on macOS). Keyboard interaction remains available through standard listbox shortcuts.

Keyboard Support#

Key	Function
`tab`	Moves focus to the first selected option, if there is none then first option receives the focus.
`up arrow`	Moves focus to the previous option.
`down arrow`	Moves focus to the next option.
`enter`	Toggles the selected state of the focused option.
`space`	Toggles the selected state of the focused option.
`home`	Moves focus to the first option.
`end`	Moves focus to the last option.
`shift + down arrow`	Moves focus to the next option and toggles the selection state.
`shift + up arrow`	Moves focus to the previous option and toggles the selection state.
`shift + space`	Selects the items between the most recently selected option and the focused option.
`control + shift + home`	Selects the focused option and all the options up to the first one.
`control + shift + end`	Selects the focused option and all the options down to the last one.
`control + a`	Selects all options.
`page up`	Jumps visual focus to the first option.
`page down`	Jumps visual focus to the last option.
`any printable character`	Moves focus to the option whose label starts with the characters being typed.

Filter Input Keyboard Support#

Key	Function
`down arrow`	Moves focus to the next option, if there is none then visual focus does not change.
`up arrow`	Moves focus to the previous option, if there is none then visual focus does not change.
`left arrow`	Removes the visual focus from the current option and moves input cursor to one character left.
`right arrow`	Removes the visual focus from the current option and moves input cursor to one character right.
`home`	Moves input cursor at the beginning, if not then moves focus to the first option.
`end`	Moves input cursor at the end, if not then moves focus to the last option.
`tab`	Moves focus to the next focusable element in the component. If there is none, moves focus to next element in page.