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.
See alsoList GroupList Panel
Usage
Installation
List Item comes with WunderUI Core and Pro, in the package from your plan. See the plans.
Then import what you need:
import {
ListItem,
CoinLogo,
CoinMark,
IntegrationLogo,
IntegrationMark,
ListFlag,
ListItemData,
ListItemLeading,
ListItemLeadingProps,
ListItemProps,
ListItems,
ListItemsProps,
ListItemTrailing,
ListItemTrailingProps,
} from "@wunderui/react"Examples
List Item: comfortable, all states
Default, hover, selected and disabled at the comfortable density (12 px padding). The first row selects on click.
List Item: compact, all states
The same four states at the compact density: 8 px above and below, 12 px at the sides.
Integration Logo: 30 integrations
The product marks inside the plain 36 px Icon Button frame, drawn at 20 px. The one-colour marks (OpenAI, GitHub, Linear, Mailchimp, Intercom, Zendesk) follow text-primary and turn white in dark mode.
Coin Logo: 30 coins
The 30 most popular coins as round brand marks at 20 px in the same 36 px plain frame, for the coin slot of crypto lists (leading: { type: "coin", coin: "btc" }). Decorative: the coin's name stays in the row text.
Anatomy
The parts the component is made of. Each one renders a you can target from CSS.
- data-slot="list-items"
The list itself (). Sets density, dividers and the timeline connector for its rows, and renders data.
- data-slot="list-item"
One row: the leading slot, the title with its description and meta line, and the trailing slot. With or the title becomes the row's single button or link, stretched over the row.
- data-slot="list-item-leading"
The left slot, drawn from a spec: icon tile, avatar, logo, checkbox, drag handle, date tile, icon, rank, step, flag or coin. A React node passes through.
- data-slot="integration-logo"
A product mark (Figma, Slack, Stripe … 30 in all) at 20 px inside the plain 36 px icon-button frame. Used by the leading slot; an image, not a control.
- data-slot="integration-mark"
The bare 20 × 20 product mark, for your own buttons or chips.
- data-slot="list-flag"
A round country flag for the leading slot (Audience by Location).
- data-slot="coin-logo"
A round coin mark (Bitcoin, Ethereum, Solana … 30 in all) at 20 px inside the plain 36 px icon-button frame, for the leading slot. Decorative: the coin name stays in the row text.
- data-slot="coin-mark"
The bare round coin mark, for your own chips, tables and pickers.
- data-slot="list-item-trailing"
The right slot, drawn from a spec: value, value with badge or trend, trend, progress, button, switch, icon button with menu, chevron, shortcut, badge, avatars or time with unread dot.
- data-slot="list-item-row"
The 8 px rounded surface that takes the hover, selected and pressed states; 12 px padding (8 px above and below when compact).
- data-slot="list-item-content"
Title (14 medium), description (12, secondary) and meta line (12, tertiary).
Best practices
- When to use
Use a List Item for a row people scan and act on in one place: a person, a payment, an app, a setting. To compare many columns across rows, use a Table or Data Table.
- Do
Give the row one primary action through or . Buttons, switches and menus in the trailing slot stay separate tab stops.
- Do
Pick one leading type per list, so the titles line up and the eye can scan down one edge.
- Do
For crypto rows pass : the real mark is drawn and kept away from screen readers, because the coin name is already in the title.
- Do
Keep the trailing value short and tabular: an amount, a badge or a trend. Put the explanation in the description.
- Don’t
Don't put two buttons in the trailing slot; move secondary actions into the icon-button menu.
- Don’t
Don't use selected for hover or focus. It marks the chosen row, and the title turns link-coloured with it.
API Reference
Theming
The CSS variables this component reads. Set one on any wrapper to restyle everything inside it. More in Theming.