Skip to content
WunderUI

List Item

Pro

One 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 LindgrenWunderUI Pro, one-time
    $299.00Today
  • Daniel OkaforWunderUI Core, one-time
    $199.00Yesterday
  • Priya RamanWunderUI 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:

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

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

  • Nora LindgrenOwner
  • Daniel OkaforEngineering
  • Priya RamanDesign

Leading

  • Review the Q3 reportDue Friday
  • Send the invoice to Daniel OkaforDue Monday
  • Book the launch callDue next week

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

  • Nora LindgrenWunderUI Pro, one-time
    $299.00Today
  • Daniel OkaforWunderUI Core, one-time
    $199.00Yesterday
  • Priya RamanWunderUI Pro, one-time
    -$49.00Refund

Trailing

  • Tomás FerreiraInvited 2 days ago
  • Maya KesslerInvited last week
  • Daniel OkaforInvited in October

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 Lindgren
    2d ago
  • Pricing model.xlsx860 KB, Daniel Okafor
    5d ago
  • Launch banner.png1.1 MB, Priya Raman
    1w 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

Density

Comfortable rows have 12 px of vertical padding, compact rows 8 px. Set it once on the list.

  • Nora LindgrenWunderUI Pro, one-time
    $299.00Today
  • Daniel OkaforWunderUI Core, one-time
    $199.00Yesterday
  • Priya 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 Lindgren
    2d 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.

NL

2 min ago

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.

TaborShiftTab
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.

  • Nora LindgrenWunderUI Pro, one-time
    $299.00Today
  • Daniel OkaforWunderUI Core, one-time
    $199.00Yesterday
  • data-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.

  • data-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.

  • Optional

    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.

  • 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.

  • Optional

    The description under the title in 12 px secondary text, wrapping onto more lines. A meta line adds a third line in tertiary text.

  • Optional

    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.

PropTypeDefaultDescription
itemsListItemData[]—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.
dividerboolean—Whether a 1 px line separates the rows. Without it the rows sit 4 px apart.
timelinebooleanfalseDraws 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.
childrenReactNode— elements, used when is not set.
wrapboolean—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.

PropTypeDefaultDescription
title requiredReact.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.
descriptionReact.ReactNode—A line under the title in 12 px secondary text. It wraps and is the accessible description of the row's button.
metaReact.ReactNode—A third line in tertiary text, under the description.
leadingListLeading | React.ReactNode—What sits at the left: a spec object with a of , , , , , , , , , or , or any React node, which is placed as it is.
trailingListTrailing | 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.
hrefstring—Makes the whole row one link. A selected link row gets .
selectedboolean—Gives the row the subtle fill. On a button row it also sets , so leave it for rows that cannot be selected.
disabledboolean—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.
dividerboolean—Overrides the divider setting of the surrounding for this row.
rowClassNamestring—Classes for the inner rounded row, for example a different fill. Use for the .
childrenReactNode—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 .
wrapboolean—Long titles wrap onto more lines instead of truncating on one (the row grows). Default: false.

PropTypeDefaultDescription
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"—

PropTypeDefaultDescription
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.

PropTypeDefaultDescription
country requiredListFlagCountry | string & {}—One of ten country codes: , , , , , , , , or . Draws a round flag.
labelstring—The accessible name of the flag. It is decorative by default.

PropTypeDefaultDescription
leading requiredListLeading | React.ReactNode—The slot to draw: a spec object or a node. Use it to draw a leading slot outside a row.
describedBystring—The id of the element that describes a checkbox in the slot. A row sets it to its description.
labelledBystring—The id of the element that names a checkbox in the slot. A row sets it to its title.

PropTypeDefaultDescription
trailing requiredListTrailing | React.ReactNode—The slot to draw: a spec object or a node.
titlestring—The row's title as text. A spec reads as its label followed by it.
describedBystring—The id of the element that describes a switch in the slot.
labelledBystring—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.

PropTypeDefaultDescription
children requiredReactNode—The message. Wrap the actor in a strong element for emphasis. Required.
time requiredReactNode—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.
iconReactNode—An icon in a round muted tile, for a notification without a sender. Ignored when an avatar is given.
quoteReactNode—A quoted excerpt in a tinted box under the message.
actionsReactNode—Buttons under the message, such as Accept and Decline. They stay clickable when the row has onClick.
unreadboolean—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.
classNamestring—Extra classes on the row.

PropTypeDefaultDescription
children requiredReactNode—Message; wrap the actor in <strong> for emphasis.
time requiredReactNode—
actionsReactNode—
avatar{ src?: string; initials?: string; color?: AvatarColor }—
iconReactNode—Icon in a round muted box (Type=icon). Ignored when an avatar is given.
onClick() => void—
quoteReactNode—Quoted excerpt (Type=avatar quote).
unreadboolean—

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

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

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