Skip to content

Design system

Documentation

DesignComponents / List

Components / List

Beta

List

Present related items with semantic list structure, optional metadata, actions, and explicit states.

On this page

Examples

Items with metadata and actions

Each item can present a clear main value, secondary metadata, and an optional action.

  • Northstar

    Customer onboarding workspace.

    Updated today
  • Atlas

    Quarterly planning and launch notes.

    Updated yesterday

Recent project list

Loading and empty states

Keep the list boundary stable while showing an explicit loading status or no-results message.

  • Loading recent activity
  • There are no projects matching this filter.

Loading and empty list states

Try bounded scrolling

Toggle the max-height scroll region while preserving the same fixture items.

  • Mina updated the onboarding checklist.
    10:32
  • Avery invited a new workspace member.
    09:58
  • The product notes were approved.
    Yesterday
  • The quarterly plan was published.
    Monday
  • A support issue was resolved.
    Friday

Scrollable list property playground

When to use

Use List when each item is a standalone record or task. Use Table when people need to compare stable fields across records. List does not fetch data or own selection state.

Usage

import { Button } from "@phuctech/ui/components/button";
import { List, ListItem } from "@phuctech/ui/components/list";

<List aria-label="Recent projects">
<ListItem meta="Updated today" actions={<Button size="sm" variant="outline">Open</Button>}>
  <h3>Northstar</h3>
  <p>Customer onboarding workspace.</p>
</ListItem>
</List>

States

Use ListLoading for an explicitly announced loading row and ListEmpty for a settled collection with no items. Keep request and retry behavior outside the list. Set scrollable when the list needs a bounded 20rem vertical region; its header or actions should remain outside that region.

API

Component API
PropTypeDefaultDescriptionConstraints
Listul props + scrollablescrollable=falseSemantic unordered list root.Use a concise aria-label when there is no visible heading naming the list.
ListItemli props + meta + actions—One item with optional trailing metadata and actions.Provide visible labels for icon-only actions through the shared control API.
ListEmptyli props + children—Status message for an empty or no-results list.Use after loading has settled; distinguish no data from no matches in the text.
ListLoadingli props + label + rowslabel="Loading items", rows=3Accessible loading status with decorative item placeholders.Rows are clamped to 1–8; set aria-busy on the parent List when appropriate.
scrollablebooleanfalseBounds the list to 20rem and enables the shared scroll affordance.Keep fixed headings and actions outside the scrolling list.

Tokens

Component tokens
TokenRoleEffective valueUsage
--color-border-default / --radius-lgList itemsShared boundary and radiusCreates quiet item separation without a second surface theme.
scrollbar-hover-revealBounded overflowShared scroll utilityShows the scroll thumb during pointer, focus, or touch interaction.

Accessibility

List and ListItem render native ul and li elements. Loading and empty parts use status semantics. Give the list an accessible name, and keep action controls keyboard reachable with their shared visible or programmatic labels.

Do and don’t

Do

Keep each row focused on one item and use metadata for a short secondary fact.

Don’t

Place fixed actions inside a bounded scroll region or turn a list into a table when field comparison matters.

  • Table presents stable tabular records.
  • EmptyState handles a larger empty collection explanation.
  • Skeleton provides decorative content placeholders.