Listbox

An always-visible list for selecting one or more options.

Move to

import * as React from 'react';
import { Listbox } from '@base-ui/react/listbox';
import styles from './index.module.css';

const folders = [
  { label: 'Inbox', value: 'inbox' },
  { label: 'Archive', value: 'archive' },
  { label: 'Drafts', value: 'drafts' },
  { label: 'Projects', value: 'projects' },
  { label: 'Receipts', value: 'receipts' },
  { label: 'Travel', value: 'travel' },
  { label: 'Work', value: 'work' },
  { label: 'Personal', value: 'personal' },
];

export default function ExampleListbox() {
  return (
    <div className={styles.Field}>
      <Listbox.Root defaultValue="archive">
        <Listbox.Label className={styles.Label}>Move to</Listbox.Label>
        <Listbox.List className={styles.List}>
          {folders.map(({ label, value }) => (
            <Listbox.Item key={value} value={value} className={styles.Item}>
              <Listbox.ItemIndicator className={styles.ItemIndicator}>
                <CheckIcon className={styles.ItemIndicatorIcon} />
              </Listbox.ItemIndicator>
              <span className={styles.ItemText}>{label}</span>
            </Listbox.Item>
          ))}
        </Listbox.List>
      </Listbox.Root>
    </div>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg fill="currentcolor" width="10" height="10" viewBox="0 0 10 10" {...props}>
      <path d="M9.1603 1.12218C9.50684 1.34873 9.60427 1.81354 9.37792 2.16038L5.13603 8.66012C5.01614 8.8438 4.82192 8.96576 4.60451 8.99384C4.3871 9.02194 4.1683 8.95335 4.00574 8.80615L1.24664 6.30769C0.939709 6.02975 0.916013 5.55541 1.19372 5.24822C1.47142 4.94102 1.94536 4.91731 2.2523 5.19524L4.36085 7.10461L8.12299 1.33999C8.34934 0.993152 8.81376 0.895638 9.1603 1.12218Z" />
    </svg>
  );
}

Usage guidelines

Prefer Select for forms: Use Select instead of Listbox for selection in forms.
Multi-select support: Set multiple to allow selecting more than one item. The value is then an array.
Provide an accessible name: Prefer <Listbox.Label>, or provide an aria-label on <Listbox.List> when no visible label is rendered.

Anatomy

Import the component and assemble its parts:

Anatomy

import { Listbox } from '@base-ui/react/listbox';

<Listbox.Root>
  <Listbox.Label />
  <Listbox.List>
    <Listbox.Item>
      <Listbox.ItemIndicator />
    </Listbox.Item>
    <Listbox.Group>
      <Listbox.GroupLabel />
    </Listbox.Group>
  </Listbox.List>
</Listbox.Root>

Examples

Multiple selection

Add the multiple prop to let users select more than one item. The value is an array of the selected items.

Choose your favorite animals

index.tsx index.module.css

import * as React from 'react';
import { Listbox } from '@base-ui/react/listbox';
import styles from './index.module.css';

const animals = [
  { label: 'Cat', value: 'cat' },
  { label: 'Dog', value: 'dog' },
  { label: 'Elephant', value: 'elephant' },
  { label: 'Giraffe', value: 'giraffe' },
  { label: 'Koala', value: 'koala' },
  { label: 'Lion', value: 'lion' },
  { label: 'Otter', value: 'otter' },
  { label: 'Penguin', value: 'penguin' },
  { label: 'Zebra', value: 'zebra' },
];

export default function ExampleListboxMultiSelection() {
  return (
    <div className={styles.Field}>
      <Listbox.Root multiple defaultValue={['otter', 'penguin']}>
        <Listbox.Label className={styles.Label}>Choose your favorite animals</Listbox.Label>
        <Listbox.List className={styles.List}>
          {animals.map(({ label, value }) => (
            <Listbox.Item key={value} value={value} className={styles.Item}>
              <Listbox.ItemIndicator className={styles.ItemIndicator}>
                <CheckIcon className={styles.ItemIndicatorIcon} />
              </Listbox.ItemIndicator>
              <span className={styles.ItemText}>{label}</span>
            </Listbox.Item>
          ))}
        </Listbox.List>
      </Listbox.Root>
    </div>
  );
}

function CheckIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg fill="currentcolor" width="10" height="10" viewBox="0 0 10 10" {...props}>
      <path d="M9.1603 1.12218C9.50684 1.34873 9.60427 1.81354 9.37792 2.16038L5.13603 8.66012C5.01614 8.8438 4.82192 8.96576 4.60451 8.99384C4.3871 9.02194 4.1683 8.95335 4.00574 8.80615L1.24664 6.30769C0.939709 6.02975 0.916013 5.55541 1.19372 5.24822C1.47142 4.94102 1.94536 4.91731 2.2523 5.19524L4.36085 7.10461L8.12299 1.33999C8.34934 0.993152 8.81376 0.895638 9.1603 1.12218Z" />
    </svg>
  );
}

Use multiple="opt-in" when users opt in to selecting more than one item by holding a modifier key. On touch devices, which have no modifier keys, a tap adds or removes an item, the same as multiple.

Playlist

index.tsx index.module.css

import * as React from 'react';
import { Listbox } from '@base-ui/react/listbox';
import styles from './index.module.css';

const songs = [
  { title: 'Bohemian Rhapsody', artist: 'Queen', value: 'bohemian-rhapsody' },
  { title: 'Billie Jean', artist: 'Michael Jackson', value: 'billie-jean' },
  { title: 'Hotel California', artist: 'Eagles', value: 'hotel-california', disabled: true },
  { title: 'Superstition', artist: 'Stevie Wonder', value: 'superstition' },
  { title: 'Dancing Queen', artist: 'ABBA', value: 'dancing-queen' },
];

export default function ExampleListboxOptInSelection() {
  return (
    <div className={styles.Field}>
      <Listbox.Root multiple="opt-in" defaultValue={['billie-jean']}>
        <Listbox.Label className={styles.Label}>Playlist</Listbox.Label>
        <Listbox.List className={styles.List}>
          {songs.map(({ title, artist, value, disabled }) => (
            <Listbox.Item key={value} value={value} disabled={disabled} className={styles.Item}>
              <span className={styles.ItemTitle}>{title}</span>
              <span className={styles.ItemArtist}>{artist}</span>
            </Listbox.Item>
          ))}
        </Listbox.List>
      </Listbox.Root>
    </div>
  );
}

Virtualized

Render large lists with a virtualization library such as @tanstack/react-virtual.

Items

index.tsx index.module.css

'use client';
import * as React from 'react';
import { Listbox } from '@base-ui/react/listbox';
import { useVirtualizer } from '@tanstack/react-virtual';
import styles from './index.module.css';

const ITEM_HEIGHT = 32;

export default function ExampleListboxVirtualized() {
  const listRef = React.useRef<HTMLDivElement>(null);
  const [value, setValue] = React.useState<Item[]>([]);

  const virtualizer = useVirtualizer({
    count: items.length,
    getScrollElement: () => listRef.current,
    estimateSize: () => ITEM_HEIGHT,
    // The same 2px spacing as the other examples.
    gap: 2,
    overscan: 5,
  });

  return (
    <div className={styles.Field}>
      <Listbox.Root
        multiple="opt-in"
        items={items}
        value={value}
        onValueChange={(nextValue, eventDetails) => {
          // The listbox only knows which rendered items are disabled, so remove the rest from
          // ranges.
          if (eventDetails.range) {
            nextValue = nextValue.filter((item) => !item.disabled);
          }
          setValue(nextValue);
        }}
        onItemHighlighted={(_, eventDetails) => {
          // Scroll the highlighted item into view.
          if (eventDetails.reason !== 'pointer' && eventDetails.index !== -1) {
            virtualizer.scrollToIndex(eventDetails.index);
          }
        }}
      >
        <Listbox.Label className={styles.Label}>Items</Listbox.Label>
        <Listbox.List ref={listRef} className={styles.List}>
          <div className={styles.Content} style={{ height: virtualizer.getTotalSize() }}>
            {virtualizer.getVirtualItems().map((virtualItem) => {
              const item = items[virtualItem.index];
              return (
                <Listbox.Item
                  key={virtualItem.key}
                  value={item}
                  disabled={item.disabled}
                  aria-setsize={items.length}
                  aria-posinset={virtualItem.index + 1}
                  className={styles.Item}
                  style={{ transform: `translateY(${virtualItem.start}px)` }}
                >
                  {item.label}
                </Listbox.Item>
              );
            })}
          </div>
        </Listbox.List>
      </Listbox.Root>
    </div>
  );
}

interface Item {
  value: string;
  label: string;
  disabled: boolean;
}

// Every tenth item is disabled.
const items: Item[] = Array.from({ length: 3000 }, (_, index) => {
  const value = String(index + 1);
  return { value, label: `Item ${value.padStart(4, '0')}`, disabled: (index + 1) % 10 === 0 };
});

API reference

Root

Groups all parts of the listbox. Doesn’t render its own HTML element.

defaultValueUnion—

Name: defaultValue
Description: The uncontrolled value of the listbox when it’s initially rendered.

To render a controlled listbox, use the value prop instead.
Type: Value[] | Value | null | undefined

valueUnion—

Name: value
Description: The value of the listbox. Use when controlled.
Type: Value[] | Value | null | undefined

onValueChangefunction—

Name: onValueChange
Description: Event handler called when the value of the listbox changes.
Type: | (( value: Value[] | Value | null, eventDetails: Listbox.Root.ChangeEventDetails, ) => void) | undefined

highlightItemOnHoverbooleantrue

Name: highlightItemOnHover
Description: Whether moving the pointer over an item highlights it. While focus is in the listbox, the item also receives focus. The pointer never takes focus from outside the listbox.
Type: boolean | undefined
Default: true

isItemEqualToValuefunction—

Name: isItemEqualToValue
Description: Custom comparison logic used to determine if a listbox item value matches the current selected value. Defaults to Object.is comparison.
Type: ((itemValue: Value, value: Value) => boolean) | undefined

itemToStringLabelfunction—

Name: itemToStringLabel
Description: When the item values are objects (<Listbox.Item value={object}>), this function converts the object value to a string representation for typeahead. If the shape of the object is { value, label }, the label will be used automatically without needing to specify this prop.
Type: ((itemValue: Value) => string) | undefined

itemsValue[]—

Name: items
Description: The items in the list, including those that aren’t rendered. Pass them when the list is virtualized, and use each item as its Listbox.Item value. Keyboard navigation, typeahead and selection can then reach items that aren’t rendered.
Type: Value[] | undefined

multipleboolean | 'opt-in'false

Name: multiple
Description: Whether multiple items can be selected, and how selecting an item affects the current selection.

false: only one item can be selected.

true: each item is toggled independently.

'opt-in': selecting an item moves the current selection to it, and users hold a modifier key to select more than one item. On touch devices, where there are no modifier keys, it behaves like true.
Type: boolean | 'opt-in' | undefined
Default: false

onItemHighlightedfunction—

Name: onItemHighlighted
Description: Callback fired when an item is highlighted or unhighlighted. Receives the highlighted item value (or undefined if no item is highlighted) and event details with a reason property describing why the highlight changed. The reason can be:

'keyboard': the highlight changed due to keyboard navigation or typeahead.

'pointer': the highlight changed due to pointer hovering. The event may be a MouseEvent rather than a PointerEvent.

'none': the highlight changed for another reason, such as an item receiving or losing focus.

With items, the highlighted item may not be rendered yet, so scroll it into view.
Type: | (( itemValue: Value | undefined, eventDetails: Listbox.Root.HighlightEventDetails, ) => void) | undefined

disabledbooleanfalse

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined
Default: false

orientation'vertical' | 'horizontal''vertical'

Name: orientation
Description: The orientation of the listbox for keyboard navigation.
Type: 'vertical' | 'horizontal' | undefined
Default: 'vertical'

childrenReact.ReactNode—

Name: children
Type: React.ReactNode | undefined

Listbox.Root.PropsHide

Re-Export of Root props as ListboxRootProps

Listbox.Root.StateHide

type ListboxRootState = {}

Listbox.Root.ChangeEventReasonHide

type ListboxRootChangeEventReason = 'item-press' | 'list-navigation' | 'escape-key'

Listbox.Root.ChangeEventDetailsHide

type ListboxRootChangeEventDetails = (
  | { reason: 'item-press'; event: MouseEvent | KeyboardEvent | PointerEvent }
  | { reason: 'list-navigation'; event: KeyboardEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
  /**
   * Set when the change selects a range of items, such as with Shift+Click, Shift+Arrow or
   * Ctrl/Cmd+A.
   */
  range?: { from: number; to: number; mode: 'replace' | 'add' };
}

Listbox.Root.HighlightEventReasonHide

type ListboxRootHighlightEventReason = 'keyboard' | 'pointer' | 'none'

Listbox.Root.HighlightEventDetailsHide

type ListboxRootHighlightEventDetails =
  | { reason: 'none'; event: Event; index: number }
  | { reason: 'keyboard'; event: KeyboardEvent; index: number }
  | { reason: 'pointer'; event: MouseEvent | PointerEvent; index: number }

Label

An accessible label that is automatically associated with the listbox. Renders a <div> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Listbox.Label.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Listbox.Label.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Listbox.Label.State, ) => ReactElement) | undefined

Listbox.Label.PropsHide

Re-Export of Label props as ListboxLabelProps

Listbox.Label.StateHide

type ListboxLabelState = {}

List

A container for the listbox items. Renders a <div> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Listbox.List.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Listbox.List.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Listbox.List.State, ) => ReactElement) | undefined

data-orientation

Indicates the orientation of the listbox.

data-disabled

Present when the listbox is disabled.

Attribute	Description	-
`data-orientation`	Indicates the orientation of the listbox.
`data-disabled`	Present when the listbox is disabled.

Listbox.List.PropsHide

Re-Export of List props as ListboxListProps

Listbox.List.StateHide

type ListboxListState = {
  /** Whether the listbox is disabled. */
  disabled: boolean;
  /** The orientation of the listbox. */
  orientation: 'vertical' | 'horizontal';
}

Item

An individual option in the listbox. Renders a <div> element.

labelstring—

Name: label
Description: Overrides the text used for keyboard text navigation. Falls back to the rendered text when not provided.
Type: string | undefined

valueanynull

Name: value
Description: A unique value that identifies this listbox item.
Type: any | undefined
Default: null

nativeButtonbooleanfalse

Name: nativeButton
Description: Whether the component renders a native <button> element when replacing it via the render prop. Set to true if the rendered element is a native button.
Type: boolean | undefined
Default: false

disabledbooleanfalse

Name: disabled
Description: Whether the component should ignore user interaction.
Type: boolean | undefined
Default: false

childrenReact.ReactNode—

Name: children
Type: React.ReactNode | undefined

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Listbox.Item.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Listbox.Item.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Listbox.Item.State, ) => ReactElement) | undefined

data-selected

Present when the listbox item is selected.

data-highlighted

Present when the listbox item is highlighted.

data-disabled

Present when the listbox item is disabled.

Attribute	Description	-
`data-selected`	Present when the listbox item is selected.
`data-highlighted`	Present when the listbox item is highlighted.
`data-disabled`	Present when the listbox item is disabled.

Listbox.Item.PropsHide

Re-Export of Item props as ListboxItemProps

Listbox.Item.StateHide

type ListboxItemState = {
  /** Whether the item should ignore user interaction. */
  disabled: boolean;
  /** Whether the item is selected. */
  selected: boolean;
  /** Whether the item is highlighted. */
  highlighted: boolean;
}

ItemIndicator

Indicates whether the listbox item is selected. Renders a <span> element.

childrenReact.ReactNode—

Name: children
Type: React.ReactNode | undefined

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: Listbox.ItemIndicator.State, ) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Listbox.ItemIndicator.State, ) => React.CSSProperties | undefined) | undefined

keepMountedboolean—

Name: keepMounted
Description: Whether to keep the HTML element in the DOM when the item is not selected.
Type: boolean | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Listbox.ItemIndicator.State, ) => ReactElement) | undefined

Listbox.ItemIndicator.PropsHide

Re-Export of ItemIndicator props as ListboxItemIndicatorProps

Listbox.ItemIndicator.StateHide

type ListboxItemIndicatorState = {
  /** Whether the item is selected. */
  selected: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
}

Group

Groups related listbox items with the corresponding label. Renders a <div> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | ((state: Listbox.Group.State) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Listbox.Group.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Listbox.Group.State, ) => ReactElement) | undefined

Listbox.Group.PropsHide

Re-Export of Group props as ListboxGroupProps

Listbox.Group.StateHide

type ListboxGroupState = {}

GroupLabel

An accessible label that is automatically associated with its parent group. Renders a <div> element.

classNamestring | function—

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: | string | (( state: Listbox.GroupLabel.State, ) => string | undefined) | undefined

styleReact.CSSProperties | function—

Name: style
Description: Style applied to the element, or a function that returns a style object based on the component’s state.
Type: | React.CSSProperties | (( state: Listbox.GroupLabel.State, ) => React.CSSProperties | undefined) | undefined

renderReactElement | function—

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Listbox.GroupLabel.State, ) => ReactElement) | undefined

Listbox.GroupLabel.PropsHide

Re-Export of GroupLabel props as ListboxGroupLabelProps

Listbox.GroupLabel.StateHide

type ListboxGroupLabelState = {}