Shim

ListBox

Display a list of selectable options.

Documentation
React Aria
Pattern
W3C ARIA
Source
GitHub
Issues
Report
Install
pnpm dlx @kkga/shim add list-box
Aardvark
Cat
Dog
Kangaroo
Panda
Snake
import { ListBox, ListBoxItem } from "@/shim-ui/list-box";

export default () => (
  <ListBox aria-label="Favorite animal" selectionMode="single">
    <ListBoxItem>Aardvark</ListBoxItem>
    <ListBoxItem>Cat</ListBoxItem>
    <ListBoxItem>Dog</ListBoxItem>
    <ListBoxItem>Kangaroo</ListBoxItem>
    <ListBoxItem>Panda</ListBoxItem>
    <ListBoxItem isDisabled>Snake</ListBoxItem>
  </ListBox>
);

Install

Use the CLI or copy the source code manually.

pnpm dlx @kkga/shim add list-box

Sections

Use the ListBoxSection component to group related items under a shared heading.

Blue Jay
Robin
Wren
Snake
Lizard
import { ListBox, ListBoxItem, ListBoxSection } from "@/shim-ui/list-box";

export default () => (
  <ListBox aria-label="Favorite animal" selectionMode="single">
    <ListBoxSection title="Birds">
      <ListBoxItem>Blue Jay</ListBoxItem>
      <ListBoxItem>Robin</ListBoxItem>
      <ListBoxItem>Wren</ListBoxItem>
    </ListBoxSection>
    <ListBoxSection title="Reptiles">
      <ListBoxItem>Snake</ListBoxItem>
      <ListBoxItem>Lizard</ListBoxItem>
    </ListBoxSection>
  </ListBox>
);

Content

Provide custom content inside ListBoxItem to show rich titles and descriptions.

ReadView content and metadata
Robin
Wren
import { Description } from "@/shim-ui/field";
import { ListBox, ListBoxItem } from "@/shim-ui/list-box";

export default () => (
  <ListBox aria-label="Permissions" selectionMode="single">
    <ListBoxItem>
      <span slot="title">Read</span>
      <Description>View content and metadata</Description>
    </ListBoxItem>
    <ListBoxItem>Robin</ListBoxItem>
    <ListBoxItem>Wren</ListBoxItem>
  </ListBox>
);

Size

Use the size prop to adjust spacing and typography.

Cat
Dog
Kangaroo
Cat
Dog
Kangaroo
Cat
Dog
Kangaroo
Cat
Dog
Kangaroo
import { ListBox, ListBoxItem } from "@/shim-ui/list-box";

export default () => (
  <div className="grid grid-cols-2 gap-3">
    <ListBox aria-label="Favorite animal" selectionMode="single" size={1}>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
    </ListBox>
    <ListBox aria-label="Favorite animal" selectionMode="single" size={2}>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
    </ListBox>
    <ListBox aria-label="Favorite animal" selectionMode="single" size={3}>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
    </ListBox>
    <ListBox aria-label="Favorite animal" selectionMode="single" size={4}>
      <ListBoxItem>Cat</ListBoxItem>
      <ListBoxItem>Dog</ListBoxItem>
      <ListBoxItem>Kangaroo</ListBoxItem>
    </ListBox>
  </div>
);