# List Group

A 400 px card of list rows with an optional header — sixteen ready patterns: basic, icon, avatar, brand, metric, selectable, toggle, sortable, expandable, grouped, ranking, comparison, tree, action, discussion and master–detail.

- Category: Data & Tables
- Page: https://wunderui.com/components/list-group
- Tier: Core and Pro

## Install

List Group ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

```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"
```

## Minimal usage

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

- [List Panel](https://wunderui.com/components/list-panel) for a dashboard card with a footer and loading, empty and error states
- [List Item](https://wunderui.com/components/list-item) for a single row inside a card you build yourself
- [Data Table](https://wunderui.com/components/data-table) for many rows that people sort, filter or compare by column

## Keyboard

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.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | 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. |
| `Enter` or `Space` | Opens or closes the focused expandable row, and presses the focused button. |
| `Alt+ArrowUp` or `Alt+ArrowDown` | 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. |
| `ArrowUp` or `ArrowDown` or `Home` or `End` | Tree, action list and master-detail: move to the previous, next, first or last row. In master-detail the selection and the detail follow. |
| `ArrowRight` or `ArrowLeft` | Tree: opens a closed folder or enters it, and closes an open folder or goes to its parent. Enter or Space selects the row. |
| `Enter` or `Space` | 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

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

- `ListGroup`: 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.
- `ListGroupHeader`: 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.
- `Title`: The title as a heading (h3 by default) in 14 px semibold, with an optional 12 px secondary description under it.
- `Count`: The count in a grey pill badge after the title, in tabular figures.
- `Action`: The action at the right of the header: any element, usually a link Button such as View all.
- `ListGroupSection`: 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.
- `ListItems`: The rows, from the items list or as ListItem children. The group tells them its density and whether they have dividers.
- `ListGroupActions`
- `ListGroupDetails`
- `ListGroupDiscussion`
- `ListGroupExpandable`
- `ListGroupMasterDetail`
- `ListGroupSelectable`
- `ListGroupSortable`
- `ListGroupToggle`
- `ListGroupTree`
- `ListView`
- `ListViewItem`
- `List Comment`
- `List Thread`
- `List Item`
- `List Item Row`
- `List Item Content`
- `List Row Click Area`
- `Footer`

## Best practices

### When to use

- Use a List Group for a card of rows that belong together: settings, members, an inbox. Use a List Panel for a dashboard card that also needs a footer and loading, empty and error states.

### 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.
- Give every group a name: a title, or an aria-label when the header is hidden.
- Use sections when the rows fall into a few labelled runs, such as Today and Yesterday, and keep the labels short.
- Build the loading, empty and error looks inside the card with Skeleton and Empty State, so the card does not jump away.
- Pass wrap to the group when its rows can have long titles; every row then wraps instead of truncating.

### 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 mix behaviours in one group, for example a toggle row between selectable rows. Use two groups with their own titles.
- Don't nest a List Group in another card with a border. The group is already a card.

## API reference

### ListGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| action | React.ReactNode |  | An element at the right of the header, usually a link Button. |
| aria-label | string |  | The accessible name of the group when it has no visible title. |
| className | string |  | Classes for the card, for example a different width than the 400 px default. |
| count | number \| string |  | A count shown in a grey pill after the title. |
| density | "compact" \| "comfortable" | "comfortable" | `comfortable` gives rows 12 px of vertical padding, `compact` 8 px. |
| description | React.ReactNode |  | A line under the title in 12 px secondary text. |
| divider | boolean | true | Whether a 1 px line separates the rows. |
| footer | React.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. |
| items | ListItemData[] |  | The rows as data. Leave it out to write `ListItems` or `ListGroupSection` children yourself. |
| showHeader | boolean |  | Shows or hides the header. It defaults to true when a title is set. Without a header give the group an `aria-label`. |
| title | React.ReactNode |  | The heading in the header. It names the section for assistive technology. |
| titleAs | "h2" \| "h3" \| "h4" \| "h5" \| "h6" |  | The heading level of the title, `h2` to `h6`. It defaults to `h3`. |
| titleId | string |  | The id of the title element, for when you need to point at it. |
| wrap | boolean | false | Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false. |

Also accepts React.HTMLAttributes attributes.

### ListGroupActions

| Prop | Type | Default | Description |
|---|---|---|---|
| actions* | ListAction[] |  | The commands: each has an `id`, a `title`, an optional `description`, `icon`, `shortcut`, `destructive`, `disabled` and `onSelect`. |
| action | React.ReactNode |  | Right-hand action, usually a link Button ("View all"). |
| aria-label | string |  | Defines a string value that labels the current element. Accessible name when the header is hidden. |
| className | string |  |  |
| count | number \| string |  | A count badge after the title (Team members 5, Inbox 12). |
| density | "compact" \| "comfortable" | "comfortable" |  |
| description | React.ReactNode |  |  |
| divider | boolean | true |  |
| footer | React.ReactNode |  | 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. |
| onAction | (action: ListAction) => void |  | Called with the action after its own `onSelect`. |
| showHeader | boolean |  | Figma "Show header". Defaults to true when a title is set. |
| title | React.ReactNode |  |  |
| titleAs | "h2" \| "h3" \| "h4" \| "h5" \| "h6" |  |  |
| titleId | string |  |  |
| wrap | boolean |  | Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false. |

Also accepts React.HTMLAttributes attributes.

### ListGroupDetails

| Prop | Type | Default | Description |
|---|---|---|---|
| rows* | { label: ReactNode; value: ReactNode }[] |  | Label and value pairs, drawn as a description list on the subtle fill. |
| actions | React.ReactNode |  | Buttons under the pairs. |

Also accepts React.HTMLAttributes attributes.

### ListGroupDiscussion

| Prop | Type | Default | Description |
|---|---|---|---|
| action | React.ReactNode |  | Right-hand action, usually a link Button ("View all"). |
| aria-label | string |  | Defines a string value that labels the current element. Accessible name when the header is hidden. |
| className | string |  |  |
| comments | ListComment[] |  | The threads when controlled: an author, a time, the text, a reaction count and replies. |
| count | number \| string |  | A count badge after the title (Team members 5, Inbox 12). |
| currentUser | ListPerson & { name: string } | { name: "You", initials: "YO", color: "indigo" } | Who writes new replies: a name, initials and a colour for the avatar. |
| defaultComments | ListComment[] |  | The threads at the start when uncontrolled. |
| density | "compact" \| "comfortable" |  |  |
| description | React.ReactNode |  |  |
| divider | boolean | true |  |
| footer | React.ReactNode |  | 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. |
| onCommentsChange | (comments: ListComment[]) => void |  | Called with the new threads after a reaction or a reply. |
| onReply | (parentId: string, text: string) => void |  | Called with the id of the comment and the text when a reply is posted. |
| showHeader | boolean |  | Figma "Show header". Defaults to true when a title is set. |
| title | React.ReactNode |  |  |
| titleAs | "h2" \| "h3" \| "h4" \| "h5" \| "h6" |  |  |
| titleId | string |  |  |
| wrap | boolean |  | Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false. |

Also accepts React.HTMLAttributes attributes.

### ListGroupExpandable

| Prop | Type | Default | Description |
|---|---|---|---|
| items* | ListItemData[] with details |  | The rows. Each one has a `details` node that opens under it; `ListGroupDetails` draws the usual box. A row's `trailing` is the chevron. |
| action | React.ReactNode |  | Right-hand action, usually a link Button ("View all"). |
| aria-label | string |  | Defines a string value that labels the current element. Accessible name when the header is hidden. |
| className | string |  |  |
| count | number \| string |  | A count badge after the title (Team members 5, Inbox 12). |
| defaultValue | string[] |  | The ids of the rows that are open at the start. |
| density | "compact" \| "comfortable" | "comfortable" |  |
| description | React.ReactNode |  |  |
| divider | boolean | true |  |
| footer | React.ReactNode |  | 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. |
| multiple | boolean | false | Lets several rows be open at once. Without it, opening one row closes the other. |
| onValueChange | (value: string[]) => void |  | Called with the ids of the open rows after each change. |
| showHeader | boolean |  | Figma "Show header". Defaults to true when a title is set. |
| title | React.ReactNode |  |  |
| titleAs | "h2" \| "h3" \| "h4" \| "h5" \| "h6" |  |  |
| titleId | string |  |  |
| value | string[] |  | The ids of the open rows when controlled. |
| wrap | boolean |  | Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false. |

Also accepts React.HTMLAttributes attributes.

### ListGroupHeader

| Prop | Type | Default | Description |
|---|---|---|---|
| action | React.ReactNode |  | Right-hand action, usually a link Button ("View all"). |
| className | string |  |  |
| count | number \| string |  | A count badge after the title (Team members 5, Inbox 12). |
| description | React.ReactNode |  |  |
| title | React.ReactNode |  |  |
| titleAs | "h2" \| "h3" \| "h4" \| "h5" \| "h6" | "h3" |  |
| titleId | string |  |  |

### ListGroupMasterDetail

| Prop | Type | Default | Description |
|---|---|---|---|
| items* | ListItemData[] |  | The rows of the list on the left. |
| renderDetail* | (item: T) => React.ReactNode |  | Draws the detail of the selected row. |
| action | React.ReactNode |  | Right-hand action, usually a link Button ("View all"). |
| className | string |  |  |
| count | number \| string |  | A count badge after the title (Team members 5, Inbox 12). |
| defaultValue | string \| null |  | The id of the selected row at the start. |
| density | "comfortable" \| "compact" | "comfortable" |  |
| description | React.ReactNode |  |  |
| divider | boolean | true |  |
| emptyDetail | React.ReactNode |  | Shown in the detail while no row is selected. |
| onValueChange | (id: string \| null, item: T \| null) => void |  | Called with the id and the row when the selection changes. |
| title | React.ReactNode |  |  |
| titleAs | "h2" \| "h3" \| "h4" \| "h5" \| "h6" |  |  |
| value | string \| null |  | The id of the selected row when controlled. |

Also accepts React.HTMLAttributes attributes.

### ListGroupSection

| Prop | Type | Default | Description |
|---|---|---|---|
| label* | React.ReactNode |  | The label of the run of rows. It names the section for assistive technology. Required. |
| children | React.ReactNode |  | Rows, or any content such as a line of text for an empty section, when `items` is not set. |
| count | number \| string |  | A count in a pill after the label. Screen readers hear it as the number of items. |
| items | ListItemData[] |  | The rows of the section as data. |

Also accepts React.HTMLAttributes attributes.

### ListGroupSelectable

| Prop | Type | Default | Description |
|---|---|---|---|
| items* | ListItemData[] |  | The rows. Their `leading` is the control, so a row's own `leading`, `onSelect` and `href` are ignored. |
| action | React.ReactNode |  | Right-hand action, usually a link Button ("View all"). |
| aria-label | string |  | Defines a string value that labels the current element. Accessible name when the header is hidden. |
| className | string |  |  |
| count | number \| string |  | A count badge after the title (Team members 5, Inbox 12). |
| defaultValue | string \| null |  | The selected ids at the start when uncontrolled. |
| density | "compact" \| "comfortable" |  |  |
| description | React.ReactNode |  |  |
| divider | boolean |  |  |
| footer | React.ReactNode |  | 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. |
| mode | "radio" |  | `checkbox` allows several rows, `radio` exactly one. |
| onValueChange | (value: string \| null) => void |  | Called with the new selection after each change. |
| showHeader | boolean |  | Figma "Show header". Defaults to true when a title is set. |
| title | React.ReactNode |  |  |
| titleAs | "h2" \| "h3" \| "h4" \| "h5" \| "h6" |  |  |
| titleId | string |  |  |
| value | string \| null |  | The selected ids when controlled: an array in checkbox mode, a single id or null in radio mode. |
| wrap | boolean |  | Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false. |

Also accepts React.HTMLAttributes attributes.

### ListGroupSortable

| Prop | Type | Default | Description |
|---|---|---|---|
| action | React.ReactNode |  | Right-hand action, usually a link Button ("View all"). |
| aria-label | string |  | Defines a string value that labels the current element. Accessible name when the header is hidden. |
| className | string |  |  |
| count | number \| string |  | A count badge after the title (Team members 5, Inbox 12). |
| defaultItems | ListItemData[] |  | The order at the start when uncontrolled. |
| density | "compact" \| "comfortable" | "comfortable" |  |
| description | React.ReactNode |  |  |
| divider | boolean | true |  |
| footer | React.ReactNode |  | 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. |
| items | ListItemData[] |  | The order when controlled. A row's `leading` is the drag handle. |
| onItemsChange | (items: SortableItem[]) => void |  | Called with the new order after each move. |
| rowMenu | (item: SortableItem) => ListMenuItem[] |  | Returns extra entries for a row's menu, after Move up and Move down. |
| showHeader | boolean |  | Figma "Show header". Defaults to true when a title is set. |
| title | React.ReactNode |  |  |
| titleAs | "h2" \| "h3" \| "h4" \| "h5" \| "h6" |  |  |
| titleId | string |  |  |
| wrap | boolean |  | Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false. |

Also accepts React.HTMLAttributes attributes.

### ListGroupToggle

| Prop | Type | Default | Description |
|---|---|---|---|
| items* | ListItemData[] |  | The rows. The trailing slot is the switch, so a row's own `trailing` is ignored. |
| action | React.ReactNode |  | Right-hand action, usually a link Button ("View all"). |
| aria-label | string |  | Defines a string value that labels the current element. Accessible name when the header is hidden. |
| className | string |  |  |
| count | number \| string |  | A count badge after the title (Team members 5, Inbox 12). |
| defaultValue | Record<string, boolean> |  | Which rows are on at the start when uncontrolled. |
| density | "compact" \| "comfortable" | "comfortable" |  |
| description | React.ReactNode |  |  |
| divider | boolean | true |  |
| footer | React.ReactNode |  | 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. |
| onValueChange | (value: Record<string, boolean>) => void |  | Called with the new record after each change. |
| showHeader | boolean |  | Figma "Show header". Defaults to true when a title is set. |
| title | React.ReactNode |  |  |
| titleAs | "h2" \| "h3" \| "h4" \| "h5" \| "h6" |  |  |
| titleId | string |  |  |
| value | Record<string, boolean> |  | Which rows are on, by id, when controlled. |
| wrap | boolean |  | Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false. |

Also accepts React.HTMLAttributes attributes.

### ListGroupTree

| Prop | Type | Default | Description |
|---|---|---|---|
| nodes* | ListTreeNode[] |  | The tree: each node has an `id`, a `label`, an optional `count`, an `icon`, `disabled` and `children`. |
| action | React.ReactNode |  | Right-hand action, usually a link Button ("View all"). |
| aria-label | string |  | Defines a string value that labels the current element. Accessible name when the header is hidden. |
| className | string |  |  |
| count | number \| string |  | A count badge after the title (Team members 5, Inbox 12). |
| defaultExpanded | string[] |  | The ids of the folders that are open at the start. |
| defaultSelected | string \| null |  |  |
| defaultValue | string \| null |  | The id of the selected node at the start. |
| density | "compact" \| "comfortable" | "comfortable" |  |
| description | React.ReactNode |  |  |
| divider | boolean |  |  |
| expanded | string[] |  | The ids of the open folders when controlled. |
| footer | React.ReactNode |  | 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. |
| onExpandedChange | (expanded: string[]) => void |  | Called with the ids of the open folders after each change. |
| onSelectedChange | (id: string \| null, node: ListTreeNode \| null) => void |  |  |
| onValueChange | (id: string \| null, node: ListTreeNode \| null) => void |  | Called with the id and the node when the selection changes. |
| selected | string \| null |  |  |
| showHeader | boolean |  | Figma "Show header". Defaults to true when a title is set. |
| title | React.ReactNode |  |  |
| titleAs | "h2" \| "h3" \| "h4" \| "h5" \| "h6" |  |  |
| titleId | string |  |  |
| value | string \| null |  | The id of the selected node when controlled. |
| wrap | boolean |  | Every row wraps a long title instead of truncating it (owner rule: never clip). Default: false. |

Also accepts React.HTMLAttributes attributes.

### ListView

| Prop | Type | Default |
|---|---|---|
| children* | ReactNode |  |
| className | string |  |

### ListViewItem

| Prop | Type | Default |
|---|---|---|
| title* | ReactNode |  |
| className | string |  |
| description | ReactNode |  |
| leading | ReactNode |  |
| trailing | ReactNode |  |

## Examples

### Header: title, description, count, action or none

### Density: comfortable and compact

### Sections: labelled runs of rows

### Choose: checkbox, radio and toggle

### Reveal: expandable, tree and master-detail

### Behaviour: sortable, actions and discussion

### Content: rows, loading, empty and error

### Simple list: a leading mark, a title with a description and one fact

## In context

### Preferences: a toggle group and a radio group

Two groups in one stack, and a click anywhere in a row toggles or picks it. Reset puts the settings back.

### Inbox: unread count and mark as read

Pressing a row clears its dot and lowers the count in the header. Mark all read clears the rest.

### Priorities: reorder by drag or keyboard

Drag a row by its handle, or focus the handle and press Alt with an arrow key. The line under the list follows the order.

### Files: a tree with a selection

Arrow keys move through the tree, Right opens a folder and Left closes it. The selection shows under the list.

## For AI agents

`get_component("list-group")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
