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.
About the List Group component
List Group is a framed list of rows for settings menus, account pages and panels. Each row can have an icon, a label with a second line under it, a count or short tag on the right and a chevron, and a danger tone marks destructive rows like Delete account in red. In single-selection mode one row stays active, with a highlight and a side bar that slide to the row you pick.
items takes objects with id, label and optional description, icon (one of eight built-in names such as user, bell, lock and card, or your own element), badge, href, disabled and tone. Rows with href render as links and the rest as buttons. selectable picks single or none, value or defaultValue with onValueChange track the active row, and onItemClick runs on every activation. variant picks bordered, inset or flush, and showChevron toggles the arrows.
When to use it
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 @reactframe/list-groupOr 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
npm dependencies
Installed for you by the shadcn CLI.
List Group 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.
- Can I use it just for links and actions?
- Yes. Set selectable="none". Rows then act as plain links or buttons with no active highlight, the list uses list semantics instead of listbox, and onItemClick still reports each activation.
