Components

Listbox

A selectable list of options with support for single or multiple selection. Items can include icons and descriptions.

Installation

npm install @trinkui/react

Import

import { Listbox } from "@trinkui/react";

Single Selection

Click an item to select it. Only one item can be active at a time.

Framework

Selected: react

const [selected, setSelected] = useState(new Set(["react"]));

<Listbox
  items={[
    { key: "react", label: "React" },
    { key: "vue", label: "Vue" },
    { key: "angular", label: "Angular" },
    { key: "svelte", label: "Svelte" },
    { key: "solid", label: "Solid" },
  ]}
  selectedKeys={selected}
  onSelectionChange={setSelected}
  selectionMode="single"
/>

Multiple Selection

Click items to toggle them. Multiple items can be selected simultaneously.

Frameworks (multi-select)

Selected: docs, media

<Listbox
  items={items}
  selectedKeys={selected}
  onSelectionChange={setSelected}
  selectionMode="multiple"
/>

With Icons and Descriptions

Items can include an icon and description text for richer content.

File browser

Selected: projects

<Listbox
  items={[
    { key: "docs", label: "Documents", description: "Word, PDF, and text files", icon: <FileIcon /> },
    { key: "projects", label: "Projects", description: "Source code and repos", icon: <FolderIcon /> },
    { key: "media", label: "Media", description: "Images, videos, and audio", icon: <ImageIcon /> },
  ]}
  selectedKeys={selected}
  onSelectionChange={setSelected}
/>

Bordered Variant

Use variant="bordered" for a bordered container instead of a shadow.

Pick a framework

<Listbox
  variant="bordered"
  items={items}
  selectedKeys={selected}
  onSelectionChange={setSelected}
/>

Props

Prop	Type	Default	Description
items	ListboxItem[]	--	Array of items with key, label, optional description and icon
selectedKeys	Set<string>	--	Set of currently selected item keys
onSelectionChange	(keys: Set<string>) => void	--	Callback when the selection changes
selectionMode	"single" \| "multiple"	"single"	Whether to allow one or many selected items
variant	"default" \| "bordered"	"default"	Visual variant: shadow (default) or bordered

Accessibility

Uses role="listbox" on the container with role="option" on each item.
Multi-select listboxes have aria-multiselectable="true".
Each option uses aria-selected to communicate state.
Items are focusable and support Enter and Space key to toggle selection.
Focus ring is visible when navigating with keyboard.

← Link Modal →