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 todayAtlas
Quarterly planning and launch notes.
Updated yesterday
Recent project list
import { Button } from "@phuctech/ui/components/button";
import { List, ListItem } from "@phuctech/ui/components/list";
export function Example() {
return (
<List aria-label="Recent projects">
<ListItem meta="Updated today" actions={<Button size="sm" variant="outline">Open</Button>}>
<h3 className="text-sm font-medium">Northstar</h3>
<p className="mt-1 text-sm text-muted-foreground">Customer onboarding workspace.</p>
</ListItem>
<ListItem meta="Updated yesterday">
<h3 className="text-sm font-medium">Atlas</h3>
<p className="mt-1 text-sm text-muted-foreground">Quarterly planning and launch notes.</p>
</ListItem>
</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
import { List, ListEmpty, ListLoading } from "@phuctech/ui/components/list";
export function Example() {
return (
<div className="grid w-full gap-4 md:grid-cols-2">
<List aria-label="Loading recent activity" aria-busy="true">
<ListLoading label="Loading recent activity" rows={2} />
</List>
<List aria-label="Filtered projects">
<ListEmpty>There are no projects matching this filter.</ListEmpty>
</List>
</div>
);
}
Try bounded scrolling
Toggle the max-height scroll region while preserving the same fixture items.
Scrollable list property playground
import { List, ListItem } from "@phuctech/ui/components/list";
export function Example() {
return (
<List aria-label="Recent activity" scrollable>
<ListItem meta="10:32">Mina updated the onboarding checklist.</ListItem>
<ListItem meta="09:58">Avery invited a new workspace member.</ListItem>
<ListItem meta="Yesterday">The product notes were approved.</ListItem>
<ListItem meta="Monday">The quarterly plan was published.</ListItem>
<ListItem meta="Friday">A support issue was resolved.</ListItem>
</List>
);
}
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
Tokens
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
Keep each row focused on one item and use metadata for a short secondary fact.
Place fixed actions inside a bounded scroll region or turn a list into a table when field comparison matters.
Related
- Table presents stable tabular records.
- EmptyState handles a larger empty collection explanation.
- Skeleton provides decorative content placeholders.