Dice UI

Installation

npm install @diceui/listbox

Installation with shadcn/ui

CLI

npx shadcn@latest add "https://diceui.com/r/listbox"

Manual

Install the following dependencies:

npm install @diceui/listbox

Copy and paste the following code into your project.

import { cn } from "@/lib/utils";
import * as ListboxPrimitive from "@diceui/listbox";
import { Check } from "lucide-react";
import * as React from "react";
 
const Listbox = React.forwardRef<
  React.ComponentRef<typeof ListboxPrimitive.Root>,
  React.ComponentPropsWithoutRef<typeof ListboxPrimitive.Root>
>(({ className, orientation = "vertical", ...props }, ref) => (
  <ListboxPrimitive.Root
    data-slot="listbox"
    ref={ref}
    orientation={orientation}
    className={cn(
      "flex gap-2 focus-visible:outline-none",
      orientation === "vertical" &&
        "flex-col *:data-[slot=listbox-group]:flex-col",
      className,
    )}
    {...props}
  />
)) as ListboxPrimitive.ListboxRootComponentProps;
Listbox.displayName = ListboxPrimitive.Root.displayName;
 
const ListboxGroup = React.forwardRef<
  React.ComponentRef<typeof ListboxPrimitive.Group>,
  React.ComponentPropsWithoutRef<typeof ListboxPrimitive.Group>
>(({ className, ...props }, ref) => (
  <ListboxPrimitive.Group
    data-slot="listbox-group"
    ref={ref}
    className={cn("flex flex-col gap-2", className)}
    {...props}
  />
));
ListboxGroup.displayName = ListboxPrimitive.Group.displayName;
 
const ListboxGroupLabel = React.forwardRef<
  React.ElementRef<typeof ListboxPrimitive.GroupLabel>,
  React.ComponentPropsWithoutRef<typeof ListboxPrimitive.GroupLabel>
>(({ className, ...props }, ref) => (
  <ListboxPrimitive.GroupLabel
    data-slot="listbox-group-label"
    ref={ref}
    className={cn(
      "px-2 pt-1 font-medium text-muted-foreground text-sm",
      className,
    )}
    {...props}
  />
));
ListboxGroupLabel.displayName = ListboxPrimitive.GroupLabel.displayName;
 
const ListboxItem = React.forwardRef<
  React.ComponentRef<typeof ListboxPrimitive.Item>,
  React.ComponentPropsWithoutRef<typeof ListboxPrimitive.Item>
>(({ className, ...props }, ref) => (
  <ListboxPrimitive.Item
    data-slot="listbox-item"
    ref={ref}
    className={cn(
      "flex w-full cursor-default select-none items-center justify-between gap-2 rounded-md p-4 outline-hidden ring-1 ring-border focus-visible:ring-ring data-disabled:pointer-events-none data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:opacity-50",
      className,
    )}
    {...props}
  />
));
ListboxItem.displayName = ListboxPrimitive.Item.displayName;
 
const ListboxItemIndicator = React.forwardRef<
  React.ComponentRef<typeof ListboxPrimitive.ItemIndicator>,
  React.ComponentPropsWithoutRef<typeof ListboxPrimitive.ItemIndicator>
>(({ ...props }, ref) => (
  <ListboxPrimitive.ItemIndicator
    data-slot="listbox-item-indicator"
    ref={ref}
    {...props}
  >
    <Check className="size-4" />
  </ListboxPrimitive.ItemIndicator>
));
ListboxItemIndicator.displayName = ListboxPrimitive.ItemIndicator.displayName;
 
export {
  Listbox,
  ListboxGroup,
  ListboxGroupLabel,
  ListboxItem,
  ListboxItemIndicator,
};

Layout

Import the parts, and compose them together.

import * as Listbox from "@diceui/listbox"
 
<Listbox.Root>
  <Listbox.Group>
    <Listbox.GroupLabel/>
    <Listbox.Item >
      <Listbox.ItemIndicator />
    </Listbox.Item>
  </Listbox.Group>
</Listbox.Root>

Examples

Horizontal Orientation

Set orientation="horizontal" to create a horizontally navigable list.

Grid Layout

For grid layouts, use orientation="mixed" to enable navigation in both directions. Use CSS Grid to arrange the items in a grid structure. In grid layouts, arrow keys will navigate accordingly:

Up/Down: Navigates within a column
Left/Right: Navigates within a row

Grouped Items

Group items together to create a list of related options.

API Reference

Root

The root component for creating listboxes.

Prop	Type	Default
`defaultValue?`	`Value<Multiple>`	-
`value?`	`Value<Multiple>`	-
`onValueChange?`	`(value: Value<Multiple>) => void`	-
`asChild?`	`boolean`	-
`disabled?`	`boolean`	-
`loop?`	`boolean`	-
`multiple?`	`Multiple`	-
`virtual?`	`boolean`	-
`orientation?`	`"horizontal" \| "vertical" \| "mixed"`	-
`name?`	`string`	-

Group

A group of items inside the selectable list.

Prop	Type	Default
`asChild?`	`boolean`	-

GroupLabel

A label for the group of items.

Prop	Type	Default
`asChild?`	`boolean`	-

Item

An item inside the selectable list.

Prop	Type	Default
`onSelect?`	`(value: string) => void`	-
`value`	`string`	-
`disabled?`	`boolean`	-
`asChild?`	`boolean`	-

ItemIndicator

A visual indicator that shows when the item is selected.

Prop	Type	Default
`forceMount?`	`boolean`	-
`asChild?`	`boolean`	-

Accessibility

Keyboard Interactions

Key	Description
`Tab`	Focuses the last active item in the list.
`Shift + Tab`	Moves focus to previous focusable item in the list.
`ArrowUp`	Moves highlighting to previous item in vertical lists.
`ArrowDown`	Moves highlighting to next item in vertical lists.
`ArrowLeft`	Moves highlighting to previous item in horizontal lists.
`ArrowRight`	Moves highlighting to next item in horizontal lists.

Listbox

On this page