ComboboxListbox

Stable
WCAG 2.2 evidence
RTL

The list of a Combobox. It opens under the field at its width, flips to stay in the viewport and scrolls when long. Focus stays in the text field: the arrow keys, Home/End and Page Up/Down move the active option (aria-activedescendant), Enter selects, Escape closes (WCAG 2.1.1, 4.1.2). The Figma Type is derived from the state, not a prop: Options and Grouped are the options you pass (with SelectSection / SelectGroupLabel), Loading follows isLoading, Empty shows when nothing matches (React Aria announces the number of results), and Create appears with onCreate once text is typed. Consumer duties: option wording, translated empty and loading text, and what "create" does with the typed text.

import { ComboboxListbox } from "@nexera-ui/react";

Loading example…

5
examples: 26
props: 2
live controls: 1
platform: 7
WCAG criteria: 0
blocks use it

Try every prop. Copy the code.

Change the props and the code updates. Check light and dark, LTR and RTL, and phone width.

Loading…

isLoadingfalse

placement

Generated code

import { ComboboxListbox } from "@nexera-ui/react";

<ComboboxListbox />

Examples 4

The same examples as Storybook, rendered live. Open Code to copy one.

Loading

Figma Type=Loading: isLoading with a message; it is announced politely.

Loading example…

app.tsx

import { ComboboxListbox, ComboboxRoot, ComboboxTrigger, FieldLabel } from "@nexera-ui/react";

interface Person {
  id: string;
  name: string;
}

const people: Person[] = [
  { id: "omar", name: "Omar Farooq" },
  { id: "sara", name: "Sara Khan" },
  { id: "ali", name: "Ali Raza" },
  { id: "hina", name: "Hina Malik" },
];

export function Loading() {
  return (
    <div className="min-h-96 w-80 max-w-full">
      <ComboboxRoot items={[]}>
        <FieldLabel>Manager</FieldLabel>
        <ComboboxTrigger placeholder="Search people" />
        <ComboboxListbox />
      </ComboboxRoot>
    </div>
  );
}

Empty

Figma Type=Empty: nothing matches; React Aria announces "0 options available".

Loading example…

app.tsx

import { ComboboxListbox, ComboboxRoot, ComboboxTrigger, FieldLabel } from "@nexera-ui/react";

interface Person {
  id: string;
  name: string;
}

const people: Person[] = [
  { id: "omar", name: "Omar Farooq" },
  { id: "sara", name: "Sara Khan" },
  { id: "ali", name: "Ali Raza" },
  { id: "hina", name: "Hina Malik" },
];

export function Empty() {
  return (
    <div className="min-h-96 w-80 max-w-full">
      <ComboboxRoot items={[]}>
        <FieldLabel>Manager</FieldLabel>
        <ComboboxTrigger placeholder="Search people" />
        <ComboboxListbox />
      </ComboboxRoot>
    </div>
  );
}

Create

Figma Type=Create: type text that is not in the list to see the Create option.

Loading example…

app.tsx

import { ComboboxListbox, SelectOption } from "@nexera-ui/react";

interface Person {
  id: string;
  name: string;
}

<ComboboxListbox onCreate={() => undefined}>
  {(person: Person) => <SelectOption id={person.id} label={person.name} />}
</ComboboxListbox>;

Right to left

Right-to-left: rows, group labels and the footer mirror.

Loading example…

app.tsx

import { ComboboxListbox, SelectOption } from "@nexera-ui/react";

interface Person {
  id: string;
  name: string;
}

<ComboboxListbox keyboardHints={{ navigate: "تنقل", select: "اختيار", close: "إغلاق" }}>
  {(person: Person) => <SelectOption id={person.id} label={person.name} />}
</ComboboxListbox>;

Props 26

Press "Try it" on a card to load that prop into the playground.

children*Nexera

ReactNode | ((item: T) => ReactNode)

The options: SelectOption elements (optionally grouped in SelectSection with a SelectGroupLabel), or a function that renders one option per item of the combobox's items / defaultItems.

isLoadingNexera

boolean

Shows the Figma Loading row (a spinner and loadingLabel) at the end of the list while results load, instead of the empty state. The message is announced politely when loading starts (WCAG 4.1.3).

loadingLabelNexera

string

Text of the loading row, for example "Searching 128 people". Translate it for your locale.

emptyTitleNexera

ReactNode | ((inputValue: string) => ReactNode)

Title of the Figma Empty state, shown when no option matches. A function receives the typed text. React Aria also announces "0 options available" (WCAG 4.1.3). Translate it for your locale.

emptyDescriptionNexera

ReactNode

Hint under the empty title.

onCreateNexera

(inputValue: string) => void

Shows the Figma Create option for the typed text and is called with that text when it is chosen (click, Enter or Tab). Needs Combobox or ComboboxRoot around the list.

createLabelNexera

(inputValue: string) => ReactNode

Label of the Create option. Translate it for your locale.

keyboardHintsNexera

false | ComboboxKeyboardHints

Words of the Figma Footer keyboard hints (↑↓ navigate, ↵ select, esc close), or false to leave the footer out (for example on touch devices). The footer is visual only; screen readers get the same information from the combobox role.

placementNexera

"bottom" | "bottom left" | "bottom right" | "bottom start" | "bottom end" | "top" | "top left" | "top right" | "top start" | "top end" | "left" | "left top" | "left bottom" | "start" | "start top" | "start bottom" | "right" | "right top" | "right bottom" | "end" | "end top" | "end bottom"

Where the list opens relative to the field. It flips to stay inside the viewport.

offsetNexera

number

Distance in px between the field and the list (UNVERIFIED).

classNameNexera

string

Extra classes for the list surface, merged last so they win over the defaults.

styleNexera

CSSProperties

Inline style for the list surface.

shouldSelectOnPressUpReact Aria

boolean

Whether selection should occur on press up instead of press down.

shouldFocusOnHoverReact Aria

boolean

Whether options should be focused when the user hovers over them.

onActionReact Aria

(key: Key) => void

Handler that is called when a user performs an action on an item. The exact user event depends on the collection's selectionBehavior prop and the interaction modality.

escapeKeyBehaviorReact Aria

"clearSelection" | "none"

Whether pressing the escape key should clear selection in the listbox or not. Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually.

autoFocusReact Aria

boolean | FocusStrategy

Whether to auto focus the listbox or an option.

shouldFocusWrapReact Aria

boolean

Whether focus should wrap around when the end/start is reached.

itemsReact Aria

Iterable<T>

Item objects in the collection.

disabledKeysReact Aria

Iterable<Key>

The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.

disallowEmptySelectionReact Aria

boolean

Whether the collection allows empty selection.

idReact Aria

string

The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).

aria-labelReact Aria

string

Defines a string value that labels the current element.

aria-labelledbyReact Aria

string

Identifies the element (or elements) that labels the current element.

aria-describedbyReact Aria

string

Identifies the element (or elements) that describes the object.

dependenciesReact Aria

readonly any[]

Values that should invalidate the item cache when using dynamic collections.

* Required. React Aria props shown are the ones most apps use; the component accepts the rest of its React Aria props too.

Accessible by default.

Built on React Aria, and covered by the WCAG 2.2 evidence generated on every build.

WCAG 2.2 evidence

4 direct · 3 supporting

1.3.1Info and RelationshipsLevel A · tested directly
1.4.10ReflowLevel AA · supporting test
1.4.12Text SpacingLevel AA · supporting test
2.1.1KeyboardLevel A · tested directly
2.3.3Animation from InteractionsLevel AAA · supporting test
4.1.2Name, Role, ValueLevel A · tested directly
4.1.3Status MessagesLevel AA · tested directly

Fits any width.

Nexera components respond to the space they are given. Drag the corner of the frame, or pick a width.

0 px · drag the corner

Styling hooks

Pass className to add Tailwind classes (merged last). State is exposed as data attributes, so you can style it with variants like data-pressed:.

data-focused
data-hovered

Usage

<ComboboxListbox className="data-focused:opacity-90 shadow-sm" />

Used in blocks

No block uses ComboboxListbox yet.

Theme studio

ComboboxListbox

Try every prop. Copy the code.

Examples 4

Loading

Empty

Create

Right to left

Props 26

Accessible by default.

WCAG 2.2 evidence

Fits any width.

Styling hooks

Used in blocks

Related components