# Item Card

A generic row card: icon, title, description, meta, action.

- Category: Core Elements
- Page: https://wunderui.com/components/item-card
- Tier: Free

## Install

```bash
npx wunderui-cli add item-card
```

## Import

```tsx
import { ItemCard, FileCard, ItemCardCover, ItemCardCoverProps, ItemCardFile, ItemCardFileProps, ItemCardGroup, ItemCardTint, ProjectCard } from "@/components/wunderui/item-card"
```

## Minimal usage

Then use it:

```tsx
import { FileText } from "lucide-react"
import { ItemCard } from "@/components/ui/item-card"

export function File() {
  return (
    <ItemCard
      icon={<FileText />}
      title="Q3 report.pdf"
      description="2.4 MB, shared by Nora Lindgren"
      meta="2d ago"
    />
  )
}
```

Expected result: You see one bordered row with an indigo file icon, the title Q3 report.pdf over its description, and 2d ago on the right.

## Usage

```tsx
import { ItemCard } from "@/components/ui/item-card"
import { Button } from "@/components/ui/button"
import { FileText } from "lucide-react"

export function Example() {
  return (
    <ItemCard
      icon={<FileText />}
      title="Q3 report.pdf"
      description="2.4 MB, shared by Nora Lindgren"
      meta="2d ago"
      action={<Button variant="plain" size="sm">Download</Button>}
    />
  )
}
```

## When to use

### Use Item Card for

- A file, a connected app or a project that stands on its own row
- A row with one action, such as Download, Connect or a menu
- A short set of related objects, framed together with ItemCardGroup

### Use something else

- [List Group](https://wunderui.com/components/list-group) for a plain list of rows in one frame, divided by lines
- [Card](https://wunderui.com/components/card) for an object with media, several parts and a footer
- [Data Table](https://wunderui.com/components/data-table) for many rows that people sort, filter or compare by column

## Keyboard

The card is a plain container, not a control. Only what you put in the action slot can take focus.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous control in the cards, for example the action button of each card in turn. |
| `Enter` or `Space` | Presses the focused action button or icon button. |

Arrow keys do not move focus between cards. Each button is a separate Tab stop, in the order the cards are written.

## Behavior

What the card does with state, content, the DOM and motion.

- **A plain row:** The card is one plain div with a rest look only: no hover fill, pressed or selected look, or focus ring. Figma also draws navigational, selectable and actionable cards, which React doesn't build.
- **One line of text:** The title and description truncate to an ellipsis instead of wrapping. The meta and action never shrink, so the text gives way first.
- **Icon tile:** The icon sits in a 40 px square with an 8 px radius in the indigo tint, and every svg inside is sized to 20 px. The tile doesn't shrink.
- **Group:** ItemCardGroup is a column with 8 px between cards, 8 px padding and a 12 px radius. The cards keep their own border inside it.
- **Density:** The card ignores the density setting, so its padding and tile stay the same in compact and comfortable. A Button in the action slot follows density as usual.
- **Motion and reduced motion:** The card adds no animation, so there is nothing to reduce. A Button or icon button in the action slot brings its own press feedback and turns it off for reduced motion.

## Anatomy

- `ItemCard`: One framed row on the card surface: 1 px border, 8 px radius, 12 px padding and 12 px between its parts. It is a plain div with no hover, focus or click state of its own.
- `Icon tile`: A 40 px indigo tint square with an 8 px radius and a 20 px icon in the tint text colour. It shows when you pass an icon.
- `Title`: The title in 14 px semibold, cut to one line with an ellipsis.
- `Description`: The description under the title in 13 px secondary text, also cut to one line.
- `Meta`: A short fact on the right in 12 px tertiary text, such as a size or a date. It never shrinks, and a Badge works here too.
- `Action`: One control at the far right, usually a Button or an icon button. It never shrinks and keeps its own focus and click behaviour.
- `ItemCardGroup`: A bordered box with a 12 px radius and 8 px padding that stacks several cards 8 px apart, for a set that belongs together.
- `ItemCardCover`: A clickable tile: a 96 px cover band in a tint, with an icon, logo or image in the middle, then the name and one line of detail. It is a button. It replaces ProjectCard.
- `ItemCardFile`: A file tile: a 120 px preview (an icon on a tint, or an image), the name and the details, with an optional selection checkbox, a menu button and a deleted state. It replaces FileCard.
- `FileCard`
- `ProjectCard`

## Best practices

### When to use

- Use an ItemCard for an object on its own row, like a file, a connected app or a project, with one action. Use a Table for rows people compare by column and List View for a plain list in one frame.

### Do

- Put the action in the action slot as a Button or icon button. The card takes no click handler, so the row itself isn't interactive.
- Give an icon button an aria-label that names its object, such as More options for Checkout redesign, so the buttons of a set can be told apart.
- Keep the title and description short, or give the full text another way. Both are cut to one line with an ellipsis.
- Use the meta slot for a short fact with its unit, such as 2.4 MB or 2d ago, or for a status Badge.

### Don't

- Don't wrap each ItemCard in a Card. It draws its own border and padding; for a set, use ItemCardGroup.
- Don't put more than one control in the action slot. Two buttons next to a long title leave no room for the text.

## API reference

### ItemCard

| Prop | Type | Default | Description |
|---|---|---|---|
| title* | React.ReactNode |  | The name of the object, in 14 px semibold. It is cut to one line with an ellipsis. Required. |
| action | React.ReactNode |  | One control at the far right, usually a Button or an icon button. It never shrinks. The card itself has no click handler, so the control carries all interaction. |
| className | string |  | Classes for the card, for example a width such as `w-80`. They are merged after the card's own classes. |
| description | React.ReactNode |  | A line under the title in 13 px secondary text, such as a size or an owner. Cut to one line. Leave it out for a card with a title only. |
| icon | React.ReactNode |  | An icon, shown in a 40 px indigo tint tile at the left. Pass a Lucide icon element; its size is set by the tile. Leave it out and the card has no tile. |
| meta | React.ReactNode |  | A short fact on the right in 12 px tertiary text, such as `2d ago`. It can also be a Badge. It never shrinks. |

### FileCard

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | ReactNode |  |  |
| className | string |  |  |
| color | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" |  |  |
| deletedAt | ReactNode |  | Type=trash — deletion line shown in red, no menu/checkbox. |
| icon | ReactNode |  |  |
| meta | ReactNode |  |  |
| onMenu | () => void |  |  |
| onOpen | () => void |  |  |
| onSelectedChange | (selected: boolean) => void |  |  |
| selected | boolean |  |  |
| thumbnail | string |  | Image preview instead of the icon tile. |

### ItemCardCover

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | ReactNode |  | The name, cut to one line. Required. |
| className | string |  | Extra classes on the tile, for example a width. |
| color | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" | "indigo" | The tint of the cover band: `indigo` (default), `blue`, `purple`, `pink`, `red`, `orange`, `yellow`, `green` or `alternative`. |
| cover | ReactNode |  | An icon, logo or image in the middle of the band. The icon takes the tint's text colour. |
| meta | ReactNode |  | One short line under the name, such as a task count or a due date. |
| onClick | () => void |  | Called when the tile is pressed. |

### ItemCardFile

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | ReactNode |  | The file name, cut to one line. Required. |
| className | string |  | Extra classes on the tile. |
| color | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" | "red" | The tint behind the icon: `red` (default) or any other tint. |
| deletedAt | ReactNode |  | A red line such as Deleted 3 days ago. It hides the menu button. |
| icon | ReactNode |  | The icon in the preview, a file icon by default. |
| meta | ReactNode |  | The details under the name, such as the size and the date. |
| onMenu | () => void |  | Adds a menu button at the end of the details. |
| onOpen | () => void |  | Makes the preview one button named Open plus the file name. |
| onSelectedChange | (selected: boolean) => void |  | Adds a checkbox in the top left corner of the preview, shown on hover, focus and while selected. |
| selected | boolean |  | Shows the selected border. With `onSelectedChange` the checkbox is visible while selected. |
| thumbnail | string |  | The address of an image that replaces the icon tile. |

### ItemCardGroup

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The cards of the set. The group stacks them with 8 px between them. |
| className | string |  | Classes for the frame, for example a width such as `w-80`. |

### ProjectCard

| Prop | Type | Default | Description |
|---|---|---|---|
| name* | ReactNode |  |  |
| className | string |  |  |
| color | "indigo" \| "blue" \| "purple" \| "pink" \| "red" \| "orange" \| "yellow" \| "green" \| "alternative" |  | Tint of the cover band. |
| cover | ReactNode |  | Icon, logo or image in the middle of the cover. |
| meta | ReactNode |  | One short line under the name. |
| onClick | () => void |  |  |

## Examples

### Content: meta and action

```tsx
import { ItemCard } from "@/components/ui/item-card"
import { Button } from "@/components/ui/button"
import { FileText } from "lucide-react"

export function Example() {
  return (
    <ItemCard
      icon={<FileText />}
      title="Q3 report.pdf"
      description="2.4 MB, shared by Nora Lindgren"
      meta="2d ago"
      action={<Button variant="plain" size="sm">Download</Button>}
    />
  )
}
```

### Text: short and long

```tsx
import { ItemCard } from "@/components/ui/item-card"

export function Example() {
  return (
    <div className="w-90">
      <ItemCard
        title="Q3 report.pdf"
        description="2.4 MB, shared by Nora Lindgren"
        meta="2d ago"
      />
    </div>
  )
}
```

### Group: one card or a set

```tsx
import { ItemCard, ItemCardGroup } from "@/components/ui/item-card"
import { FileText, FileSpreadsheet } from "lucide-react"

export function Example() {
  return (
    <ItemCardGroup className="w-96 max-w-full">
      <ItemCard icon={<FileText />} title="Q3 report.pdf" description="2.4 MB, shared by Nora Lindgren" meta="2d ago" />
      <ItemCard icon={<FileSpreadsheet />} title="Pricing model.xlsx" description="860 KB, shared by Daniel Okafor" meta="5d ago" />
    </ItemCardGroup>
  )
}
```

### Cover: a tinted band, a name and a line of detail

```tsx
import { FolderKanban } from "lucide-react"
import { ItemCardCover } from "@wunderui/react"

export function ProjectTile() {
  return (
    <ItemCardCover
      className="w-56"
      name="Website relaunch"
      meta="12 tasks, due Nov 28"
      cover={<FolderKanban className="size-8" strokeWidth={1.5} />}
      onClick={() => {}}
    />
  )
}
```

### File: a preview, a name, selection and a menu

```tsx
import { useState } from "react"
import { ItemCardFile } from "@wunderui/react"

export function FileTile() {
  const [selected, setSelected] = useState(false)

  return (
    <ItemCardFile
      className="w-56"
      name="Q3 report.pdf"
      meta="2.4 MB, edited today"
      selected={selected}
      onSelectedChange={setSelected}
      onOpen={() => {}}
      onMenu={() => {}}
    />
  )
}
```

## In context

### Files: one download action per card

Each card holds a Download button in its action. The button of a saved file turns into a disabled Saved, and Reset puts them back.

```tsx
import { useState } from "react"
import { Check, FileSpreadsheet, FileText, Image } from "lucide-react"
import { ItemCard, ItemCardGroup } from "@/components/ui/item-card"
import { Button } from "@/components/ui/button"

const ICONS = { FileText, FileSpreadsheet, Image }

const FILES = [
  { id: "report", icon: "FileText", title: "Q3 report.pdf", description: "2.4 MB, shared by Nora Lindgren", meta: "2d ago" },
  { id: "pricing", icon: "FileSpreadsheet", title: "Pricing model.xlsx", description: "860 KB, shared by Daniel Okafor", meta: "5d ago" },
  { id: "banner", icon: "Image", title: "Launch banner.png", description: "1.1 MB, shared by Priya Raman", meta: "1w ago" },
] as const

export function Files() {
  const [saved, setSaved] = useState<string[]>([])

  return (
    <ItemCardGroup className="w-full max-w-lg">
      {FILES.map((file) => {
        const Icon = ICONS[file.icon]
        const done = saved.includes(file.id)
        return (
          <ItemCard
            key={file.id}
            icon={<Icon />}
            title={file.title}
            description={file.description}
            meta={file.meta}
            action={
              <Button variant="plain" size="sm" disabled={done} onClick={() => setSaved([...saved, file.id])}>
                {done ? <Check /> : null}
                {done ? "Saved" : "Download"}
              </Button>
            }
          />
        )
      })}
    </ItemCardGroup>
  )
}
```

### Integrations: connect and disconnect

The button flips the state and the card follows: the description changes and a Connected badge appears in the meta.

```tsx
import { useState } from "react"
import { CalendarDays, Mail, Receipt, Webhook } from "lucide-react"
import { ItemCard, ItemCardGroup } from "@/components/ui/item-card"
import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"

const APPS = [
  { id: "calendar", icon: <CalendarDays />, title: "Calendar sync", on: "Synced with your calendar" },
  { id: "digest", icon: <Mail />, title: "Email digest", on: "Sent every Monday at 9:00" },
  { id: "webhooks", icon: <Webhook />, title: "Webhooks", on: "3 endpoints, last call 4 min ago" },
  { id: "export", icon: <Receipt />, title: "Billing export", on: "Invoices go to your accountant" },
]

export function Integrations() {
  const [connected, setConnected] = useState<string[]>(["calendar", "digest"])
  const toggle = (id: string) =>
    setConnected((list) => (list.includes(id) ? list.filter((item) => item !== id) : [...list, id]))

  return (
    <ItemCardGroup className="w-full max-w-lg">
      {APPS.map((app) => {
        const on = connected.includes(app.id)
        return (
          <ItemCard
            key={app.id}
            icon={app.icon}
            title={app.title}
            description={on ? app.on : "Not connected"}
            meta={on ? <Badge color="green" badgeStyle="light">Connected</Badge> : undefined}
            action={
              <Button variant="plain" size="sm" onClick={() => toggle(app.id)}>
                {on ? "Disconnect" : "Connect"}
              </Button>
            }
          />
        )
      })}
    </ItemCardGroup>
  )
}
```

### Projects: a status and a menu

A Badge in the meta tells the status, and an icon button in the action opens a menu. Each icon button names its project for assistive technology.

```tsx
import { FolderKanban, MoreHorizontal } from "lucide-react"
import { ItemCard, ItemCardGroup } from "@/components/ui/item-card"
import { Badge } from "@/components/ui/badge"
import { IconButton } from "@/components/ui/icon-button"

const PROJECTS = [
  { id: "checkout", title: "Checkout redesign", description: "Design system, 12 tasks", status: "In progress", color: "blue" },
  { id: "onboarding", title: "Onboarding emails", description: "Lifecycle, 7 tasks", status: "In review", color: "purple" },
  { id: "billing", title: "Billing page", description: "Payments, 5 tasks", status: "Done", color: "green" },
] as const

export function Projects() {
  return (
    <ItemCardGroup className="w-full max-w-lg">
      {PROJECTS.map((project) => (
        <ItemCard
          key={project.id}
          icon={<FolderKanban />}
          title={project.title}
          description={project.description}
          meta={<Badge color={project.color} badgeStyle="light">{project.status}</Badge>}
          action={
            <IconButton variant="plain" size="sm" aria-label={`More options for ${project.title}`}>
              <MoreHorizontal />
            </IconButton>
          }
        />
      ))}
    </ItemCardGroup>
  )
}
```

### Item Card / Group

Cards with an icon, title, description, details and an action, alone or in a group.

```tsx
<ItemCardGroup>
  <ItemCard icon={<Zap />} title="Automations" description="…" meta="12 active" action={<Button size="sm">Open</Button>} />
</ItemCardGroup>
```

## For AI agents

`get_component("item-card")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
