List Group React component
A framed group of rows for settings menus and navigation lists: icons, descriptions, count badges, a danger row for destructive actions, and in selectable mode an active highlight that slides from row to row with arrow-key navigation.
When to use the List Group component
Use List Group for settings menus, account pages, sidebars inside panels and short lists of actions or links. Each row can carry an icon, a hint and a count, and the danger tone keeps destructive actions visibly apart.
Use single selection when the list switches what's shown next to it (like settings sections); use none when rows are links or one-off actions.
Installation
Add the List Group component to your project with the shadcn CLI. It lands in components/list-group.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add https://reactframe.com/r/list-group.jsonOr copy the source by hand and install its dependencies:
npm install motion clsx tailwind-mergeProps
<ListGroup /> accepts 11 props, all optional.
| Prop | Type | Default |
|---|---|---|
| items | ListGroupItem[] | DEFAULT_ITEMS |
| selectable single: one item is active and the highlight slides to it. none: plain actions or links. | "single" | "none" | "single" |
| value | string | — |
| defaultValue | string | "profile" |
| onValueChange | (id: string) => void | — |
| onItemClick Called for every activation (click, Enter), selectable or not. | (item: ListGroupItem) => void | — |
| variant bordered: framed with dividers. inset: framed, rows as separate pills. flush: no frame. | "bordered" | "inset" | "flush" | "bordered" |
| showChevron | boolean | true |
| label | string | "Settings" |
| theme | "dark" | "light" | "dark" |
| className | string | — |
- itemsListGroupItem[]Default: DEFAULT_ITEMS
- selectable
single: one item is active and the highlight slides to it. none: plain actions or links.
"single" | "none"Default: "single" - valuestring
- defaultValuestringDefault: "profile"
- onValueChange(id: string) => void
- onItemClick
Called for every activation (click, Enter), selectable or not.
(item: ListGroupItem) => void - variant
bordered: framed with dividers. inset: framed, rows as separate pills. flush: no frame.
"bordered" | "inset" | "flush"Default: "bordered" - showChevronbooleanDefault: true
- labelstringDefault: "Settings"
- theme"dark" | "light"Default: "dark"
- classNamestring
FAQ
- What does the selectable mode add?
- One row stays active, the highlight slides to the one you pick, and the list becomes a listbox: arrow keys, Home and End move between rows and skip disabled ones.
- Can rows be links?
- Yes. Give a row an href and it renders as a link; in single mode the active link gets aria-current="page".
- Which style should I use?
- Bordered for a classic settings list with dividers, inset when rows should read as separate pills inside a card, flush when the list sits inside something that already has a frame.
