Card
FreeGroup the content of one thing, such as a project, a plan or a setting, on one surface with media, header, content and footer.
npx wunderui-cli add cardPlayground
Installation
npx wunderui-cli add cardWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import {
Card,
CardAction,
CardBanner,
CardBody,
CardContent,
CardDescription,
CardDragHandle,
CardFeedback,
CardFooter,
CardHeader,
CardIcon,
CardIndicator,
CardMedia,
CardMeta,
CardTitle,
CardTrigger,
} from "@/components/ui/card"
import type {
CardFeedbackKind,
CardFooterLayout,
CardMediaRatio,
CardOrientation,
CardVariant,
} from "@/components/ui/card"Then use it:
import { Card, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"
export function Project() {
return (
<Card className="w-80">
<CardHeader>
<CardTitle>Website redesign</CardTitle>
<CardDescription>Launch the new marketing site before the Q4 campaign.</CardDescription>
</CardHeader>
</Card>
)
}Expected result: You see one 320 px card with a hairline border and a small shadow, a title and a two-line description.
When to use
Use Card for
- Grouping the content of one thing, such as a project, a plan, a file or a person
- A settings section or a form with a title, a short explanation and a footer of actions
- A tile in a grid that opens something, or that someone selects
Use something else for
- Item Card for a row with an icon, a title, a description, meta and an action
- Metric Card for one number with its trend and an optional sparkline
- Empty State for a whole region that has nothing to show yet
Appearance
Three looks. Default has a hairline border and a small shadow, elevated a larger shadow and no border, outlined only the border.
Sizes
The default size has 16 px of padding all round and 16 px between the parts. The small size keeps 12 px, for dense grids.
Orientation
Vertical puts the media on top. Horizontal puts it on the left with the text beside it.
Media
The media sits flush with the card edges. Pick a ratio, or the fallback for a file without a preview.
Footer
A row of buttons under a line. A card with a footer is never wholly clickable, because the buttons are separate targets.
Interaction
A card is static, or it opens something. Make the whole card the target, or add a trigger when other controls sit inside it.
None
Click the card or press Enter.
Click the card or press Enter.
States
An interactive card changes its surface on hover and press and shows a focus ring. Selected and invalid looks are yours to set.
Data states
Show loading, empty, error and no access inside the card. While refreshing or after a failed refresh, the last data stays visible under a strip.
No projects yet
Create a project to start your first board.
Couldn’t load projects
Check your connection and try again.
No access
Ask the workspace owner to invite you.
Keyboard interactions
A static card has no keyboard behaviour. An interactive card is one focus stop, and a CardTrigger is a native button.
- TaborShift+Tab
- Moves focus to or away from an interactive card or a card trigger. A static card is skipped, and the buttons inside a card keep their own focus stop.
- EnterorSpace
- Runs the click handler of the focused interactive card or trigger: opens the card, or toggles a selectable one.
Card does not move the choice between sibling cards. A group of selectable cards does that itself, as in the Plans example.
Behavior and motion
What the card does with spacing, state, content and motion.
- Spacing
- The default size has 16 px padding and 16 px between header, content and footer, and the small size has 12 px. With a footer, the card drops its bottom padding.
- Surface
- The card clips its content to its corner radius, so media and banners sit flush with the edge. Avatars, rings and marks inside use the card colour for their cut-out edge.
- Interactive
- An interactive card is one target with a hover surface, a pressed surface and an indigo focus ring. Enter and Space run the click handler when the card has focus.
- Card with other controls
- A card with a menu or button uses a CardTrigger that covers it. The trigger is the only focus stop and carries the name, while the other controls sit above it and keep their own stop.
- Selected
- A selected card shows the tint surface, border and text, and keeps them on hover and press. Put the role and checked state on the card or its trigger, and add a CardIndicator for the mark.
- Media
- Media sits flush with the top edge, or the left in a horizontal card, at 160 px high or at a set ratio. A missing image shows an icon and No preview available.
- Data states
- CardFeedback replaces the card content: a skeleton while loading, then an icon, title, description and action. CardBanner sits above content that stays visible, with a spinner or a Retry.
- Names for screen readers
- CardTitle is a div, so put a heading inside it when the card opens a section of the page. An interactive card needs an aria-label when its text is not a good name.
- Motion
- The surface of an interactive card changes quickly, and the selection mark changes colour the same way. The refreshing banner shows a spinning icon.
- Reduced motion
- With reduced motion the surface and the mark change at once, and the spinner in the refreshing banner stands still.
Anatomy
The parts of a card, numbered in the figure. The figure shows a horizontal card, and the other parts are in the list.
- 1data-slot="card"
The surface, in a default, elevated or outlined style, with 16 px padding and gaps (12 px when small) and a 16 px corner radius. It can be horizontal, interactive or selected.
- 2data-slot="card-media"Optional
An image area flush with the top edge, or the left edge in a horizontal card. Put an image inside to fill it; empty, it shows a placeholder, and a ratio replaces the fixed 160 px height.
- 3data-slot="card-header"Optional
A grid for the title, the description and an optional action on the right, with an icon tile or avatar at the left if you want one.
- 4data-slot="card-title"Optional
The title of the card. It renders a div, so put a heading inside it when the card opens a section of the page.
- 5data-slot="card-description"Optional
Secondary text under the title, in the secondary text colour.
- 6data-slot="card-action"Optional
Sits top right in the header, for a menu button or one small button. It stays there however long the title runs.
- data-slot="card-icon"Optional
An icon tile for the header's leading slot: a tint surface and the icon in the tint text colour.
- data-slot="card-leading"
- 7data-slot="card-content"Optional
The body of the card. Anything goes in it: text, a list, a form, a chart.
- 8data-slot="card-footer"Optional
A row of buttons with a line above it, aligned right, split with a note, equal width or stacked. The line can be removed, and the card drops its bottom padding when a footer is present.
- data-slot="card-body"Optional
The text column of a horizontal card, next to the media. It carries the vertical padding the card does not have itself.
- data-slot="card-meta"Optional
A row for a date, a status, a category or people, in small secondary text. It wraps on a narrow card.
- data-slot="card-indicator"Optional
The radio or checkbox mark at the top right of a selectable card. It is decorative, since the card or its trigger carries the role and checked state.
- data-slot="card-trigger"Optional
A button that covers the whole card, for a card that also holds other controls. It is the card's only focus stop, and the other controls sit above it.
- data-slot="card-feedback"Optional
The data states of the whole card: loading (a skeleton), empty, error and denied, each with an optional title, description and action.
- data-slot="card-banner"Optional
A strip at the top of a card: refreshing while the data stays visible, or an error with Retry when the last data stays visible.
- data-slot="card-drag-handle"Optional
The grip for cards in a sortable list such as a board. Every drag needs a keyboard alternative, such as a Move to menu.
Best practices
- Do
Leave the padding to the card. It matches the chart, stat and metric cards, and the small size suits dense grids, so don't override padding classes.
- Do
Put a menu button or one small button in the card action. It stays top right however long the title runs.
- Do
To make the whole card the target, set it interactive and give it a role (link, button or radio) and an aria-label.
- Do
When a card holds other controls, use a CardTrigger as the one target and raise the other controls above it.
- Do
Use plain buttons in a card footer when cards repeat in a grid. A view has one main action, and a gradient button on every card leaves none.
- Do
Show data states on the card: CardFeedback for loading, empty, error and no access, CardBanner when old data stays visible while it refreshes or after a failed refresh.
- Do
Pick the footer layout by content: end for a normal row of actions, between when a note sits beside them, stretch or stacked for a narrow card.
- Don’t
Don't put a button inside a card that is itself a button or a link. Use a CardTrigger, or keep the card static.
- Don’t
Don't set a white or hex background on a card. The card colour follows the theme and dark mode, and the parts inside read it.
API reference
One table per part, in the order of the anatomy. Every part also takes the props of the HTML element it renders, such as className, style and id.
The surface, in a default, elevated or outlined style, with 16 px padding and gaps (12 px when small) and a 16 px corner radius. It can be horizontal, interactive or selected.
| Prop | Type | Default | Description |
|---|---|---|---|
| variant | "default" | "elevated" | "outlined" | "default" | has a hairline border and a small shadow, a larger shadow and no border, and only the border. |
| size | "default" | "sm" | "default" | has 16 px of padding and 16 px between the parts; has 12 px, for dense grids. |
| orientation | "horizontal" | "vertical" | "vertical" | stacks the parts, with the media on top. puts the media at the left and the text in a next to it. |
| interactive | boolean | false | Makes the whole card one target: pointer cursor, , hover, pressed and focus states, and Enter and Space run . Add a role and an . For a card with other controls, set and add a . |
| selected | boolean | false | Shows the tint surface, border and text of a chosen card. Set the role and yourself, and add a for the mark. |
An image area flush with the top edge, or the left edge in a horizontal card. Put an image inside to fill it; empty, it shows a placeholder, and a ratio replaces the fixed 160 px height.
| Prop | Type | Default | Description |
|---|---|---|---|
| ratio | "16:9" | "4:3" | "1:1" | "3:1" | — | Gives the media a shape instead of the fixed 160 px height: , , or . Without it the height is 160 px. |
| missing | boolean | false | Shows the image icon and on the page tone, for a file that has no preview. The area then has the role and a name. |
A grid for the title, the description and an optional action on the right, with an icon tile or avatar at the left if you want one.
| Prop | Type | Default | Description |
|---|---|---|---|
| leading | ReactNode | — | An icon tile () or an avatar shown at the left of the title and the description. |
The title of the card. It renders a div, so put a heading inside it when the card opens a section of the page.
Secondary text under the title, in the secondary text colour.
Sits top right in the header, for a menu button or one small button. It stays there however long the title runs.
The body of the card. Anything goes in it: text, a list, a form, a chart.
A row of buttons with a line above it, aligned right, split with a note, equal width or stacked. The line can be removed, and the card drops its bottom padding when a footer is present.
| Prop | Type | Default | Description |
|---|---|---|---|
| layout | "end" | "stacked" | "stretch" | "between" | "end" | aligns the buttons to the right, puts a note left and the actions right, makes equal buttons, and makes full-width buttons, primary first. |
| divider | boolean | true | Draws the line above the footer. Set it to for a footer that follows a card without content. |
The text column of a horizontal card, next to the media. It carries the vertical padding the card does not have itself.
An icon tile for the header's leading slot: a tint surface and the icon in the tint text colour.
A row for a date, a status, a category or people, in small secondary text. It wraps on a narrow card.
The radio or checkbox mark at the top right of a selectable card. It is decorative, since the card or its trigger carries the role and checked state.
| Prop | Type | Default | Description |
|---|---|---|---|
| type | "radio" | "checkbox" | "radio" | draws a round mark, a square one with a check. The mark is decorative: the role and belong on the card or its trigger. |
| checked | boolean | false | Fills the mark with the tint text colour and draws the dot or the check. |
A button that covers the whole card, for a card that also holds other controls. It is the card's only focus stop, and the other controls sit above it.
The data states of the whole card: loading (a skeleton), empty, error and denied, each with an optional title, description and action.
| Prop | Type | Default | Description |
|---|---|---|---|
| kind required | "error" | "loading" | "empty" | "denied" | — | shows a skeleton like the content, an inbox icon, a red warning icon and a lock. has the role . |
| title | ReactNode | — | The line under the icon, in 16 px semibold text. |
| description | ReactNode | — | One or two sentences under the title that say what happened and what to do. |
| action | ReactNode | — | A button under the text, such as or . |
| media | boolean | false | With , adds a block at the top that matches the media of the card. |
| loadingLabel | string | — | The name read out for the loading skeleton. The default is . |
| className | string | — | Extra classes for the feedback block, merged with its own. |
A strip at the top of a card: refreshing while the data stays visible, or an error with Retry when the last data stays visible.
| Prop | Type | Default | Description |
|---|---|---|---|
| kind required | "refreshing" | "error" | — | is a quiet strip with a spinning icon and the role ; is a red strip with the role . |
| children required | ReactNode | — | The text of the strip, such as or |
| action | ReactNode | — | A small button at the right end of the strip, such as . |
| className | string | — | Extra classes for the strip, merged with its own. |
The grip for cards in a sortable list such as a board. Every drag needs a keyboard alternative, such as a Move to menu.
| Prop | Type | Default | Description |
|---|---|---|---|
| dragging | boolean | false | Draws the handle in its dragging look: a grabbing cursor, the subtle fill and the foreground colour. Set it while the card is being dragged. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("card")npx wunderui-cli add cardThe full library index for assistants is at /llms.txt.
Related components
- Checkout redesignCart, address and payment steps.Design tokens v2One source for colour, type and spacing.Billing portalInvoices, plans and payment methods.AnalyticsTraffic, conversion and retention.OnboardingA short tour for new teammates.Core Elements3 stylesCarouselA horizontally scrollable row of items with arrow controls.