Skip to content
WunderUI

Item Card

Free

Show one object on its own row: an icon, a title with a description, a short fact and one action.

npx wunderui-cli add item-card

Playground

Q3 report.pdf

2.4 MB, shared by Nora Lindgren

2d ago

Installation

bash
npx wunderui-cli add item-card

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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 for

  • List Group for a plain list of rows in one frame, divided by lines
  • Card for an object with media, several parts and a footer
  • Data Table for many rows that people sort, filter or compare by column

Content

Meta holds a short fact, as text or a Badge. Action holds one control, a Button or an icon button, and both stay at full width on the right.

Q3 report.pdf

2.4 MB, shared by Nora Lindgren

Text

Title and description are cut to one line with an ellipsis. Give the full text another way if it matters.

Q3 report.pdf

2.4 MB, shared by Nora Lindgren

2d ago

Group

ItemCardGroup frames cards that belong together and puts 8 px between them. A card on its own draws its own border.

Q3 report.pdf

2.4 MB, shared by Nora Lindgren

2d ago

Cover

ItemCardCover is a clickable tile: a 96 px band in one of the nine tints with an icon, logo or image in it, then the name and one line of detail. Use it for projects, boards and workspaces in a grid. It replaces ProjectCard.

File

ItemCardFile is a file tile: a 120 px preview (an icon on a tint, or an image), the name and the details. onOpen makes the preview a button, onSelectedChange shows a checkbox on hover and while selected, onMenu adds a menu button and deletedAt turns the details into a red line without menu or checkbox. It replaces FileCard.

Q3 report.pdf

2.4 MB, edited today

Keyboard interactions

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

TaborShiftTab
Moves focus to the next or previous control in the cards, for example the action button of each card in turn.
EnterorSpace
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 and motion

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

The parts a card is made of, numbered in the figure. ItemCardGroup is the frame around several cards and is described in the list.

Q3 report.pdf

2.4 MB, shared by Nora Lindgren

2d ago
  • 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.

  • Optional

    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.

  • The title in 14 px semibold, cut to one line with an ellipsis.

  • Optional

    The description under the title in 13 px secondary text, also cut to one line.

  • Optional

    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.

  • Optional

    One control at the far right, usually a Button or an icon button. It never shrinks and keeps its own focus and click behaviour.

  • Optional

    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.

  • data-slot="item-card-cover"Optional

    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.

  • data-slot="item-card-file"Optional

    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.

  • Optional
  • Optional

Best practices

  • 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.

  • Do

    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.

  • Do

    Keep the title and description short, or give the full text another way. Both are cut to one line with an ellipsis.

  • Do

    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

    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

Item Card and Item Card Group render a div and take only the props below, with no other attributes. Item Card has no click handler: put the control in the action slot. ItemCardCover and ItemCardFile take only the props listed under them.

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.

PropTypeDefaultDescription
title requiredReact.ReactNode—The name of the object, in 14 px semibold. It is cut to one line with an ellipsis. Required.
descriptionReact.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.
iconReact.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.
metaReact.ReactNode—A short fact on the right in 12 px tertiary text, such as . It can also be a Badge. It never shrinks.
actionReact.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.
classNamestring—Classes for the card, for example a width such as . They are merged after the card's own classes.

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.

PropTypeDefaultDescription
children requiredReact.ReactNode—The cards of the set. The group stacks them with 8 px between them.
classNamestring—Classes for the frame, for example a width such as .

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.

PropTypeDefaultDescription
name requiredReactNode—The name, cut to one line. Required.
metaReactNode—One short line under the name, such as a task count or a due date.
color"indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative""indigo"The tint of the cover band: (default), , , , , , , or .
coverReactNode—An icon, logo or image in the middle of the band. The icon takes the tint's text colour.
onClick() => void—Called when the tile is pressed.
classNamestring—Extra classes on the tile, for example a width.

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.

PropTypeDefaultDescription
name requiredReactNode—The file name, cut to one line. Required.
metaReactNode—The details under the name, such as the size and the date.
iconReactNode—The icon in the preview, a file icon by default.
color"indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative""red"The tint behind the icon: (default) or any other tint.
thumbnailstring—The address of an image that replaces the icon tile.
selectedboolean—Shows the selected border. With the checkbox is visible while selected.
onSelectedChange(selected) => void—Adds a checkbox in the top left corner of the preview, shown on hover, focus and while selected.
deletedAtReactNode—A red line such as Deleted 3 days ago. It hides the menu button.
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.
classNamestring—Extra classes on the tile.

PropTypeDefaultDescription
name requiredReactNode—
color"indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative"—
deletedAtReactNode—Type=trash — deletion line shown in red, no menu/checkbox.
iconReactNode—
metaReactNode—
onMenu() => void—
onOpen() => void—
onSelectedChange(selected) => void—
selectedboolean—
thumbnailstring—Image preview instead of the icon tile.

PropTypeDefaultDescription
name requiredReactNode—
color"indigo" | "blue" | "purple" | "pink" | "red" | "orange" | "yellow" | "green" | "alternative"—Tint of the cover band.
coverReactNode—Icon, logo or image in the middle of the cover.
metaReactNode—One short line under the name.
onClick() => void—

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("item-card")
Installnpx wunderui-cli add item-card

The full library index for assistants is at /llms.txt.