A card-per-row list with a leading icon, auto-derived columns, inline actions, and click-through navigation.
Installation
$Terminal
npx shadcn@latest add https://sdk-components.thesqd.com/r/item-list.jsonUsage
Pass a `data` array of dicts. Columns are derived from the keys (minus reserved keys like `icon`, `title`, `actions`, `href`); pass `columns` to reorder, relabel, align, or custom-render.
TSImport
import { ItemList, type ItemListRow } from "@/components/ui/item-list";TSExample
import { ItemList, type ItemListRow } from "@/components/ui/item-list";
import { GlobeIcon } from "lucide-react";
const data: ItemListRow[] = [
{
icon: GlobeIcon,
title: "Chrome",
subtitle: "Web Browser",
member: "Ann Wong",
amount: "$88,904.92",
href: "/apps/chrome",
},
];
export function Example() {
// Columns auto-derive from the keys (member, amount); pass `columns` to
// reorder / relabel / align / custom-render.
return <ItemList data={data} />;
}Composition
Anatomy of the ItemList primitive.
ItemList (props) // flat, card-per-row list
├── data: ItemListRow[] // each row is a dict
│ ├── icon? | image? // leading visual
│ ├── title / subtitle? // leading text
│ ├── [key]: ReactNode // any other key → a data column (auto)
│ ├── actions?: { icon, label, onClick }[] // animate-ui icon buttons
│ └── href? | onNavigate? // trailing chevron navigation
├── columns?: ItemListColumn[] // optional: reorder / relabel / align / render
├── nameHeader? (default "Name")
└── hideHeader? / emptyState? / getRowId?
Row = <Card> surface
├── Leading cell — icon|image + title + subtitle
├── Data columns — value rendered as-is (drop in Badge / Select / Input to edit inline)
├── Action cluster — animated Lucide icons, animate on hover
└── Chevron — navigates via href (<a>) or onNavigateDefault
App-directory style: a leading icon + title/subtitle, data columns, a status indicator, animate-ui icon actions, and a chevron that navigates. Columns are reordered/aligned via `columns`.
Auto columns
Pass just `data` — columns are inferred from the dict keys (minus reserved keys). No actions or navigation.
Name
Region
Uptime
Marketing site
Production
us-east-1
99.98%
Docs
Production
eu-west-2
99.95%
Status page
Edge
global
100%
API Reference
Props for the flat `<ItemList>` component plus the row, column, and action shapes.
ItemList
| Prop | Type | Default | Description |
|---|---|---|---|
data | ItemListRow[] | — | Rows to render. Each is a dict; non-reserved keys become data columns automatically. |
columns | ItemListColumn[] | — | Optional override — reorder, relabel, align, set width, or custom-render columns. Omit to auto-derive from keys. |
nameHeader | ReactNode | "Name" | Header label for the leading (icon + title) column. |
hideHeader | boolean | false | Hide the uppercase column-label header row. |
getRowId | (row, index) => string | — | Stable row key. Falls back to `row.id` then the index. |
emptyState | ReactNode | — | Rendered in place of the list when `data` is empty. |
aria-label | string | — | Accessibility label for the list. |
className | string | — | Extra wrapper classes. |
ItemListRow
| Prop | Type | Default | Description |
|---|---|---|---|
id | string | number | — | Stable id (else `getRowId`, else the index). |
icon | ComponentType<{ className?: string }> | — | Leading icon (use this OR `image`). |
image | string | — | Leading image URL (use this OR `icon`). |
imageAlt | string | — | Alt text for `image`. |
title | ReactNode | — | Primary label in the leading cell. |
subtitle | ReactNode | — | Secondary muted label under the title. |
actions | ItemListAction[] | — | Animated icon-action buttons rendered before the chevron. |
href | string | — | Navigate here when the chevron is clicked (renders an `<a>`). |
target | HTMLAttributeAnchorTarget | — | Anchor target for `href`. |
onNavigate | (row) => void | — | Alternative to `href` — called when the chevron is clicked. |
[key] | ReactNode | — | Any other key becomes a data column. The value may be any node — text, a Badge, a Select, an Input, etc. |
ItemListColumn
| Prop | Type | Default | Description |
|---|---|---|---|
key | string | — | Row key this column reads. |
header | ReactNode | — | Header label. Defaults to a humanized version of `key`. |
align | "start" | "center" | "end" | "start" | Text alignment for the column. |
width | string | number | — | Track width (number = px). Defaults to a flexible `1fr`. |
render | (value, row) => ReactNode | — | Custom cell renderer. Without it the raw value renders as-is. |
className | string | — | Extra classes on the cell. |
ItemListAction
| Prop | Type | Default | Description |
|---|---|---|---|
icon | AnimatedIconComponent | — | Animated (motion) Lucide icon — e.g. `FoldersIcon` from `@/components/ui/folders`. Plays its animation on hover. |
label | string | — | Accessible label + tooltip. |
onClick | (e) => void | — | Fires when the action is clicked. |
disabled | boolean | — | Disables the action. |