Listbox

Import

import { Listbox } from "@hope-ui/components/listbox";

Listbox is a compound component — a namespace object whose parts you compose yourself. See the Anatomy below for every part and how they nest.

Usage

Listbox.Root takes your options as items and owns the state (selection, focus, keyboard navigation, type-ahead, ARIA) plus the role="listbox" element. Its child is a render callback invoked once per item — return a Listbox.Item item={item}, with an optional Listbox.ItemIndicator to paint a check on the selected row. Map each item to a stable string with itemToValue (the selection identity) and to its display / type-ahead text with itemToLabel.

Your items are your own objects and stay that way: every question the listbox asks about one is an accessor function, never a required key name.

const [value, setValue] = createSignal<Fruit[]>([]);
 
<Listbox.Root
  aria-label="Choose a fruit"
  items={fruits}
  itemToValue={(fruit) => String(fruit.id)}
  itemToLabel={(fruit) => fruit.name}
  value={value()}
  onChange={setValue}
>
  {(fruit) => (
    <Listbox.Item item={fruit}>
      {fruit.name}
      <Listbox.ItemIndicator />
    </Listbox.Item>
  )}
</Listbox.Root>;

Anatomy

Listbox.Root renders the list element and invokes your callback once per items entry; Listbox.Item is one option (with an optional Listbox.ItemIndicator check inside). Listbox.Group + Listbox.GroupLabel name a section, and Listbox.Separator divides sections — all three appear once you set groupToItems (see Groups), and none of them are available in virtual mode, which is flat.

Selection modes

selectionMode controls how many options can be chosen at once:

• single (default): one option; choosing another replaces it. (shown in Usage above)
• multiple: a set; Space or a click toggles each. Shift+Arrow extends the selection and ⌘/Ctrl+A selects all.
• none: nothing is ever selected; arrows and type-ahead still move the highlight — a browsing or command list.

Selection is an array in every mode (onChange receives V[]), and the value items are your own objects — Listbox never forces you to key by string.

<Listbox.Root selectionMode="multiple" value={value()} onChange={setValue}>
  {/* … */}
</Listbox.Root>

<Listbox.Root selectionMode="none">{/* … */}</Listbox.Root>

Groups and separators

Set groupToItems and items becomes your group entries: it flattens them into navigation order, which is the only thing the listbox needs from a group. Your callback then goes one level up — it is invoked per group, and you iterate that group’s own items with a plain <For>.

The group’s name never reaches the listbox: you render it from your own key, which is why there is no groupToLabel and no { label, items } shape to conform to. Wrap each section in a Listbox.Group with a Listbox.GroupLabel, and divide them with a Listbox.Separator. The group is a role="group" named by its label (aria-labelledby); the separator is decorative (role="presentation"). Keyboard navigation flows across groups as one list — arrows skip the labels and the separator. Grouping is data mode only — a virtual listbox is flat.

// Nested straight from your API — no remapping, no required key names.
// [{ kind: "Citrus", fruits: [{ id, name }, …] }, …]
 
<Listbox.Root
  aria-label="Choose a fruit"
  items={baskets}
  groupToItems={(basket) => basket.fruits}
  itemToValue={itemToValue}
  itemToLabel={itemToLabel}
>
  {(basket, index) => (
    <>
      <Show when={index() > 0}>
        <Listbox.Separator />
      </Show>
      <Listbox.Group>
        <Listbox.GroupLabel>{basket.kind}</Listbox.GroupLabel>
        <For each={basket.fruits}>
          {(fruit) => <FruitItem fruit={fruit} />}
        </For>
      </Listbox.Group>
    </>
  )}
</Listbox.Root>

Sizes

The size prop scales density — the row text, padding, gap, and the panel’s min width — across sm, md (the default), and lg. It carries no color axis; Listbox is a neutral collection surface.

<Listbox.Root size="sm">…</Listbox.Root>
<Listbox.Root size="md">…</Listbox.Root>
<Listbox.Root size="lg">…</Listbox.Root>

Disabled items

Answer isItemDisabled and the matching rows are dimmed and skipped by keyboard navigation and type-ahead. It is a data question, like every other one here, so a row’s disabled state is known before it ever mounts — which is what lets a closed Select skip it. skipDisabled (default true) governs the skipping; set it false to let the highlight land on disabled rows — they still can’t be selected. Disable the whole list with disabled on Listbox.Root.

<Listbox.Root isItemDisabled={(fruit) => fruit.outOfSeason}>
  {(fruit) => (
    <Listbox.Item item={fruit}>
      {fruit.name}
      <Listbox.ItemIndicator />
    </Listbox.Item>
  )}
</Listbox.Root>

Virtualization

For lists of thousands of rows, add estimateSize and the same callback child becomes per windowed row, returning a Listbox.Item index={index} — a recycled row’s position is the only thing it knows, so it is told rather than resolving its own. The list element becomes the scroll container; only a window of rows mounts, so the 10,000 rows below scroll and navigate at full frame rate — try End, or type to jump to a row. Selection, focus, and type-ahead all run over the full set, so offscreen selections survive scrolling and submit with a form.

const items = Array.from({ length: 10_000 }, (_, i) => ({
  id: i,
  name: `Item ${i}`,
}));
 
<Listbox.Root
  aria-label="Ten thousand rows"
  // Pure sizing: the fixed height/width makes the list a scroll viewport.
  class="h-72 w-56"
  items={items}
  estimateSize={() => 32}
  itemToValue={(item) => String(item.id)}
  itemToLabel={(item) => item.name}
>
  {(item, index) => (
    <Listbox.Item index={index} style={{ height: "2rem" }}>
      {item.name}
      <Listbox.ItemIndicator />
    </Listbox.Item>
  )}
</Listbox.Root>;

Native form submission

Set name and the listbox renders a visually-hidden native <select> beside the list — so a plain <form> submit carries the selection with no extra wiring. The submitted strings are the itemToValue values (here, the fruit ids), and in virtual multi-select even offscreen selections are included. Add form to associate the field with a form by id.

Because it is a real <select> holding one <option> per item, three things come for free that a hidden input cannot give you: the browser can autofill it, required genuinely blocks submission (and moves focus to the list rather than to a control nobody can see), and the form’s reset button puts the selection back to where it started.

<form onSubmit={handleSubmit}>
  <Listbox.Root
    name="fruit"
    selectionMode="multiple"
    items={fruits}
    itemToValue={(f) => String(f.id)}
  >
    {(fruit) => <FruitItem fruit={fruit} />}
  </Listbox.Root>
  <Button type="submit">Submit</Button>
</form>

Focus modes

focusMode decides where DOM focus lives. roving (the default) moves real focus onto the active option and makes it the single tab stop — right for a standalone list. activedescendant keeps focus on the listbox container and points aria-activedescendant at the active option — the model Select and Combobox use, where focus stays on the trigger or input while the arrows drive the list. Tab into each below and arrow through it.

<Listbox.Root focusMode="roving">…</Listbox.Root>
<Listbox.Root focusMode="activedescendant">…</Listbox.Root>

Reading direction (LTR and RTL)

An RTL direction mirrors the list — the check gutter moves to the left edge — and reverses a horizontal listbox’s arrow keys, where ← moves to the next option. A vertical listbox is unaffected: RTL mirrors the inline axis only.

Set dir on your document root (see i18n) and every listbox follows. The wrapper below is only needed because this page shows two directions at once:

<div dir="rtl">
  <I18nProvider locale="ar-EG">
    <Listbox.Root aria-label="اختر فاكهة">…</Listbox.Root>
  </I18nProvider>
</div>

Keyboard interactions

Listbox implements the WAI-ARIA listbox keyboard pattern. Navigation follows orientation (the vertical arrows are shown; a horizontal listbox uses ← / →, reversed under RTL).

Polymorphism

Render a part as a different element or component with the render prop — a function that receives the part’s computed props and spreads them onto your element. Listbox.Item, Listbox.Group, Listbox.GroupLabel, and Listbox.Separator all accept it. There is no as prop; render is the single polymorphism API.

<Listbox.Item item={item} render={(props) => <a href={item.href} {...props} />}>
  {item.name}
  <Listbox.ItemIndicator />
</Listbox.Item>

Theming

Listbox’s look comes from the active preset’s recipe. It is a neutral collection surface — no color axis; the only accents are the transient highlight and the persistent selection, both driven by tokens. Override styling at three levels, applied in order (later wins a Tailwind conflict): recipe base → preset slotClasses → instance slotClasses / part class.

Part slots

Every part carries a data-slot attribute you can target, and each is addressable by name through slotClasses. The root slot deliberately carries no popup chrome — layer the elevated surface yourself (see the note in Usage).

Overriding one listbox

Set slotClasses on Listbox.Root to reach any slot from one place, or put class on an individual part. class on Listbox.Root merges onto the root slot — this is where the elevated-panel look goes. Use literal class strings so your Tailwind build can see them.

<Listbox.Root
  class="rounded-lg border border-subtle bg-surface-overlay shadow-md p-1"
  slotClasses={{ item: "rounded-md", separator: "bg-strong/40" }}
>
  {/* … */}
</Listbox.Root>

App-wide defaults and overrides

Set the default size and global part classes for every Listbox through the theme with definePreset, then pass the derived preset to ThemeProvider. defaultProps resolve at instance ?? preset ?? builtin precedence, so an explicit prop on a single listbox always wins.

import { definePreset } from "@hope-ui/theming";
import { hope } from "@hope-ui/presets/hope";
 
export const myPreset = definePreset(hope, {
  components: {
    listbox: {
      defaultProps: { size: "sm" },
      slotClasses: { root: "rounded-lg border border-subtle shadow-md p-1" },
    },
  },
});

API

Listbox.Root

Listbox.Root<V> is generic in your item type V. It accepts the props below plus every native <div> attribute (aria-label, style, data-*, …) so the list can be named and styled.

Listbox.Item

Provide exactly one of item (the normal case) or index (virtual mode). Plus every native <div> attribute — id is the exception: it is the aria-activedescendant target and is generated for you. Nothing else about the row is declared here; its label, disabled state and value all come from Listbox.Root’s accessors.

Listbox.ItemIndicator

Plus every native <span> attribute. aria-hidden is not one of them — the glyph stays hidden from assistive tech, since the option’s own aria-selected already conveys the selection.

Part props

Listbox.Group, Listbox.GroupLabel, and Listbox.Separator each accept their native <div> attributes plus a render prop and a class. All three belong to the grouped (groupToItems) shape and none are available in virtual mode.

Accessibility

Listbox implements the WAI-ARIA Listbox pattern.

• Roles and state are wired for you. The list is role="listbox", each option role="option" with aria-selected, groups role="group", and the separator role="presentation". Multi-select sets aria-multiselectable on the list.
• Give the list an accessible name. There’s no built-in label, so pass aria-label (or aria-labelledby pointing at your own heading) on Listbox.Root.
• Two focus models. roving moves DOM focus to the active option (the standalone default); activedescendant keeps focus on the container and points aria-activedescendant at the active option — what a trigger-owned Select needs.
• One highlight, keyboard and pointer. Arrows and the pointer share a single active option, so the cursor and the keyboard never paint two highlights; selection (the check) is separate from the transient highlight.
• The highlight follows focus. The active option is highlighted only while the list has focus, so it never lingers after you tab away. Entering the list highlights the selected option if there is one, otherwise the first — and Tab lands there directly.
• Disabled options stay discoverable. A disabled row keeps aria-disabled and, by default, is skipped by navigation; it can never be selected.
• Type-ahead. Typing focuses the next option whose label matches, read from itemToLabel (else itemToValue). Because it comes from your data rather than the rendered text, it reaches rows that have not mounted — an offscreen row in a virtual list, and every option of a closed Select.