@lucid-softworks/listbox

Accessible, unstyled listbox primitives for React.

import { useState, type ReactElement } from "react";

import { Listbox } from "@lucid-softworks/listbox";

export function StatusPicker(): ReactElement {
  const [status, setStatus] = useState("draft");

  return (
    <Listbox.Root value={status} onValueChange={setStatus}>
      <Listbox.Label>Status</Listbox.Label>
      <Listbox.Options>
        <Listbox.Option value="draft">Draft</Listbox.Option>
        <Listbox.Option value="review">In review</Listbox.Option>
        <Listbox.Option value="published">Published</Listbox.Option>
      </Listbox.Options>
    </Listbox.Root>
  );
}

Use defaultValue for uncontrolled state, or value and onValueChange for controlled state. Add multiple to work with an array of selected values.

Keyboard interaction

Arrow keys move through enabled options, Home and End move to the boundaries, typing moves focus to a matching option, and Space or Enter selects the focused option. Multiple listboxes toggle the focused value.

Composition and styling

Listbox.Root, Listbox.Label, Listbox.Options, and Listbox.Option render div, span, listbox, and option elements. They accept the standard props for those elements, so consumers can style them with plain CSS, CSS modules, Tailwind, inline styles, or StyleX.

Selection and disabled state use aria-selected and aria-disabled; keyboard focus uses ordinary :focus. No package-specific selectors or styles are required.