List Item
ProOne row of a list: something at the left, a title with a description, and a value or control at the right. A row can be static, one button or one link.
Playground
- Nora Lindgren
- Daniel Okafor
- Priya Raman
- Nora LindgrenWunderUI Pro, one-time
- Daniel OkaforWunderUI Core, one-time
- Priya RamanWunderUI Pro, one-time
- NLNora LindgrenWunderUI Pro, one-time
- DODaniel OkaforWunderUI Core, one-time
- PRPriya RamanWunderUI Pro, one-time
- NLNora LindgrenWunderUI Pro, one-time$299.00Today
- DODaniel OkaforWunderUI Core, one-time$199.00Yesterday
- PRPriya RamanWunderUI Pro, one-time$299.00Nov 4
- NLWunderUI Pro, one-time$299.00Today
- DOWunderUI Core, one-time$199.00Yesterday
- PRWunderUI Pro, one-time$299.00Nov 4
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,
ListNotification,
NotificationItem,
} from "@wunderui/react"Then use it:
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 for
- List Group for a short framed list whose rows carry their own controls and need no row states
- Item Card for one object that stands on its own, with its own border
- Data Table for many rows that people sort, filter or compare by column
Leading
The leading slot takes one of eleven types: identities like avatar, icon tile or logo, and markers like checkbox, rank or date. Any React node works too.
Leading
- NLNora LindgrenOwner
- DODaniel OkaforEngineering
- PRPriya RamanDesign
- Invoice 1042Due Nov 20
- Contract draftEdited 2 hours ago
- Launch planShared with the team
- FigmaConnected 2 days ago
- SlackConnected last week
- StripeConnected in October
- United StatesUSD
- GermanyEUR
- United KingdomGBP
- BitcoinBTC
- EthereumETH
- SolanaSOL
Leading
- Review the Q3 reportDue Friday
- Send the invoice to Daniel OkaforDue Monday
- Book the launch callDue next week
- NotificationsEmail and push
- MessagesDirect and group
- SecurityPassword and sign-in
- 1Pricing1,842 visits
- 2Documentation1,310 visits
- 3Changelog764 visits
- Nov12Design review10:00, Priya Raman
- Nov13Sprint planning14:30, Daniel Okafor
- Nov18Launch call09:00, Nora Lindgren
- Order placedNov 3, 09:12
- Payment receivedNov 3, 09:14
- ShippedExpected Nov 6
- OverviewDashboard home
- ReportsWeekly and monthly
- SettingsWorkspace and billing
Trailing
The trailing slot takes one of thirteen types, figures to read and controls to use. A control keeps its own click and keyboard behaviour inside a button or link row.
Trailing
- NLNora LindgrenWunderUI Pro, one-time$299.00Today
- DODaniel OkaforWunderUI Core, one-time$199.00Yesterday
- PRPriya RamanWunderUI Pro, one-time-$49.00Refund
- NLNora LindgrenWunderUI Pro, one-time$299.00Paid
- DODaniel OkaforWunderUI Core, one-time$199.00Pending
- PRPriya RamanWunderUI Pro, one-time$299.00Failed
- PricingPage views1,842vs 1,64012%
- DocumentationPage views1,310vs 1,3664%
- ChangelogPage views764vs 7640%
- PricingPage views12%
- DocumentationPage views4%
- ChangelogPage views0%
- Launch planDue Nov 2880%x
- Docs rewriteDue Dec 59 of 20x
- Billing migrationDue Dec 1212%x
- NLNora LindgrenCommented on Launch plan2m agoUnread
- DODaniel OkaforReplied in Docs rewrite1h agoUnread
- PRPriya RamanShared Pricing page v2Yesterday
Trailing
- TFTomás FerreiraInvited 2 days ago
- MKMaya KesslerInvited last week
- DODaniel OkaforInvited in October
- Product updatesNews about new components and releases
- Billing alertsInvoices, failed payments and plan changes
- Security noticesSign-ins from a new device
- NLNora LindgrenOwner
- DODaniel OkaforEngineering
- PRPriya RamanDesign
- New project⌘N
- Search⌘K
- Settings⌘,
- NLNora LindgrenOwnerOwner
- DODaniel OkaforEngineeringAdmin
- PRPriya RamanDesignMember
- Launch planDue Nov 28Nora Lindgren, Daniel OkaforNLDO
- Docs rewriteDue Dec 5Priya RamanPR
- Billing migrationDue Dec 12Tomás Ferreira, Maya Kessler, Nora LindgrenTFMKNL
Row type
A row with a select handler is one button across the whole row, and a row with an href is one link. Without either it is static text.
Row
- Q3 report.pdf2.4 MB, Nora Lindgren2d ago
- Pricing model.xlsx860 KB, Daniel Okafor5d ago
- Launch banner.png1.1 MB, Priya Raman1w ago
- 2.4 MB, Nora Lindgren2d ago
- 860 KB, Daniel Okafor5d ago
- 1.1 MB, Priya Raman1w ago
- Q3 report.pdf2.4 MB, Nora Lindgren2d ago
- Pricing model.xlsx860 KB, Daniel Okafor5d ago
- Launch banner.png1.1 MB, Priya Raman1w ago
States
Selected, disabled and destructive are set by you. Hover and pressed are automatic: an interactive row shows a light fill on hover and a small press on click. Avatar rings and presence dots in a row take the row's fill, and a row that leads with an avatar puts title and description without a gap, as tall as the 36 px avatar.
- Change the name everyone sees
- Hand WunderUI to another admin
- Remove all projects and members
- Change the name everyone sees
- Hand WunderUI to another admin
- Remove all projects and members
- Change the name everyone sees
- Hand WunderUI to another admin
- Remove all projects and members
- Change the name everyone sees
- Hand WunderUI to another admin
- Remove all projects and members
Density
Comfortable rows have 12 px of vertical padding, compact rows 8 px. Set it once on the list.
- NLNora LindgrenWunderUI Pro, one-time$299.00Today
- DODaniel OkaforWunderUI Core, one-time$199.00Yesterday
- PRPriya RamanWunderUI Pro, one-time$299.00Nov 4
- NLNora LindgrenWunderUI Pro, one-time$299.00Today
- DODaniel OkaforWunderUI Core, one-time$199.00Yesterday
- PRPriya RamanWunderUI Pro, one-time$299.00Nov 4
Long text
A cut title ends in an ellipsis and shows its full text as a tooltip. A description wraps onto more lines.
Text
- Q3 report.pdfShared by Nora Lindgren2d ago
- Q3 revenue report with the final numbers for every region and product line.pdfShared by Nora Lindgren with the whole finance team, the board and every regional lead, with comments on pages 4 to 92d ago
Notification
ListNotification is a row for a notification list: an avatar or a round icon, the message, an optional quote and actions, the time and an indigo dot while it is unread. Wrap the actor in a strong element. With onClick the whole row is one button and the actions stay separately clickable. It replaces NotificationItem.
2 min ago
Deploy of wunderui.com finished
1 h ago
Daniel Okafor invited you to Design review
Can you join the design review on Thursday?
Yesterday
Keyboard interactions
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.
- TaborShift+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.
- EnterorSpace
- Presses the focused row button and calls . On a toggle row this changes .
- Enter
- Follows the focused row link.
- Space
- Toggles a focused leading Checkbox or trailing Switch.
- EnterorSpaceorArrowDown
- Opens the menu of a trailing icon button that has a . 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 and motion
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
The parts of a row, numbered in the figure. The divider is a 1 px line drawn under the row, not a part of its own.
- NLNora LindgrenWunderUI Pro, one-time$299.00Today
- DODaniel OkaforWunderUI Core, one-time$199.00Yesterday
- 1data-slot="list-items"
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.
- 2data-slot="list-item"
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.
- 3Optional
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.
- 4
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.
- 5Optional
The description under the title in 12 px secondary text, wrapping onto more lines. A meta line adds a third line in tertiary text.
- 6Optional
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.
- data-slot="list-item-row"
- data-slot="list-item-content"
- data-slot="coin-logo"Optional
- data-slot="coin-mark"Optional
- data-slot="integration-logo"Optional
- data-slot="integration-mark"Optional
- data-slot="list-flag"Optional
- data-slot="list-flag-ring"
- data-slot="list-item-leading"Optional
- data-slot="list-item-trailing"Optional
- data-slot="list-notification"Optional
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.
- data-slot="list-notification-icon"Optional
- Optional
Best practices
- 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.
- Do
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.
- Do
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.
- Do
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.
- 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
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
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.
- Do
Pass wrap where titles run long (a phone, a narrow rail): the row grows instead of cutting the title.
API reference
A List Item takes the props below and every attribute of a li, and ListItems takes those of a ul. The same row data is what the items array of ListItems, List Group and List Panel holds, plus an id. ListNotification renders a div and takes only the props listed under it.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| items | ListItemData[] | — | The rows as data. Each one is the props of a ListItem plus a unique . Leave it out to write children yourself. |
| density | "compact" | "comfortable" | — | gives rows 12 px of vertical padding, 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. |
| timeline | boolean | false | Draws a 2 px connector behind the step circles of rows whose leading type is . The connector joins each step to the one above and below. |
| children | ReactNode | — | elements, used when is not set. |
| wrap | boolean | — | Every row wraps a long title instead of truncating it (a row can still set its own ). |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| title required | React.ReactNode | — | The main text, in 14 px medium and cut to one line. It is the row's button or link when or is set. Required. |
| 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. |
| meta | React.ReactNode | — | A third line in tertiary text, under the description. |
| leading | ListLeading | React.ReactNode | — | What sits at the left: a spec object with a of , , , , , , , , , or , or any React node, which is placed as it is. |
| trailing | ListTrailing | React.ReactNode | — | What sits at the right: a spec object with a of , , , , , , , , , , , or , or any React node. |
| onSelect | () => void | — | Makes the whole row one button and is called when it is pressed. Trailing controls stay separately clickable. |
| href | string | — | Makes the whole row one link. A selected link row gets . |
| selected | boolean | — | Gives the row the subtle fill. On a button row it also sets , so leave it for rows that cannot be selected. |
| disabled | boolean | — | Dims the row to 40 %, disables its button and turns a link into plain text. |
| tone | "default" | "destructive" | "default" | sets the title in the error text colour, for actions such as Delete workspace. |
| density | "compact" | "comfortable" | — | Overrides the density of the surrounding for this row. |
| divider | boolean | — | Overrides the divider setting of the surrounding for this row. |
| rowClassName | string | — | Classes for the inner rounded row, for example a different fill. Use for the . |
| children | ReactNode | — | Extra content after the trailing slot, inside the row. |
| state | "default" | "hover" | "selected" | "disabled" | — | Freezes a look (, , or ) for documentation and screenshots. Do not use it in product code: live rows get their state from the pointer, and . |
| wrap | boolean | — | Long titles wrap onto more lines instead of truncating on one (the row grows). Default: false. |
| Prop | Type | Default | Description |
|---|---|---|---|
| coin required | "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 , or . 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. |
| Prop | Type | Default | Description |
|---|---|---|---|
| coin required | "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" | — |
| Prop | Type | Default | Description |
|---|---|---|---|
| name required | "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 , or . 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 is "" (the text beside the logo already names it). |
| Prop | Type | Default | Description |
|---|---|---|---|
| name required | "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. |
| Prop | Type | Default | Description |
|---|---|---|---|
| country required | ListFlagCountry | string & {} | — | One of ten country codes: , , , , , , , , or . Draws a round flag. |
| label | string | — | The accessible name of the flag. It is decorative by default. |
| Prop | Type | Default | Description |
|---|---|---|---|
| leading required | ListLeading | React.ReactNode | — | The slot to draw: a spec object or a node. Use it to draw a leading slot outside a row. |
| 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. |
| Prop | Type | Default | Description |
|---|---|---|---|
| trailing required | ListTrailing | React.ReactNode | — | The slot to draw: a spec object or a node. |
| title | string | — | The row's title as text. A spec reads as its label followed by it. |
| 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. |
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | ReactNode | — | The message. Wrap the actor in a strong element for emphasis. Required. |
| time required | ReactNode | — | The time under the message, already formatted, such as 2 min ago. Required. |
| avatar | { src?: string; initials?: string; color?: AvatarColor } | — | The sender as , and . It replaces the icon. |
| icon | ReactNode | — | An icon in a round muted tile, for a notification without a sender. Ignored when an avatar is given. |
| quote | ReactNode | — | A quoted excerpt in a tinted box under the message. |
| actions | ReactNode | — | Buttons under the message, such as Accept and Decline. They stay clickable when the row has onClick. |
| unread | boolean | — | Tints the row indigo and shows the unread dot, which carries the name Unread. |
| onClick | () => void | — | Makes the message one button that covers the whole row. |
| className | string | — | Extra classes on the row. |
| Prop | Type | Default | Description |
|---|---|---|---|
| children required | ReactNode | — | Message; wrap the actor in <strong> for emphasis. |
| time required | ReactNode | — | |
| actions | ReactNode | — | |
| avatar | { src?: string; initials?: string; color?: AvatarColor } | — | |
| icon | ReactNode | — | Icon in a round muted box (Type=icon). Ignored when an avatar is given. |
| onClick | () => void | — | |
| quote | ReactNode | — | Quoted excerpt (Type=avatar quote). |
| unread | boolean | — |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("list-item")The full library index for assistants is at /llms.txt.
Related components
- 3
Team
- NLNora LindgrenOwnerOwner
- DODaniel OkaforEngineeringAdmin
- PRPriya RamanDesignMember
Data & Tables8 stylesProList GroupA 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. Recent transactions
Last 7 days
- NLNora LindgrenWunderUI Pro, one-time+$299.00Today
- DODaniel OkaforWunderUI Core, one-time+$199.00Yesterday
- PRPriya RamanWunderUI Pro, refund-$49.00Nov 4
Data & Tables7 stylesProList PanelA dashboard card with a titled list: 31 ready panels (transactions, orders, integrations, team, activity, crypto, timelines …) with loading, empty and error states, or your own rows.