Listbox

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

Playlist

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

const songGroups = [
  {
    label: 'Pop',
    songs: [
      { title: 'Billie Jean', artist: 'Michael Jackson', value: 'billie-jean' },
      { title: 'Dancing Queen', artist: 'ABBA', value: 'dancing-queen' },
      { title: 'Like a Prayer', artist: 'Madonna', value: 'like-a-prayer' },
      { title: 'Bohemian Rhapsody', artist: 'Queen', value: 'bohemian-rhapsody' },
    ],
  },
  {
    label: 'Rock',
    songs: [
      { title: 'Hotel California', artist: 'Eagles', value: 'hotel-california' },
      { title: 'Stairway to Heaven', artist: 'Led Zeppelin', value: 'stairway-to-heaven' },
      { title: 'Smells Like Teen Spirit', artist: 'Nirvana', value: 'smells-like-teen-spirit' },
      { title: 'Back in Black', artist: 'AC/DC', value: 'back-in-black' },
    ],
  },
];

export default function ExampleListbox() {
  return (
    <div className={styles.Field}>
      <Listbox.Root defaultValue={['billie-jean']}>
        <Listbox.Label className={styles.Label}>Playlist</Listbox.Label>
        <Listbox.List className={styles.List}>
          {songGroups.map((group) => (
            <Listbox.Group key={group.label} className={styles.Group}>
              <Listbox.GroupLabel className={styles.GroupLabel}>{group.label}</Listbox.GroupLabel>
              {group.songs.map(({ title, artist, value }) => (
                <Listbox.Item key={value} value={value} className={styles.Item}>
                  <Listbox.ItemIndicator className={styles.ItemIndicator}>
                    <CheckIcon className={styles.ItemIndicatorIcon} />
                  </Listbox.ItemIndicator>
                  <Listbox.ItemText className={styles.ItemText}>
                    <span className={styles.ItemTitle}>{title}</span>
                    <span className={styles.ItemArtist}>{artist}</span>
                  </Listbox.ItemText>
                </Listbox.Item>
              ))}
            </Listbox.Group>
          ))}
        </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

Always visible: Unlike Select, the Listbox is always open and does not use a popup or trigger. Use it when all options should be visible at once.
Multi-select support: Set selectionMode="multiple" or "explicit-multiple" to allow selecting more than one item.
Form controls must have an accessible name: Prefer <Listbox.Label>, or provide an aria-label on <Listbox.List> when no visible label is rendered. See the forms guide.

Anatomy

Import the component and assemble its parts:

Anatomy

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

<Listbox.Root>
  <Listbox.Label />
  <Listbox.DragAndDropProvider>
    <Listbox.List>
      <Listbox.Item>
        <Listbox.ItemIndicator />
        <Listbox.ItemText />
        <Listbox.ItemDragHandle />
      </Listbox.Item>
      <Listbox.Group>
        <Listbox.GroupLabel />
      </Listbox.Group>
      <Listbox.LoadingTrigger />
    </Listbox.List>
  </Listbox.DragAndDropProvider>
</Listbox.Root>

Examples

Selection modes

The selectionMode prop controls how items are selected:

"single" (default) — clicking an item selects it and deselects any other.
"multiple" — every click toggles an item. Hold Shift and click to select a contiguous range.
"explicit-multiple" — clicking an item replaces the selection. Hold Ctrl/⌘ and click to toggle, or Shift and click to select a range.

multiple

explicit-multiple

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' },
  { title: 'Superstition', artist: 'Stevie Wonder', value: 'superstition' },
  { title: 'Dancing Queen', artist: 'ABBA', value: 'dancing-queen' },
];

export default function ExampleListboxMultiSelection() {
  return (
    <div className={styles.Row}>
      <SongList label="multiple" selectionMode="multiple" />
      <SongList label="explicit-multiple" selectionMode="explicit-multiple" />
    </div>
  );
}

function SongList({
  label,
  selectionMode,
}: {
  label: string;
  selectionMode: 'multiple' | 'explicit-multiple';
}) {
  return (
    <div className={styles.Field}>
      <Listbox.Root selectionMode={selectionMode} defaultValue={['bohemian-rhapsody']}>
        <Listbox.Label className={styles.Label}>{label}</Listbox.Label>
        <Listbox.List className={styles.List}>
          {songs.map(({ title, artist, value }) => (
            <Listbox.Item key={value} value={value} className={styles.Item}>
              <Listbox.ItemIndicator className={styles.ItemIndicator}>
                <CheckIcon className={styles.ItemIndicatorIcon} />
              </Listbox.ItemIndicator>
              <Listbox.ItemText className={styles.ItemText}>
                <span className={styles.ItemTitle}>{title}</span>
                <span className={styles.ItemArtist}>{artist}</span>
              </Listbox.ItemText>
            </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>
  );
}

Lazy loading

Use Listbox.LoadingTrigger as a sentinel at the end of the list. When it scrolls into view, the onLoadMore callback fires.

Library

index.tsx index.module.css

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

const allSongs = [
  'Bohemian Rhapsody',
  'Billie Jean',
  'Hotel California',
  'Stairway to Heaven',
  'Imagine',
  'Smells Like Teen Spirit',
  'Like a Rolling Stone',
  'Hey Jude',
  'Superstition',
  "What's Going On",
  'Dancing Queen',
  'Good Vibrations',
  'Johnny B. Goode',
  'I Will Always Love You',
  'Purple Rain',
  'Respect',
  'Yesterday',
  'Back in Black',
  'Like a Prayer',
  'A Change Is Gonna Come',
  'London Calling',
  'Born to Run',
  'Waterloo Sunset',
  'God Only Knows',
  'No Woman, No Cry',
  'Every Breath You Take',
  'Under Pressure',
  'Bridge Over Troubled Water',
  'Let It Be',
  'Redemption Song',
  'Heroes',
  'A Day in the Life',
  'Life on Mars?',
  'Wish You Were Here',
  'Go Your Own Way',
  'Take Me to the River',
  'Heart of Gold',
  'Jolene',
  'Waterloo',
  'Roxanne',
  'Ring of Fire',
  'I Heard It Through the Grapevine',
  'The Message',
  'Sabotage',
  'Losing My Religion',
  'Fast Car',
  'Hallelujah',
  'Stand by Me',
  'Summertime',
  'What a Wonderful World',
].map((song, i) => ({
  title: song,
  value: `song-${i + 1}`,
}));

const PAGE_SIZE = 10;

export default function ExampleListboxLazyLoading() {
  const [count, setCount] = React.useState(PAGE_SIZE);
  const [loading, setLoading] = React.useState(false);
  const hasMore = count < allSongs.length;
  const items = allSongs.slice(0, count);

  const handleLoadMore = React.useCallback(() => {
    if (loading || !hasMore) {
      return;
    }

    setLoading(true);

    // Simulate an async fetch
    setTimeout(() => {
      setCount((prev) => Math.min(prev + PAGE_SIZE, allSongs.length));
      setLoading(false);
    }, 800);
  }, [loading, hasMore]);

  return (
    <div className={styles.Field}>
      <Listbox.Root loading={loading} onLoadMore={hasMore ? handleLoadMore : undefined}>
        <Listbox.Label className={styles.Label}>Library</Listbox.Label>
        <Listbox.List className={styles.List}>
          {items.map(({ title, value }) => (
            <Listbox.Item key={value} value={value} className={styles.Item}>
              <Listbox.ItemIndicator className={styles.ItemIndicator}>
                <CheckIcon className={styles.ItemIndicatorIcon} />
              </Listbox.ItemIndicator>
              <Listbox.ItemText className={styles.ItemText}>{title}</Listbox.ItemText>
            </Listbox.Item>
          ))}
          {hasMore && (
            <Listbox.LoadingTrigger className={styles.Loading}>
              {loading ? 'Loading...' : 'Scroll for more'}
            </Listbox.LoadingTrigger>
          )}
        </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>
  );
}

Wrap reorderable content in Listbox.DragAndDropProvider and provide onItemsReorder on the provider. Use the provider’s canDrag and canDrop predicates to control which items can be dragged or dropped, and use Listbox.ItemDragHandle to restrict drag initiation to a handle. Items can also be reordered with the keyboard using Alt + Arrow keys.

Use canDrop to constrain reordering within a Listbox.Group or apply other custom drop rules.

In multiple or explicit-multiple mode, dragging a selected item moves all selected items together, preserving their relative order.

Queue

index.tsx index.module.css

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

const initialItems = [
  { 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' },
  { title: 'Superstition', artist: 'Stevie Wonder', value: 'superstition' },
  { title: 'Dancing Queen', artist: 'ABBA', value: 'dancing-queen' },
];

export default function ExampleListboxDragAndDrop() {
  const [items, setItems] = React.useState(initialItems);

  return (
    <div className={styles.Field}>
      <Listbox.Root defaultValue={['bohemian-rhapsody']}>
        <Listbox.Label className={styles.Label}>Queue</Listbox.Label>
        <Listbox.DragAndDropProvider
          onItemsReorder={(event) => {
            setItems((prev) => {
              const movedValues = new Set(event.items);
              const movedItems = prev.filter((item) => movedValues.has(item.value));
              const rest = prev.filter((item) => !movedValues.has(item.value));
              const refIndex = rest.findIndex((item) => item.value === event.referenceItem);
              rest.splice(event.edge === 'after' ? refIndex + 1 : refIndex, 0, ...movedItems);
              return rest;
            });
          }}
        >
          <Listbox.List className={styles.List}>
            {items.map(({ title, artist, value }) => (
              <Listbox.Item key={value} value={value} className={styles.Item}>
                <Listbox.ItemDragHandle className={styles.DragHandle}>
                  <GripIcon />
                </Listbox.ItemDragHandle>
                <Listbox.ItemIndicator className={styles.ItemIndicator}>
                  <CheckIcon className={styles.ItemIndicatorIcon} />
                </Listbox.ItemIndicator>
                <Listbox.ItemText className={styles.ItemText}>
                  <span className={styles.ItemTitle}>{title}</span>
                  <span className={styles.ItemArtist}>{artist}</span>
                </Listbox.ItemText>
              </Listbox.Item>
            ))}
          </Listbox.List>
        </Listbox.DragAndDropProvider>
      </Listbox.Root>
    </div>
  );
}

function GripIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="8" height="14" viewBox="0 0 8 14" fill="currentcolor" {...props}>
      <circle cx="2" cy="2" r="1.25" />
      <circle cx="6" cy="2" r="1.25" />
      <circle cx="2" cy="7" r="1.25" />
      <circle cx="6" cy="7" r="1.25" />
      <circle cx="2" cy="12" r="1.25" />
      <circle cx="6" cy="12" r="1.25" />
    </svg>
  );
}

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>
  );
}

Drag within groups

Pass canDrop to Listbox.DragAndDropProvider to keep reordering inside the current Listbox.Group. This example only accepts drops when every dragged item belongs to the same group as the target item.

The same canDrop callback can also enforce other drop target rules, such as preventing drops around locked items or only allowing certain item types to be reordered next to each other. Because it receives the dragged items, the target item, and the drop edge, you can use it to express custom placement logic in one place.

Playlist

index.tsx index.module.css

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

interface Item {
  title: string;
  artist: string;
  value: string;
  group: string;
}

const initialItems: Item[] = [
  { title: 'Billie Jean', artist: 'Michael Jackson', value: 'billie-jean', group: 'Pop' },
  { title: 'Dancing Queen', artist: 'ABBA', value: 'dancing-queen', group: 'Pop' },
  { title: 'Like a Prayer', artist: 'Madonna', value: 'like-a-prayer', group: 'Pop' },
  { title: 'Hotel California', artist: 'Eagles', value: 'hotel-california', group: 'Rock' },
  {
    title: 'Smells Like Teen Spirit',
    artist: 'Nirvana',
    value: 'smells-like-teen-spirit',
    group: 'Rock',
  },
  { title: 'Back in Black', artist: 'AC/DC', value: 'back-in-black', group: 'Rock' },
];

export default function ExampleListboxDragWithinGroups() {
  const [items, setItems] = React.useState(initialItems);
  const groups = React.useMemo(() => groupItems(items), [items]);

  return (
    <div className={styles.Field}>
      <Listbox.Root defaultValue={['billie-jean']}>
        <Listbox.Label className={styles.Label}>Playlist</Listbox.Label>
        <Listbox.DragAndDropProvider
          canDrop={(sourceItems, targetItem) =>
            sourceItems.every((item) => item.groupId === targetItem.groupId)
          }
          onItemsReorder={(event) => {
            setItems((prev) => reorderItems(prev, event));
          }}
        >
          <Listbox.List className={styles.List}>
            {groups.map((group) => (
              <Listbox.Group key={group.label} className={styles.Group}>
                <Listbox.GroupLabel className={styles.GroupLabel}>{group.label}</Listbox.GroupLabel>
                {group.items.map(({ title, artist, value }) => (
                  <Listbox.Item key={value} value={value} className={styles.Item}>
                    <Listbox.ItemDragHandle className={styles.DragHandle}>
                      <GripIcon />
                    </Listbox.ItemDragHandle>
                    <Listbox.ItemIndicator className={styles.ItemIndicator}>
                      <CheckIcon className={styles.ItemIndicatorIcon} />
                    </Listbox.ItemIndicator>
                    <Listbox.ItemText className={styles.ItemText}>
                      <span className={styles.ItemTitle}>{title}</span>
                      <span className={styles.ItemArtist}>{artist}</span>
                    </Listbox.ItemText>
                  </Listbox.Item>
                ))}
              </Listbox.Group>
            ))}
          </Listbox.List>
        </Listbox.DragAndDropProvider>
      </Listbox.Root>
    </div>
  );
}

function groupItems(items: Item[]) {
  const groups: Array<{ label: string; items: Item[] }> = [];

  for (const item of items) {
    const lastGroup = groups.at(-1);

    if (lastGroup?.label === item.group) {
      lastGroup.items.push(item);
      continue;
    }

    groups.push({ label: item.group, items: [item] });
  }

  return groups;
}

function reorderItems(
  items: Item[],
  event: {
    items: string[];
    referenceItem: string;
    edge: 'before' | 'after';
  },
) {
  const movedValues = new Set(event.items);
  const movedItems = items.filter((item) => movedValues.has(item.value));
  const rest = items.filter((item) => !movedValues.has(item.value));
  const referenceIndex = rest.findIndex((item) => item.value === event.referenceItem);

  rest.splice(event.edge === 'after' ? referenceIndex + 1 : referenceIndex, 0, ...movedItems);

  return rest;
}

function GripIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg width="8" height="14" viewBox="0 0 8 14" fill="currentcolor" {...props}>
      <circle cx="2" cy="2" r="1.25" />
      <circle cx="6" cy="2" r="1.25" />
      <circle cx="2" cy="7" r="1.25" />
      <circle cx="6" cy="7" r="1.25" />
      <circle cx="2" cy="12" r="1.25" />
      <circle cx="6" cy="12" r="1.25" />
    </svg>
  );
}

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>
  );
}

Custom keyboard shortcuts

You can add custom keyboard shortcuts by handling onKeyDown on Listbox.List and updating the items array directly. This example uses ] and [ to move the focused item to the beginning or the end of the list.

Layers

index.tsx index.module.css

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

type IconType = 'image' | 'text' | 'component';

const initialItems = [
  { label: 'Header', value: 'header', icon: 'text' as IconType },
  { label: 'Hero image', value: 'hero-image', icon: 'image' as IconType },
  { label: 'Body text', value: 'body-text', icon: 'text' as IconType },
  { label: 'Call to action', value: 'call-to-action', icon: 'component' as IconType },
  { label: 'Background', value: 'background', icon: 'image' as IconType },
];

function reorder(
  prev: typeof initialItems,
  event: { items: string[]; referenceItem: string; edge: 'before' | 'after' },
) {
  const movedValues = new Set(event.items);
  const movedItems = prev.filter((item) => movedValues.has(item.value));
  const rest = prev.filter((item) => !movedValues.has(item.value));
  const refIndex = rest.findIndex((item) => item.value === event.referenceItem);
  rest.splice(event.edge === 'after' ? refIndex + 1 : refIndex, 0, ...movedItems);
  return rest;
}

export default function ExampleListboxCustomShortcuts() {
  const [items, setItems] = React.useState(initialItems);
  const actionsRef = React.useRef<ListboxRootActions<string>>(null);
  const highlightedRef = React.useRef<{ value: string; element: HTMLElement } | null>(null);

  function handleKeyDown(event: React.KeyboardEvent) {
    const highlighted = highlightedRef.current;
    if (!highlighted) {
      return;
    }

    if (event.key === ']') {
      event.preventDefault();
      const first = items[0];
      if (!first || first.value === highlighted.value) {
        return;
      }
      setItems((prev) =>
        reorder(prev, {
          items: [highlighted.value],
          referenceItem: first.value,
          edge: 'before',
        }),
      );
      actionsRef.current?.highlightValue(highlighted.value, highlighted.element);
    }

    if (event.key === '[') {
      event.preventDefault();
      const last = items[items.length - 1];
      if (!last || last.value === highlighted.value) {
        return;
      }
      setItems((prev) =>
        reorder(prev, {
          items: [highlighted.value],
          referenceItem: last.value,
          edge: 'after',
        }),
      );
      actionsRef.current?.highlightValue(highlighted.value, highlighted.element);
    }
  }

  return (
    <div className={styles.Field}>
      <Listbox.Root
        defaultValue={['header']}
        actionsRef={actionsRef}
        onHighlightChange={(value, element) => {
          highlightedRef.current = value != null && element != null ? { value, element } : null;
        }}
      >
        <Listbox.Label className={styles.Label}>Layers</Listbox.Label>
        <Listbox.DragAndDropProvider
          onItemsReorder={(event) => setItems((prev) => reorder(prev, event))}
        >
          <Listbox.List className={styles.List} onKeyDown={handleKeyDown}>
            {items.map(({ label, value, icon }) => (
              <Listbox.Item key={value} value={value} className={styles.Item}>
                <LayerIcon type={icon} className={styles.LayerIcon} />
                <Listbox.ItemText className={styles.ItemText}>{label}</Listbox.ItemText>
              </Listbox.Item>
            ))}
          </Listbox.List>
        </Listbox.DragAndDropProvider>
      </Listbox.Root>
    </div>
  );
}

const iconPaths: Record<IconType, React.ReactNode> = {
  image: (
    <React.Fragment>
      <rect width="18" height="18" x="3" y="3" rx="2" ry="2" />
      <circle cx="9" cy="9" r="2" />
      <path d="m21 15-3.086-3.086a2 2 0 00-2.828 0L6 21" />
    </React.Fragment>
  ),
  text: (
    <React.Fragment>
      <path d="m15 16 2.536-7.328a1.02 1.02 0 011.928 0L22 16" />
      <path d="M15.697 14h5.606" />
      <path d="m2 16 4.039-9.69a.5.5 0 01.923 0L11 16" />
      <path d="M3.304 13h6.392" />
    </React.Fragment>
  ),
  component: (
    <React.Fragment>
      <path d="M15.536 11.293a1 1 0 000 1.414l2.376 2.377a1 1 0 001.414 0l2.377-2.377a1 1 0 000-1.414l-2.377-2.377a1 1 0 00-1.414 0z" />
      <path d="M2.297 11.293a1 1 0 000 1.414l2.377 2.377a1 1 0 001.414 0l2.377-2.377a1 1 0 000-1.414L6.088 8.916a1 1 0 00-1.414 0z" />
      <path d="M8.916 17.912a1 1 0 000 1.415l2.377 2.376a1 1 0 001.414 0l2.377-2.376a1 1 0 000-1.415l-2.377-2.376a1 1 0 00-1.414 0z" />
      <path d="M8.916 4.674a1 1 0 000 1.414l2.377 2.376a1 1 0 001.414 0l2.377-2.376a1 1 0 000-1.414l-2.377-2.377a1 1 0 00-1.414 0z" />
    </React.Fragment>
  ),
};

function LayerIcon({ type, ...props }: React.ComponentProps<'svg'> & { type: IconType }) {
  return (
    <svg
      width="24"
      height="24"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      strokeWidth="2"
      strokeLinecap="round"
      strokeLinejoin="round"
      {...props}
    >
      {iconPaths[type]}
    </svg>
  );
}

API reference

Root

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

namestring—

Name: name
Description: Identifies the field when a form is submitted.
Type: string | undefined

defaultValueValue[]—

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[] | undefined

valueValue[]—

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

onValueChangefunction—

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

highlightItemOnHoverbooleantrue

Name: highlightItemOnHover
Description: Whether moving the pointer over items should highlight them.
Type: boolean | undefined
Default: true

actionsRefReact.Ref<Listbox.Root.Actions<Value>>—

Name: actionsRef
Description: A ref to imperative actions.
Type: React.Ref<Listbox.Root.Actions<Value>> | undefined

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: Converts an object value to a string label for display.
Type: ((itemValue: Value) => string) | undefined

itemToStringValuefunction—

Name: itemToStringValue
Description: Converts an object value to a string representation for form submission.
Type: ((itemValue: Value) => string) | undefined

loadingbooleanfalse

Name: loading
Description: Whether items are currently being loaded.
Type: boolean | undefined
Default: false

loopFocusbooleantrue

Name: loopFocus
Description: Whether keyboard navigation loops back to the first/last item.
Type: boolean | undefined
Default: true

onHighlightChangefunction—

Name: onHighlightChange
Description: Event handler called when the highlighted item changes. Receives the highlighted item’s value and DOM element, or null for both when no item is highlighted.
Type: | (( value: Value | null, element: HTMLElement | null, ) => void) | undefined

onLoadMorefunction—

Name: onLoadMore
Description: Event handler called when more items should be loaded.
Type: (() => void) | undefined

selectionModeSelectionMode'single'

Name: selectionMode
Description: Determines how user interactions affect the selection.

'single' — Only one item can be selected at a time.

'multiple' — Clicking toggles items. Shift+Click selects a range.

'explicit-multiple' — Like a file browser: plain click replaces the selection, Ctrl/Cmd+Click toggles, Shift+Click selects a range.
Type: SelectionMode | undefined
Default: 'single'

disabledbooleanfalse

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

requiredbooleanfalse

Name: required
Description: Whether the user must choose a value before submitting a form.
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'

inputRefReact.Ref<HTMLInputElement>—

Name: inputRef
Description: A ref to access the hidden input element.
Type: React.Ref<HTMLInputElement> | undefined

idstring—

Name: id
Description: The id of the Listbox.
Type: string | undefined

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.ActionsHide

type ListboxRootActions<Value> = {
  /**
   * Sets the highlighted item by value. Focuses the item and scrolls it into view.
   * Useful when reordering items externally and needing to restore highlight.
   *
   * When called after a reorder, pass the item's DOM element as the second
   * argument for reliable matching — the element reference survives React's
   * keyed reconciliation even when its position changes.
   */
  highlightValue: (value: Value, element?: HTMLElement | null) => void;
}

Listbox.Root.ChangeEventReasonHide

type ListboxRootChangeEventReason = 'item-press' | 'list-navigation' | 'none'

Listbox.Root.ChangeEventDetailsHide

type ListboxRootChangeEventDetails = (
  | { reason: 'item-press'; event: MouseEvent | KeyboardEvent | PointerEvent }
  | { reason: 'list-navigation'; event: KeyboardEvent }
  | { reason: 'none'; event: Event }
) & {
  /** 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;
}

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: FieldRootState) => 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: FieldRootState, ) => 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: FieldRootState, ) => ReactElement) | undefined

Listbox.Label.PropsHide

Re-Export of Label props as ListboxLabelProps

Listbox.Label.StateHide

type ListboxLabelState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
}

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';
}

DragAndDropProvider

Enables drag-and-drop reordering when rendered inside Listbox.Root. Renders no DOM element of its own.

canDragfunction—

Name: canDrag
Description: Determines whether a given item can initiate drag-and-drop. Defaults to allowing all non-disabled items.
Type: | ((item: ListboxDragAndDropItem<Value>) => boolean) | undefined

canDropfunction—

Name: canDrop
Description: Determines whether the dragged items can be dropped relative to a target item. Defaults to allowing all drops.
Type: | (( sourceItems: ListboxDragAndDropItem<Value>[], targetItem: ListboxDragAndDropItem<Value>, edge: 'before' | 'after', ) => boolean) | undefined

onItemsReorderfunction—

Name: onItemsReorder
Description: Event handler called when items are reordered via drag-and-drop or keyboard. items contains the moved item(s). referenceItem is the item that was dropped on or moved next to, and edge indicates placement relative to it.
Type: | (( event: ListboxDragAndDropProviderOnItemsReorderEvent<Value>, ) => void) | undefined

childrenReact.ReactNode—

Name: children
Type: React.ReactNode | undefined

Listbox.DragAndDropProvider.PropsHide

Re-Export of DragAndDropProvider props as ListboxDragAndDropProviderProps

Listbox.DragAndDropProvider.StateHide

type ListboxDragAndDropProviderState = {}

Item

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

labelstring—

Name: label
Description: Specifies the text label to use when the item is matched during keyboard text navigation.
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-dragging

Present when the listbox item is being dragged.

data-disabled

Present when the listbox item is disabled.

data-drop-target

Present when the listbox item is a drop target.

data-drop-target-edge

Indicates the closest edge when the item is a drop target. The value is 'before' or 'after'.

Attribute	Description	-
`data-selected`	Present when the listbox item is selected.
`data-highlighted`	Present when the listbox item is highlighted.
`data-dragging`	Present when the listbox item is being dragged.
`data-disabled`	Present when the listbox item is disabled.
`data-drop-target`	Present when the listbox item is a drop target.
`data-drop-target-edge`	Indicates the closest edge when the item is a drop target. The value is `'before'` or `'after'`.

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;
  /** Whether the item is currently being dragged. */
  dragging: boolean;
  /** Whether the item is a drop target. */
  dropTarget: boolean;
  /** The edge closest to the pointer when the item is a drop target (`'before'` or `'after'`), or `null`. */
  dropTargetEdge: string | null;
}

ItemText

A text label of the listbox item. 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.ItemText.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.ItemText.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.ItemText.State, ) => ReactElement) | undefined

Listbox.ItemText.PropsHide

Re-Export of ItemText props as ListboxItemTextProps

Listbox.ItemText.StateHide

type ListboxItemTextState = {}

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;
}

ItemDragHandle

A drag handle within a listbox item for initiating drag-and-drop reordering. Renders a <div> element.

When placed inside a Listbox.Item within Listbox.DragAndDropProvider, the drag operation will be restricted to start only from this handle whenever the provider allows dragging for that item.

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.ItemDragHandle.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.ItemDragHandle.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.ItemDragHandle.State, ) => ReactElement) | undefined

Listbox.ItemDragHandle.PropsHide

Re-Export of ItemDragHandle props as ListboxItemDragHandleProps

Listbox.ItemDragHandle.StateHide

type ListboxItemDragHandleState = {}

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 = {}

LoadingTrigger

A sentinel element that triggers loading more items when scrolled into view. Renders a <div> element.

Place at the end of the listbox items. When it becomes visible in the scrollable list container, the onLoadMore callback on Listbox.Root is called.

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.LoadingTrigger.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.LoadingTrigger.State, ) => React.CSSProperties | undefined) | undefined

keepMountedboolean—

Name: keepMounted
Description: Whether to keep the HTML element in the DOM when not loading.
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.LoadingTrigger.State, ) => ReactElement) | undefined

Listbox.LoadingTrigger.PropsHide

Re-Export of LoadingTrigger props as ListboxLoadingTriggerProps

Listbox.LoadingTrigger.StateHide

type ListboxLoadingTriggerState = {
  /** Whether items are currently being loaded. */
  loading: boolean;
}