Skip to content
WunderUI

List Group

Pro

A card of list rows with an optional header. Plain groups show rows; selectable, toggle, expandable, sortable, tree, action, discussion and master-detail groups add behaviour.

Playground

Team

3
  • Nora LindgrenOwner
    Owner
  • Daniel OkaforEngineering
    Admin
  • Priya RamanDesign
    Member

Installation

List Group comes with WunderUI Core and Pro, in the package from your plan. See the plans.

Then import what you need:

tsx
import {
  ListGroup,
  ListGroupActions,
  ListGroupActionsProps,
  ListGroupDetails,
  ListGroupDetailsProps,
  ListGroupDiscussion,
  ListGroupDiscussionProps,
  ListGroupExpandable,
  ListGroupExpandableItem,
  ListGroupExpandableProps,
  ListGroupHeader,
  ListGroupHeaderProps,
  ListGroupMasterDetail,
  ListGroupMasterDetailItem,
  ListGroupMasterDetailProps,
  ListGroupProps,
  ListGroupSection,
  ListGroupSectionProps,
  ListGroupSelectable,
  ListGroupSelectableItem,
  ListGroupSelectableProps,
  ListGroupSortable,
  ListGroupSortableItem,
  ListGroupSortableProps,
  ListGroupToggle,
  ListGroupToggleItem,
  ListGroupToggleProps,
  ListGroupTree,
  ListGroupTreeProps,
  ListView,
  ListViewItem,
} from "@wunderui/react"

Then use it:

tsx
import { ListGroup } from "@wunderui/react"

export function Team() {
  return (
    <ListGroup
      title="Team"
      count={2}
      items={[
        { id: "nora", title: "Nora Lindgren", description: "Owner" },
        { id: "daniel", title: "Daniel Okafor", description: "Engineering" },
      ]}
    />
  )
}

Expected result: You see one bordered card with the title Team and a count of 2, and two rows divided by a line.

When to use

Use List Group for

  • A card of related rows with a title, a count or an action
  • Settings, members, files, tickets and inboxes
  • Rows that people select, switch, open, reorder, run or discuss

Use something else for

  • List Panel for a dashboard card with a footer and loading, empty and error states
  • List Item for a single row inside a card you build yourself
  • Data Table for many rows that people sort, filter or compare by column

The header holds a title, description, count badge and one action. For a group without a header, hide it and give the group an aria-label.

Team

  • Nora LindgrenOwner
    Owner
  • Daniel OkaforEngineering
    Admin
  • Priya RamanDesign
    Member

Density

Comfortable rows have 12 px of vertical padding, compact rows 8 px. The group passes it to every row.

Team

  • Nora LindgrenOwner
    Owner
  • Daniel OkaforEngineering
    Admin
  • Priya RamanDesign
    Member

Sections

A section is a labelled run of rows with an optional count. The label scrolls with the rows; there are no sticky headers.

Inbox

Today, 2 items
  • Nora LindgrenCommented on Launch plan
    2m ago
  • Daniel OkaforReplied in Docs rewrite
    1h ago
Yesterday, 1 items
  • Priya RamanShared Pricing page v2
    Yesterday

Choose

Selectable groups put a checkbox or radio before each row, toggle groups a switch after it. The whole row takes the click and the control keeps keyboard focus.

Notify me about

  • Product updatesNews about new components and releases
  • Billing alertsInvoices, failed payments and plan changes
  • Security noticesSign-ins from a new device

Reveal

Expandable rows open a detail box under them, the tree nests rows by level, and master-detail shows the chosen row beside the list when there is room.

Projects

  • Due Nov 28
    Owner
    Nora Lindgren
    Status
    On track
    Due
    Nov 28
  • Due Dec 5
    Owner
    Daniel Okafor
    Status
    At risk
    Due
    Dec 5
  • Due Dec 12
    Owner
    Priya Raman
    Status
    Not started
    Due
    Dec 12

Behaviour

Sortable rows move by drag handle or with Alt and the arrow keys, and action rows run a command and show its shortcut. A discussion holds comments with reactions and replies.

Priorities

Drag the handle to reorder, or press Alt with Arrow Up or Arrow Down. Space picks a row up and drops it.

  • Launch planNora Lindgren
  • Docs rewriteDaniel Okafor
  • Billing migrationPriya Raman

Loading, empty and error

The group has no states of its own. Build them inside the card: skeleton rows while loading, an Empty State when there is nothing to show or the load failed.

Content

Team

3
  • Nora LindgrenOwner
    Owner
  • Daniel OkaforEngineering
    Admin
  • Priya RamanDesign
    Member

Simple list

For a short set of similar rows without a header, leave the title out and name the group with aria-label. Each ListItem holds a leading mark, a title with a description and one trailing fact, a Badge or a switch, and the divider runs between rows. It replaces ListView and ListViewItem.

  • Q3 report.pdf2.4 MB
    2 days ago
  • Roadmap.docx1.1 MB
    5 days ago
  • Brand guide.pdf4.2 MB
    Last week

Keyboard interactions

A plain group has no focus handling of its own: only controls in its rows take focus. The groups with behaviour add the keys below.

TaborShiftTab
Moves focus to the next or previous control. A tree, an action list and a master-detail list are one stop: Tab enters them and leaves them.
Space
Toggles the focused checkbox or switch, and selects the focused radio. A click on the row does the same.
EnterorSpace
Opens or closes the focused expandable row, and presses the focused button.
AltArrowUporAltArrowDown
Sortable: moves the row whose handle has focus one place. Space picks the row up, the arrows move it, Space drops it and Escape puts it back.
ArrowUporArrowDownorHomeorEnd
Tree, action list and master-detail: move to the previous, next, first or last row. In master-detail the selection and the detail follow.
ArrowRightorArrowLeft
Tree: opens a closed folder or enters it, and closes an open folder or goes to its parent. Enter or Space selects the row.
EnterorSpace
Action list: runs the focused action. Typing a letter jumps to the next action that starts with it.

A button or link row is one tab stop. Selectable, toggle, expandable, sortable and discussion rows each have their own; tree, actions and master-detail are one stop with arrow keys inside.

Behavior and motion

What the group does with state, content, the DOM and motion.

Controlled or not
These groups keep their own state. Pass a value and change handler (or the items or comments equivalents) to control them, or a default value to set the first state.
Rows and the card
The card has 8 px padding and a 16 px radius, so the 8 px rows are concentric to it. The group passes its density and dividers to its rows, and sections wrap rows in ListGroupSection.
No states of its own
The group has no loading, empty or error look and no sticky headers or scroll region. Put a Skeleton, an Empty State or a message inside the card.
Click anywhere in the row
In selectable and toggle groups a click on the row toggles its control, unless it lands on a control, button, link or field. The control keeps focus, so the row is still one tab stop.
Sortable announces its moves
Every move, by pointer or keyboard, is announced politely with the new position, like Daniel Okafor moved to position 1 of 3. The row menu also offers Move up and Move down.
Expandable keeps closed content out of reach
A closed row's detail is inert, so its buttons leave the tab order. Opening one row closes the other unless multiple is allowed; rows are disclosure buttons with aria-expanded and aria-controls.
Master-detail adapts
The list is a listbox whose selection drives the detail, and the card is 880 px wide by default. Beside the 400 px list sits a detail column; under 720 px the detail stacks below the list.
Motion and reduced motion
Rows fill and press quickly; an expandable row animates its detail open and turns its chevron. With reduced motion the press scale is off and the detail only fades.

Anatomy

The parts of a group, numbered in the figure. The groups with behaviour (selectable, toggle, expandable, sortable, tree, actions, discussion, master-detail) are made of the same parts.

Inbox

Two new messages

2
Today
  • Nora LindgrenCommented on Launch plan
    2m ago
  • Daniel OkaforReplied in Docs rewrite
    1h ago
  • data-slot="list-group"

    The card: a section 400 px wide (it shrinks on a narrow screen) with a 1 px border, 16 px radius, card surface and 8 px padding. A title names the section.

  • data-slot="list-group-header"Optional

    The header row, with 12 px padding and 12 px between its parts. It shows when a title is set or the header is turned on.

  • The title as a heading (h3 by default) in 14 px semibold, with an optional 12 px secondary description under it.

  • Optional

    The count in a grey pill badge after the title, in tabular figures.

  • Optional

    The action at the right of the header: any element, usually a link Button such as View all.

  • data-slot="list-group-section"Optional

    A labelled run of rows. The label is 12 px semibold tertiary text with an optional count badge, and it doesn't stick to the top while the rows scroll.

  • The rows, from the items list or as ListItem children. The group tells them its density and whether they have dividers.

  • data-slot="list-group-footer"Optional
  • Optional
  • data-slot="list-group-details"Optional
  • Optional
  • data-slot="list-comment"
  • data-slot="list-thread"Optional
  • Optional
  • data-slot="list-item"
  • data-slot="list-item-row"
  • data-slot="list-item-content"
  • data-slot="list-group-master-detail"Optional
  • Optional
  • data-slot="list-row-click-area"
  • Optional
  • Optional
  • Optional
  • Optional
  • Optional

Best practices

  • Do

    Pick the group that matches the job: Selectable for choosing, Toggle for switching, Expandable for details, Sortable for order. Behaviour, focus handling and labels come with it.

  • Do

    Give every group a name: a title, or an aria-label when the header is hidden.

  • Do

    Use sections when the rows fall into a few labelled runs, such as Today and Yesterday, and keep the labels short.

  • Do

    Build the loading, empty and error looks inside the card with Skeleton and Empty State, so the card does not jump away.

  • Don’t

    Don't expect sticky section labels or a scroll region. The group grows with its rows; for a fixed height put it in a container that scrolls.

  • Don’t

    Don't mix behaviours in one group, for example a toggle row between selectable rows. Use two groups with their own titles.

  • Don’t

    Don't nest a List Group in another card with a border. The group is already a card.

  • Do

    Pass wrap to the group when its rows can have long titles; every row then wraps instead of truncating.

API reference

Every group takes the props of ListGroup and every attribute of a section; the groups with behaviour add the props listed under their name. Rows are ListItemData (see List Item).

The card: a section 400 px wide (it shrinks on a narrow screen) with a 1 px border, 16 px radius, card surface and 8 px padding. A title names the section.

PropTypeDefaultDescription
titleReact.ReactNode—The heading in the header. It names the section for assistive technology.
descriptionReact.ReactNode—A line under the title in 12 px secondary text.
countnumber | string—A count shown in a grey pill after the title.
actionReact.ReactNode—An element at the right of the header, usually a link Button.
itemsListItemData[]—The rows as data. Leave it out to write or children yourself.
density"compact" | "comfortable""comfortable" gives rows 12 px of vertical padding, 8 px.
dividerbooleantrueWhether a 1 px line separates the rows.
showHeaderboolean—Shows or hides the header. It defaults to true when a title is set. Without a header give the group an .
titleAs"h2" | "h3" | "h4" | "h5" | "h6"—The heading level of the title, to . It defaults to .
footerReact.ReactNode—A node pinned to the bottom edge of the card, such as a View all or Add button. In a row of cards that stretch to the same height it stays on the bottom edge instead of floating under the last row.
aria-labelstring—The accessible name of the group when it has no visible title.
titleIdstring—The id of the title element, for when you need to point at it.
wrapbooleanfalseEvery row wraps a long title instead of truncating it (owner rule: never clip). Default: false.

The header row, with 12 px padding and 12 px between its parts. It shows when a title is set or the header is turned on.

PropTypeDefaultDescription
actionReactNode—Right-hand action, usually a link Button ("View all").
countnumber | string—A count badge after the title (Team members 5, Inbox 12).
descriptionReactNode—
titleReactNode—
titleAs"h2" | "h3" | "h4" | "h5" | "h6""h3"
titleIdstring—

A labelled run of rows. The label is 12 px semibold tertiary text with an optional count badge, and it doesn't stick to the top while the rows scroll.

PropTypeDefaultDescription
label requiredReact.ReactNode—The label of the run of rows. It names the section for assistive technology. Required.
countnumber | string—A count in a pill after the label. Screen readers hear it as the number of items.
itemsListItemData[]—The rows of the section as data.
childrenReactNode—Rows, or any content such as a line of text for an empty section, when is not set.

PropTypeDefaultDescription
actions requiredListAction[]—The commands: each has an , a , an optional , , , , and .
onAction(action) => void—Called with the action after its own .
actionReactNode—Right-hand action, usually a link Button ("View all").
aria-labelstring—Defines a string value that labels the current element. Accessible name when the header is hidden.
countnumber | string—A count badge after the title (Team members 5, Inbox 12).
density"compact" | "comfortable""comfortable"
descriptionReactNode—
dividerbooleantrue
footerReactNode—Pinned to the bottom of the card (a "View all" or "Add" action): in a row of equal cards it stays on the bottom edge.
showHeaderboolean—Figma "Show header". Defaults to true when a title is set.
titleReactNode—
titleAs"h2" | "h3" | "h4" | "h5" | "h6"—
titleIdstring—
wrapboolean—Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false.

PropTypeDefaultDescription
rows required{ label: ReactNode; value: ReactNode }[]—Label and value pairs, drawn as a description list on the subtle fill.
actionsReactNode—Buttons under the pairs.

PropTypeDefaultDescription
commentsListComment[]—The threads when controlled: an author, a time, the text, a reaction count and replies.
defaultCommentsListComment[]—The threads at the start when uncontrolled.
onCommentsChange(comments) => void—Called with the new threads after a reaction or a reply.
currentUserListPerson & { name: string }{ name: "You", initials: "YO", color: "indigo" }Who writes new replies: a name, initials and a colour for the avatar.
onReply(parentId, text) => void—Called with the id of the comment and the text when a reply is posted.
actionReactNode—Right-hand action, usually a link Button ("View all").
aria-labelstring—Defines a string value that labels the current element. Accessible name when the header is hidden.
countnumber | string—A count badge after the title (Team members 5, Inbox 12).
density"compact" | "comfortable"—
descriptionReactNode—
dividerbooleantrue
footerReactNode—Pinned to the bottom of the card (a "View all" or "Add" action): in a row of equal cards it stays on the bottom edge.
showHeaderboolean—Figma "Show header". Defaults to true when a title is set.
titleReactNode—
titleAs"h2" | "h3" | "h4" | "h5" | "h6"—
titleIdstring—
wrapboolean—Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false.

PropTypeDefaultDescription
items requiredListItemData[] with details—The rows. Each one has a node that opens under it; draws the usual box. A row's is the chevron.
valuestring[]—The ids of the open rows when controlled.
defaultValuestring[]—The ids of the rows that are open at the start.
onValueChange(value) => void—Called with the ids of the open rows after each change.
multiplebooleanfalseLets several rows be open at once. Without it, opening one row closes the other.
actionReactNode—Right-hand action, usually a link Button ("View all").
aria-labelstring—Defines a string value that labels the current element. Accessible name when the header is hidden.
countnumber | string—A count badge after the title (Team members 5, Inbox 12).
density"compact" | "comfortable""comfortable"
descriptionReactNode—
dividerbooleantrue
footerReactNode—Pinned to the bottom of the card (a "View all" or "Add" action): in a row of equal cards it stays on the bottom edge.
showHeaderboolean—Figma "Show header". Defaults to true when a title is set.
titleReactNode—
titleAs"h2" | "h3" | "h4" | "h5" | "h6"—
titleIdstring—
wrapboolean—Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false.

PropTypeDefaultDescription
items requiredListItemData[]—The rows of the list on the left.
valuestring | null—The id of the selected row when controlled.
defaultValuestring | null—The id of the selected row at the start.
onValueChange(id, item) => void—Called with the id and the row when the selection changes.
renderDetail required(item) => ReactNode—Draws the detail of the selected row.
emptyDetailReactNode—Shown in the detail while no row is selected.
actionReactNode—Right-hand action, usually a link Button ("View all").
countnumber | string—A count badge after the title (Team members 5, Inbox 12).
density"comfortable" | "compact""comfortable"
descriptionReactNode—
dividerbooleantrue
titleReactNode—
titleAs"h2" | "h3" | "h4" | "h5" | "h6"—

PropTypeDefaultDescription
mode"radio"— allows several rows, exactly one.
items requiredListItemData[]—The rows. Their is the control, so a row's own , and are ignored.
valuestring | null—The selected ids when controlled: an array in checkbox mode, a single id or null in radio mode.
defaultValuestring | null—The selected ids at the start when uncontrolled.
onValueChange(value) => void—Called with the new selection after each change.
actionReactNode—Right-hand action, usually a link Button ("View all").
aria-labelstring—Defines a string value that labels the current element. Accessible name when the header is hidden.
countnumber | string—A count badge after the title (Team members 5, Inbox 12).
density"compact" | "comfortable"—
descriptionReactNode—
dividerboolean—
footerReactNode—Pinned to the bottom of the card (a "View all" or "Add" action): in a row of equal cards it stays on the bottom edge.
showHeaderboolean—Figma "Show header". Defaults to true when a title is set.
titleReactNode—
titleAs"h2" | "h3" | "h4" | "h5" | "h6"—
titleIdstring—
wrapboolean—Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false.

PropTypeDefaultDescription
itemsListItemData[]—The order when controlled. A row's is the drag handle.
defaultItemsListItemData[]—The order at the start when uncontrolled.
onItemsChange(items) => void—Called with the new order after each move.
rowMenu(item) => ListMenuItem[]—Returns extra entries for a row's menu, after Move up and Move down.
actionReactNode—Right-hand action, usually a link Button ("View all").
aria-labelstring—Defines a string value that labels the current element. Accessible name when the header is hidden.
countnumber | string—A count badge after the title (Team members 5, Inbox 12).
density"compact" | "comfortable""comfortable"
descriptionReactNode—
dividerbooleantrue
footerReactNode—Pinned to the bottom of the card (a "View all" or "Add" action): in a row of equal cards it stays on the bottom edge.
showHeaderboolean—Figma "Show header". Defaults to true when a title is set.
titleReactNode—
titleAs"h2" | "h3" | "h4" | "h5" | "h6"—
titleIdstring—
wrapboolean—Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false.

PropTypeDefaultDescription
items requiredListItemData[]—The rows. The trailing slot is the switch, so a row's own is ignored.
valueRecord<string, boolean>—Which rows are on, by id, when controlled.
defaultValueRecord<string, boolean>—Which rows are on at the start when uncontrolled.
onValueChange(value) => void—Called with the new record after each change.
actionReactNode—Right-hand action, usually a link Button ("View all").
aria-labelstring—Defines a string value that labels the current element. Accessible name when the header is hidden.
countnumber | string—A count badge after the title (Team members 5, Inbox 12).
density"compact" | "comfortable""comfortable"
descriptionReactNode—
dividerbooleantrue
footerReactNode—Pinned to the bottom of the card (a "View all" or "Add" action): in a row of equal cards it stays on the bottom edge.
showHeaderboolean—Figma "Show header". Defaults to true when a title is set.
titleReactNode—
titleAs"h2" | "h3" | "h4" | "h5" | "h6"—
titleIdstring—
wrapboolean—Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false.

PropTypeDefaultDescription
nodes requiredListTreeNode[]—The tree: each node has an , a , an optional , an , and .
expandedstring[]—The ids of the open folders when controlled.
defaultExpandedstring[]—The ids of the folders that are open at the start.
onExpandedChange(expanded) => void—Called with the ids of the open folders after each change.
valuestring | null—The id of the selected node when controlled.
defaultValuestring | null—The id of the selected node at the start.
onValueChange(id, node) => void—Called with the id and the node when the selection changes.
actionReactNode—Right-hand action, usually a link Button ("View all").
aria-labelstring—Defines a string value that labels the current element. Accessible name when the header is hidden.
countnumber | string—A count badge after the title (Team members 5, Inbox 12).
defaultSelectedstring | null—
density"compact" | "comfortable""comfortable"
descriptionReactNode—
dividerboolean—
footerReactNode—Pinned to the bottom of the card (a "View all" or "Add" action): in a row of equal cards it stays on the bottom edge.
onSelectedChange(id, node) => void—
selectedstring | null—
showHeaderboolean—Figma "Show header". Defaults to true when a title is set.
titleReactNode—
titleAs"h2" | "h3" | "h4" | "h5" | "h6"—
titleIdstring—
wrapboolean—Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false.

PropTypeDefaultDescription
children requiredReactNode—

PropTypeDefaultDescription
title requiredReactNode—
descriptionReactNode—
leadingReactNode—
trailingReactNode—

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("list-group")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.