ListBox
A sunken-bevel container for vertical lists of items. Think of it as the inset counterpart to Panel — while Panel provides a raised surface, ListBox provides a recessed well that visually contains selectable or scrollable content.
Overview
ListBox is container-only. It provides the sunken bevel, background, column layout, and overflow: hidden (so item highlights never bleed over the bevel edges). The items inside are entirely up to the consumer.
When to use
- Navigation lists (sidebar menus, component lists)
- Data lists (bill items, task lists, log entries)
- Any vertical collection that needs a recessed Win95-style well
When not to use
- Single content areas — use Panel instead
- Horizontal layouts — ListBox is always a vertical column
- Dropdown menus — use a proper select or combobox
Variants
Simple text items
Plain text items with an active/selected state. The active item's highlight stays within the bevel thanks to overflow: hidden.
Rich content items
Items can be any React node — rows with multiple columns, icons, badges, checkboxes, etc.
Empty state
When there are no items, render a placeholder message inside the ListBox.
States
| State | Description |
|---|---|
| Default | Sunken bevel with light background, items rendered as children |
| Scrollable | Add overflow-y: auto via className when content exceeds container height |
| Empty | Render a placeholder child for the empty state |
Controls
Interactive controls are available in Storybook. Open Storybook
Props
Token mapping
| Part | Token |
|---|---|
| Background | --primitive-gray-50 |
| Bevel outer highlight | --sunken-outer-light |
| Bevel outer shadow | --sunken-outer-dark |
| Bevel inner highlight | --sunken-inner-light |
| Bevel inner shadow | --sunken-inner-dark |
Changelog
| Date | Change |
|---|---|
| 2026-03-27 | Initial release — sunken bevel container with overflow hidden |