Data

ListBox

Selectable list following the WAI-ARIA listbox pattern with single, multiple or no selection and roving-tabindex keyboard navigation.

Import

import { ListBox, ListBoxItem } from "@zephora/react";

Examples

Single selection

<ListBox aria-label="Favorite language" defaultValue="ts">
  <ListBoxItem value="js">JavaScript</ListBoxItem>
  <ListBoxItem value="ts">TypeScript</ListBoxItem>
  <ListBoxItem value="rs">Rust</ListBoxItem>
</ListBox>

Multiple with descriptions

In `selectionMode="multiple"` the callback fires with a `string[]`. Disabled items are skipped by keyboard navigation.

Selected: email

const [value, setValue] = React.useState<string[]>(["email"]);

<ListBox
  aria-label="Notification channels"
  selectionMode="multiple"
  value={value}
  onValueChange={(next) => setValue(Array.isArray(next) ? next : next ? [next] : [])}
>
  <ListBoxItem value="email" description="Daily digest at 9:00">Email</ListBoxItem>
  <ListBoxItem value="push" description="Instant on your devices">Push</ListBoxItem>
  <ListBoxItem value="sms" description="Requires a verified number" disabled>SMS</ListBoxItem>
</ListBox>

API

ListBox props

Prop	Type	Default	Description
`selectionMode`	`"none" \| "single" \| "multiple"`	`"single"`	Selection behavior; "none" renders a plain list.
`value`	`string \| string[] \| null`	—	Controlled value: `string \| null` (single) or `string[]` (multiple).
`defaultValue`	`string \| string[] \| null`	—	Uncontrolled initial value.
`onValueChange`	`(value: string \| string[] \| null) => void`	—	Fires with `string \| null` (single) or `string[]` (multiple).
`unstyled`	`boolean`	`false`	Headless mode — skips Zephora styling.

ListBoxItem props

Prop	Type	Default	Description
`value` *	`string`	—	Unique option value.
`disabled`	`boolean`	`false`	Removes the option from selection and keyboard navigation.
`description`	`ReactNode`	—	Secondary line rendered under the label.
`unstyled`	`boolean`	—	Headless mode — inherits from the parent ListBox by default.

Keyboard

Key	Action
`ArrowDown / ArrowUp`	Move focus to the next / previous enabled option.
`Home / End`	Move focus to the first / last enabled option.
`Enter / Space`	Select the focused option (toggles in multiple mode).
`Tab`	Moves focus into / out of the list (roving tabindex).