Content & Data

List Item

List Item is a single row inside a collection — avatar, title, description, metadata, and optional trailing content.

State (Default/Hover) — 2 variants

betaReact AvailableFigma AvailableDocs Partial

React last updated: 2026-07-13
Documentation last updated: 2026-06-01
Accessibility target: WCAG 2.2 AA (target)
Version: 0.5.0-beta

Known open questions

Selected and density variants are not confirmed in Figma — not implemented.
Compose List Item inside native ul/ol — no separate List component.
Nested Avatar initials cannot be driven from List Item Figma properties.

Live preview

Compose rows inside native ul/ol lists. Only one root interactive element per row.

Static / avatar / metadata / badge

Usman FarooqiUpdated Button documentation2h ago
Design tokensFoundations referenceBeta

Interactive modes

Navigational / action / trailing action

ButtonPrimary actions and links-as-buttons
Registry exportStatic row with separate trailing action

Do not combine a row-level href or onClick with an interactive trailing control — use a static row when a separate trailing action is required.

Purpose

A single row in a list showing an avatar, title/subtitle, and trailing metadata — the standard pattern for activity feeds and contact lists.

Anatomy

List Item composes optional Avatar, Badge, Tag, Button, or icon leading/trailing slots: li + row + leading + title + description + metadata + trailing.

Variants and states

static · navigational · action

When to use

Any list of similarly-structured items with a person/entity, primary text, secondary text, and trailing info.

When not to use

Tabular data with multiple aligned columns — use Table (/components/table).

Accessibility

If the row is clickable, the whole row should be one real link/button, not just visually clickable.

Keyboard behavior

Navigational rows use native link activation. Action rows use native button activation. Static rows are not tab stops unless they contain separate controls.

Common mistakes

Cramming too much information into the trailing metadata slot.

Properties

State as variants. Title (text), Subtitle (text), Meta (text).

When should a List Item be interactive?

Only when navigation or a row action is intentional. Default rows are static content inside ul/ol.

What is the difference between List Item and Menu Item?

List Item is generic collection content without menu or listbox roles. Menu Item belongs inside menu semantics.

Can a List Item contain another action?

Yes on static rows — trailing actions must be separate controls. Do not combine row-level href/onClick with trailing buttons.

Which semantics should List Item use?

Native li for all modes. Navigational uses anchor/NextLink. Action uses button type="button". No menuitem, option, or listbox roles.

Tokens used

semantic/surface/elevatedsemantic/text/primarycomponent/radius/control

Known limitation

The nested Avatar instance's Initials property cannot be exposed as a parent-level property through Figma's API — requires selecting the nested instance directly.

Component API

Prop	Type	Default	Description
title	ReactNode	—	Primary row label.
description	ReactNode	—	Secondary text (Figma Subtitle).
metadata	ReactNode	—	Trailing metadata such as time or Badge.
leading	ReactNode	—	Avatar, icon, or other leading content.
trailing	ReactNode	—	Static trailing content or separate action on static rows.
href	string	—	Navigational mode — real anchor.
onClick	() => void	—	Action mode — native button.
disabled	boolean	false	Disables action rows.

React example

Copy React example

import { Avatar } from "@/components/ui/Avatar";
import { ListItem } from "@/components/ui/ListItem";

export function Example() {
  return (
    <ul>
      <ListItem
        leading={<Avatar size="sm" initials="UF" decorative alt="" />}
        title="Usman Farooqi"
        description="Updated documentation"
        metadata="2h ago"
      />
      <ListItem href="/components/button" title="Button" description="Actions" />
    </ul>
  );
}