# List Item

One list row: an icon tile, avatar, logo, flag, checkbox or date tile on the left, title and description in the middle, a value, badge, trend, button, switch or menu on the right. Comfortable or compact, with default, hover, selected and disabled states.

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

## Install

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

## Import

```tsx
import { ListItem, CoinLogo, CoinMark, IntegrationLogo, IntegrationMark, ListFlag, ListItemData, ListItemLeading, ListItemLeadingProps, ListItemProps, ListItems, ListItemsProps, ListItemTrailing, ListItemTrailingProps, ListNotification, NotificationItem } from "@wunderui/react"
```

## Minimal usage

Then use it:

```tsx
import { ListItems } from "@wunderui/react"

export function Payments() {
  return (
    <ListItems
      aria-label="Payments"
      items={[
        { id: "nora", title: "Nora Lindgren", description: "WunderUI Pro, one-time", trailing: { type: "value", value: "$299.00", sub: "Today" } },
        { id: "daniel", title: "Daniel Okafor", description: "WunderUI Core, one-time", trailing: { type: "value", value: "$199.00", sub: "Yesterday" } },
      ]}
    />
  )
}
```

Expected result: You see two rows divided by a line, each with a name over its plan and the amount with the day at the right.

## When to use

### Use List Item for

- One row of a list in a card, a List Group or a List Panel
- Rows that people press to open, select or follow
- Rows with a figure, a status or one control at the right

### Use something else

- [List Group](https://wunderui.com/components/list-group) for a short framed list whose rows carry their own controls and need no row states
- [Item Card](https://wunderui.com/components/item-card) for one object that stands on its own, with its own border
- [Data Table](https://wunderui.com/components/data-table) for many rows that people sort, filter or compare by column

## Keyboard

A row with a select handler or href is one native button or link. Controls in the leading and trailing slots are separate tab stops, in the order they are written.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous control: a leading checkbox, then the row button or link, then the trailing control, then the next row. A disabled row and a static row are skipped. |
| `Enter` or `Space` | Presses the focused row button and calls `onSelect`. On a toggle row this changes `selected`. |
| `Enter` | Follows the focused row link. |
| `Space` | Toggles a focused leading Checkbox or trailing Switch. |
| `Enter` or `Space` or `ArrowDown` | Opens the menu of a trailing icon button that has a `menu`. Inside the menu the arrow keys move, Enter picks and Escape closes it. |

A static row takes no focus. Arrow keys don't move between rows because the list is not a listbox; use List Group Master-Detail or Actions for arrow-key navigation.

## Behavior

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

- **One button over the whole row:** With a select handler the title is a button stretched over the whole row; with an href it is a link. Leading and trailing controls sit above it and take their own clicks.
- **States:** An interactive row fills with the page background on hover and scales to 98 % when pressed. A selected row keeps the subtle fill, and a disabled row dims to 40 %.
- **Focus:** Keyboard focus draws a 2 px indigo outline around the whole row. The divider next to a focused, hovered or selected row fades out so the highlight is never cut by a line.
- **Long text:** The title is cut to one line, and while it is cut, hovering it shows the full text as a native tooltip. The description and meta line wrap.
- **Names for assistive technology:** The title names the row's controls: checkboxes, switches and progress bars are labelled by it, and a trailing button reads as its label plus the title. Avatars list their people for screen readers.
- **Dividers and density:** Dividers sit inside the row's reserved space, so showing or hiding one never moves the layout. Without dividers rows sit 4 px apart; density comes from ListItems and a row can override it.
- **Motion and reduced motion:** The row fills and presses quickly and the divider fades. With reduced motion the press scale is off and only colour and opacity changes remain, so hover and selected fills still show.

## Anatomy

- `ListItems`: The list: a ul with the list role that holds the rows and tells them the density and whether they have dividers. It has no surface of its own, so put it in a card, a panel or a List Group.
- `ListItem`: One row: a li with a rounded inner row, 12 px side padding and 12 px between parts. Vertical padding is 12 px comfortable or 8 px compact, and a 1 px divider sits under the row, none on the last.
- `Leading`: The leading slot at the left. A spec object draws one of eleven types (avatar, icon tile, logo, flag, coin, checkbox, icon, rank, date, step, drag handle), or place any React node.
- `Title`: The title in 14 px medium, cut to one line with an ellipsis. It is a button with a select handler, a link with an href, otherwise plain text.
- `Description`: The description under the title in 12 px secondary text, wrapping onto more lines. A meta line adds a third line in tertiary text.
- `Trailing`: The trailing slot at the right. A spec object draws one of thirteen types (value, trend, progress, button, switch, menu and more), or place any node; it keeps its width and the text gives way first.
- `CoinLogo`
- `CoinMark`
- `IntegrationLogo`
- `IntegrationMark`
- `ListFlag`
- `ListItemLeading`
- `ListItemTrailing`
- `ListNotification`: A notification row: a 40 px avatar or a round 36 px icon, the message, an optional quoted excerpt and actions, the time and an unread dot. An unread row takes the indigo tint. It stands on its own, outside a list, and replaces NotificationItem.
- `NotificationItem`
- `Row`
- `Content`
- `List Flag Ring`
- `List Notification Icon`

## Best practices

### When to use

- Use a ListItem for one row of a list in a card, a List Group or a List Panel. For rows that people sort, filter or compare by column use a Data Table.

### Do

- Give a row people can press a select handler or an href. The title then becomes one button or link over the whole row, so pointer and keyboard reach it the same way.
- Keep one idea per slot: an avatar or icon at the left, a figure or one control at the right. Put the rest in the description.
- Use href when pressing the row goes to another page and a select handler when it changes something on this one. Assistive technology treats a link and a button differently.
- Write a title that is understandable on its own, because trailing controls are named after it: a button labelled Resend reads as Resend Maya Kessler.
- Pass wrap where titles run long (a phone, a narrow rail): the row grows instead of cutting the title.

### Don't

- Don't put a button in the trailing slot and also give the row a select handler unless they do different things. Two controls for one action make the row hard to read.
- Don't use the state prop in product code. It freezes a look for documentation; live rows get their state from the pointer, selected and disabled.
- Don't set a row's padding or radius by hand. A card with other geometry sets row padding and radius variables, so the rows stay concentric to it.

## API reference

### ListItem

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  | The main text, in 14 px medium and cut to one line. It is the row's button or link when `onSelect` or `href` is set. Required. |
| children | React.ReactNode |  | Extra content after the trailing slot, inside the row. |
| density | "compact" \| "comfortable" |  | Overrides the density of the surrounding `ListItems` for this row. |
| description | React.ReactNode |  | A line under the title in 12 px secondary text. It wraps and is the accessible description of the row's button. |
| disabled | boolean |  | Dims the row to 40 %, disables its button and turns a link into plain text. |
| divider | boolean |  | Overrides the divider setting of the surrounding `ListItems` for this row. |
| href | string |  | Makes the whole row one link. A selected link row gets `aria-current="page"`. |
| leading | ListLeading \| React.ReactNode |  | What sits at the left: a spec object with a `type` of `icon-tile`, `avatar`, `logo`, `checkbox`, `drag-handle`, `date`, `icon`, `rank`, `step`, `flag` or `coin`, or any React node, which is placed as it is. |
| meta | React.ReactNode |  | A third line in tertiary text, under the description. |
| onSelect | () => void |  | Makes the whole row one button and is called when it is pressed. Trailing controls stay separately clickable. |
| rowClassName | string |  | Classes for the inner rounded row, for example a different fill. Use `className` for the `li`. |
| selected | boolean |  | Gives the row the subtle fill. On a button row it also sets `aria-pressed`, so leave it `undefined` for rows that cannot be selected. |
| state | "default" \| "hover" \| "selected" \| "disabled" |  | Freezes a look (`default`, `hover`, `selected` or `disabled`) for documentation and screenshots. Do not use it in product code: live rows get their state from the pointer, `selected` and `disabled`. |
| tone | "default" \| "destructive" | "default" | `destructive` sets the title in the error text colour, for actions such as Delete workspace. |
| trailing | ListTrailing \| React.ReactNode |  | What sits at the right: a spec object with a `type` of `value`, `value-badge`, `value-trend`, `trend`, `progress`, `button`, `switch`, `icon-button`, `chevron`, `shortcut`, `badge`, `avatars` or `meta`, or any React node. |
| wrap | boolean |  | Long titles wrap onto more lines instead of truncating on one (the row grows). Default: false. |

Also accepts React.LiHTMLAttributes attributes.

### CoinLogo

| Prop | Type | Default | Description |
|---|---|---|---|
| coin* | "link" \| "dot" \| "btc" \| "eth" \| "usdt" \| "bnb" \| "sol" \| "usdc" \| "xrp" \| "doge" \| "ton" \| "ada" \| "trx" \| "avax" \| "shib" \| "bch" \| "ltc" \| "near" \| "pol" \| "uni" \| "icp" \| "xlm" \| "etc" \| "xmr" \| "atom" \| "apt" \| "arb" \| "op" \| "aave" \| "dai" |  | One of 30 coin symbols such as `btc`, `eth` or `sol`. Draws its mark in a 36 px tile. |
| label | string |  | The accessible name of the coin. It is decorative by default, because the name stays in the row's text. |

Also accepts React.HTMLAttributes attributes.

### CoinMark

| Prop | Type | Default |
|---|---|---|
| coin* | "link" \| "dot" \| "btc" \| "eth" \| "usdt" \| "bnb" \| "sol" \| "usdc" \| "xrp" \| "doge" \| "ton" \| "ada" \| "trx" \| "avax" \| "shib" \| "bch" \| "ltc" \| "near" \| "pol" \| "uni" \| "icp" \| "xlm" \| "etc" \| "xmr" \| "atom" \| "apt" \| "arb" \| "op" \| "aave" \| "dai" |  |

Also accepts React.SVGAttributes attributes.

### IntegrationLogo

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | "Figma" \| "Claude" \| "OpenAI" \| "Slack" \| "Notion" \| "GitHub" \| "Google Drive" \| "Google Sheets" \| "Google Calendar" \| "Microsoft Teams" \| "Stripe" \| "Shopify" \| "HubSpot" \| "Zapier" \| "Linear" \| "Gmail" \| "Outlook" \| "Salesforce" \| "Zoom" \| "Discord" \| "Dropbox" \| "Jira" \| "Asana" \| "Trello" \| "Airtable" \| "Mailchimp" \| "PayPal" \| "Zendesk" \| "Intercom" \| "Google Analytics" \| "Vercel" \| "Google" \| "X" \| "LinkedIn" \| "Google Meet" \| "Apple Calendar" |  | One of 31 product names, for example `Figma`, `Slack` or `Stripe`. Draws its mark in a 36 px tile. |
| label | string |  | The accessible name of the logo. Without it the product name is used; an empty string makes it decorative. |
| tooltip | boolean |  | Show the product name in a Tooltip on hover. Default: on, unless `label` is "" (the text beside the logo already names it). |

Also accepts React.HTMLAttributes attributes.

### IntegrationMark

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | "Figma" \| "Claude" \| "OpenAI" \| "Slack" \| "Notion" \| "GitHub" \| "Google Drive" \| "Google Sheets" \| "Google Calendar" \| "Microsoft Teams" \| "Stripe" \| "Shopify" \| "HubSpot" \| "Zapier" \| "Linear" \| "Gmail" \| "Outlook" \| "Salesforce" \| "Zoom" \| "Discord" \| "Dropbox" \| "Jira" \| "Asana" \| "Trello" \| "Airtable" \| "Mailchimp" \| "PayPal" \| "Zendesk" \| "Intercom" \| "Google Analytics" \| "Vercel" \| "Google" \| "X" \| "LinkedIn" \| "Google Meet" \| "Apple Calendar" |  | Which product mark to draw. |

Also accepts React.SVGAttributes attributes.

### ListFlag

| Prop | Type | Default | Description |
|---|---|---|---|
| country* | ListFlagCountry \| (string & {}) |  | One of ten country codes: `us`, `de`, `gb`, `in`, `br`, `fr`, `es`, `nl`, `jp` or `ca`. Draws a round flag. |
| label | string |  | The accessible name of the flag. It is decorative by default. |

Also accepts React.SVGAttributes attributes.

### ListItemLeading

| Prop | Type | Default | Description |
|---|---|---|---|
| leading* | ListLeading \| React.ReactNode |  | The slot to draw: a spec object or a node. Use it to draw a leading slot outside a row. |
| className | string |  | Classes for the slot. |
| describedBy | string |  | The id of the element that describes a checkbox in the slot. A row sets it to its description. |
| labelledBy | string |  | The id of the element that names a checkbox in the slot. A row sets it to its title. |

### ListItems

| Prop | Type | Default | Description |
|---|---|---|---|
| children | React.ReactNode |  | `ListItem` elements, used when `items` is not set. |
| density | "compact" \| "comfortable" |  | `comfortable` gives rows 12 px of vertical padding, `compact` 8 px. Every row reads it from here. |
| divider | boolean |  | Whether a 1 px line separates the rows. Without it the rows sit 4 px apart. |
| items | ListItemData[] |  | The rows as data. Each one is the props of a ListItem plus a unique `id`. Leave it out to write `ListItem` children yourself. |
| timeline | boolean | false | Draws a 2 px connector behind the step circles of rows whose leading type is `step`. The connector joins each step to the one above and below. |
| wrap | boolean |  | Every row wraps a long title instead of truncating it (a row can still set its own `wrap`). |

Also accepts React.HTMLAttributes attributes.

### ListItemTrailing

| Prop | Type | Default | Description |
|---|---|---|---|
| trailing* | ListTrailing \| React.ReactNode |  | The slot to draw: a spec object or a node. |
| className | string |  | Classes for the slot. |
| describedBy | string |  | The id of the element that describes a switch in the slot. |
| labelledBy | string |  | The id of the element that names a switch or progress bar in the slot. |
| title | string |  | The row's title as text. A `button` spec reads as its label followed by it. |

### ListNotification

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The message. Wrap the actor in a strong element for emphasis. Required. |
| time* | React.ReactNode |  | The time under the message, already formatted, such as 2 min ago. Required. |
| actions | React.ReactNode |  | Buttons under the message, such as Accept and Decline. They stay clickable when the row has onClick. |
| avatar | { src?: string; initials?: string; color?: AvatarColor } |  | The sender as `src`, `initials` and `color`. It replaces the icon. |
| className | string |  | Extra classes on the row. |
| icon | React.ReactNode |  | An icon in a round muted tile, for a notification without a sender. Ignored when an avatar is given. |
| onClick | () => void |  | Makes the message one button that covers the whole row. |
| quote | React.ReactNode |  | A quoted excerpt in a tinted box under the message. |
| unread | boolean |  | Tints the row indigo and shows the unread dot, which carries the name Unread. |

### NotificationItem

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | Message; wrap the actor in <strong> for emphasis. |
| time* | React.ReactNode |  |  |
| actions | React.ReactNode |  |  |
| avatar | { src?: string; initials?: string; color?: AvatarColor } |  |  |
| className | string |  |  |
| icon | React.ReactNode |  | Icon in a round muted box (Type=icon). Ignored when an avatar is given. |
| onClick | () => void |  |  |
| quote | React.ReactNode |  | Quoted excerpt (Type=avatar quote). |
| unread | boolean |  |  |

## Examples

### Leading: who or what the row is about

### Leading: a marker before the text

### Trailing: figures

### Trailing: controls

### Row: static, button or link

### States: default, selected, disabled and destructive

### Density: comfortable and compact

### Text: short and long

### Notification: an avatar or an icon, a message and an unread dot

## In context

### Team: a badge for the owner and a menu for the rest

Every member except the owner has a row menu. Remove from workspace takes the member out of the list, and Reset brings the team back.

### Notifications: mark a row as read

Pressing a row clears its unread dot. The dot keeps its space, so nothing moves when it goes.

### Settings navigation: one current section

Each row is one button, and the selected row is the current section.

### Currency: pick one

Flags lead each row, and the selected row stays highlighted.

### Long titles wrap

`wrap` lets the title take more lines instead of truncating (the row grows). ListItems and ListGroup take `wrap` for all their rows.

## For AI agents

`get_component("list-item")`

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