# Card

A bordered container for grouping related content.

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

## Install

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

## Import

```tsx
import { Card, CardAction, CardBanner, CardBody, CardContent, CardDescription, CardDragHandle, CardFeedback, CardFeedbackKind, CardFooter, CardFooterLayout, CardHeader, CardIcon, CardIndicator, CardMedia, CardMediaRatio, CardMeta, CardOrientation, CardTitle, CardTrigger, CardVariant } from "@/components/ui/card"
```

## Minimal usage

Then use it:

```tsx
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.

## Usage

```tsx
import { Card, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"

export function Example() {
  return (
    <Card className="w-80">
      <CardHeader>
        <CardTitle>Website redesign</CardTitle>
        <CardDescription>Launch the new marketing site before the Q4 campaign.</CardDescription>
      </CardHeader>
    </Card>
  )
}
```

## 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

- [Item Card](https://wunderui.com/components/item-card) for a row with an icon, a title, a description, meta and an action
- [Metric Card](https://wunderui.com/components/metric-card) for one number with its trend and an optional sparkline
- [Empty State](https://wunderui.com/components/empty-state) for a whole region that has nothing to show yet

## Keyboard

A static card has no keyboard behaviour. An interactive card is one focus stop, and a CardTrigger is a native button.

| Key | Action |
|---|---|
| `Tab` or `Shift+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. |
| `Enter` or `Space` | 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

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

- `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.
- `CardMedia`: 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.
- `CardHeader`: 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.
- `CardTitle`: The title of the card. It renders a div, so put a heading inside it when the card opens a section of the page.
- `CardDescription`: Secondary text under the title, in the secondary text colour.
- `CardAction`: Sits top right in the header, for a menu button or one small button. It stays there however long the title runs.
- `CardContent`: The body of the card. Anything goes in it: text, a list, a form, a chart.
- `CardFooter`: 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.
- `CardBody`: The text column of a horizontal card, next to the media. It carries the vertical padding the card does not have itself.
- `CardIcon`: An icon tile for the header's leading slot: a tint surface and the icon in the tint text colour.
- `CardMeta`: A row for a date, a status, a category or people, in small secondary text. It wraps on a narrow card.
- `CardIndicator`: 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.
- `CardTrigger`: 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.
- `CardFeedback`: The data states of the whole card: loading (a skeleton), empty, error and denied, each with an optional title, description and action.
- `CardBanner`: 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.
- `CardDragHandle`: The grip for cards in a sortable list such as a board. Every drag needs a keyboard alternative, such as a Move to menu.
- `Leading`

## Best practices

### When to use

- Use a Card to group the content of one thing, like a project, a plan or a settings section. For a row use Item Card, for one number Metric Card, for nothing to show yet Empty State.

### 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.
- Put a menu button or one small button in the card action. It stays top right however long the title runs.
- To make the whole card the target, set it interactive and give it a role (link, button or radio) and an aria-label.
- When a card holds other controls, use a CardTrigger as the one target and raise the other controls above it.
- 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.
- 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.
- 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 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

### Card

| Prop | Type | Default | Description |
|---|---|---|---|
| interactive | boolean | false | Makes the whole card one target: pointer cursor, `tabIndex=0`, hover, pressed and focus states, and Enter and Space run `onClick`. Add a role and an `aria-label`. For a card with other controls, set `tabIndex={-1}` and add a `CardTrigger`. |
| orientation | "horizontal" \| "vertical" | "vertical" | `vertical` stacks the parts, with the media on top. `horizontal` puts the media at the left and the text in a `CardBody` next to it. |
| selected | boolean | false | Shows the tint surface, border and text of a chosen card. Set the role and `aria-checked` yourself, and add a `CardIndicator` for the mark. |
| size | "default" \| "sm" | "default" | `default` has 16 px of padding and 16 px between the parts; `sm` has 12 px, for dense grids. |
| variant | "default" \| "elevated" \| "outlined" | "default" | `default` has a hairline border and a small shadow, `elevated` a larger shadow and no border, and `outlined` only the border. |

Also accepts React.HTMLAttributes attributes.

### CardAction

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### CardBanner

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode |  | The text of the strip, such as `Refreshing data` or `Couldn’t refresh. Showing the last loaded data.` |
| kind* | "refreshing" \| "error" |  | `refreshing` is a quiet strip with a spinning icon and the role `status`; `error` is a red strip with the role `alert`. |
| action | React.ReactNode |  | A small button at the right end of the strip, such as `Retry`. |
| className | string |  | Extra classes for the strip, merged with its own. |

### CardBody

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### CardContent

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### CardDescription

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### CardDragHandle

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

Also accepts React.ButtonHTMLAttributes attributes.

### CardFeedback

| Prop | Type | Default | Description |
|---|---|---|---|
| kind* | "error" \| "loading" \| "empty" \| "denied" |  | `loading` shows a skeleton like the content, `empty` an inbox icon, `error` a red warning icon and `denied` a lock. `error` has the role `alert`. |
| action | React.ReactNode |  | A button under the text, such as `Retry` or `New project`. |
| className | string |  | Extra classes for the feedback block, merged with its own. |
| description | React.ReactNode |  | One or two sentences under the title that say what happened and what to do. |
| loadingLabel | string |  | The name read out for the loading skeleton. The default is `Loading`. |
| media | boolean | false | With `loading`, adds a block at the top that matches the media of the card. |
| title | React.ReactNode |  | The line under the icon, in 16 px semibold text. |

### CardFooter

| Prop | Type | Default | Description |
|---|---|---|---|
| divider | boolean | true | Draws the line above the footer. Set it to `false` for a footer that follows a card without content. |
| layout | "end" \| "stacked" \| "stretch" \| "between" | "end" | `end` aligns the buttons to the right, `between` puts a note left and the actions right, `stretch` makes equal buttons, and `stacked` makes full-width buttons, primary first. |

Also accepts React.HTMLAttributes attributes.

### CardHeader

| Prop | Type | Default | Description |
|---|---|---|---|
| leading | React.ReactNode |  | An icon tile (`CardIcon`) or an avatar shown at the left of the title and the description. |

Also accepts React.HTMLAttributes attributes.

### CardIcon

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### CardIndicator

| Prop | Type | Default | Description |
|---|---|---|---|
| checked | boolean | false | Fills the mark with the tint text colour and draws the dot or the check. |
| type | "radio" \| "checkbox" | "radio" | `radio` draws a round mark, `checkbox` a square one with a check. The mark is decorative: the role and `aria-checked` belong on the card or its trigger. |

Also accepts React.HTMLAttributes attributes.

### CardMedia

| Prop | Type | Default | Description |
|---|---|---|---|
| missing | boolean | false | Shows the image icon and `No preview available` on the page tone, for a file that has no preview. The area then has the role `img` and a name. |
| ratio | "16:9" \| "4:3" \| "1:1" \| "3:1" |  | Gives the media a shape instead of the fixed 160 px height: `16:9`, `4:3`, `1:1` or `3:1`. Without it the height is 160 px. |

Also accepts React.HTMLAttributes attributes.

### CardMeta

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### CardTitle

| Prop | Type | Default |
|---|---|---|


Also accepts React.HTMLAttributes attributes.

### CardTrigger

| Prop | Type | Default |
|---|---|---|


Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Appearance: default, elevated and outlined

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"

export function Example() {
  return (
    <Card className="w-80">
      <CardHeader>
        <CardTitle>Website redesign</CardTitle>
        <CardDescription>Launch the new marketing site before the Q4 campaign.</CardDescription>
      </CardHeader>
      <CardContent>12 of 18 tasks done, 3 due this week.</CardContent>
    </Card>
  )
}
```

### Sizes: default and small

```tsx
import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"

export function Example() {
  return (
    <Card className="w-80">
      <CardHeader>
        <CardTitle>Website redesign</CardTitle>
        <CardDescription>Launch the new marketing site before the Q4 campaign.</CardDescription>
      </CardHeader>
      <CardContent>12 of 18 tasks done, 3 due this week.</CardContent>
    </Card>
  )
}
```

### Orientation: media on top or at the left

```tsx
import { Card, CardDescription, CardHeader, CardMedia, CardTitle } from "@/components/ui/card"

export function Example() {
  return (
    <Card className="w-80">
      <CardMedia ratio="16:9" />
      <CardHeader>
        <CardTitle>Website redesign</CardTitle>
        <CardDescription>Launch the new marketing site before the Q4 campaign.</CardDescription>
      </CardHeader>
    </Card>
  )
}
```

### Media: four ratios and a fallback

```tsx
import { Card, CardDescription, CardHeader, CardMedia, CardTitle } from "@/components/ui/card"

export function Example() {
  return (
    <Card className="w-56">
      <CardMedia ratio="16:9" />
      <CardHeader>
        <CardTitle>Aurora launch</CardTitle>
        <CardDescription>Campaign shots</CardDescription>
      </CardHeader>
    </Card>
  )
}
```

### Footer: end, between, stretch and stacked

```tsx
import { Button } from "@/components/ui/button"
import { Card, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"

export function Example() {
  return (
    <Card className="w-80">
      <CardHeader>
        <CardTitle>Release notes</CardTitle>
        <CardDescription>Changes since version 2.4.</CardDescription>
      </CardHeader>
      <CardFooter>
        <Button variant="plain" size="sm">
          Cancel
        </Button>
        <Button variant="gradient" size="sm">
          Save changes
        </Button>
      </CardFooter>
    </Card>
  )
}
```

### Interaction: static, the whole card or a trigger

```tsx
import { Card, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"

export function Example() {
  return (
    <Card className="w-80">
      <CardHeader>
        <CardTitle>Website redesign</CardTitle>
        <CardDescription>Launch the new marketing site before the Q4 campaign.</CardDescription>
      </CardHeader>
    </Card>
  )
}
```

### States: rest, hover, focus, pressed, selected and invalid

```tsx
import { Card, CardDescription, CardHeader, CardTitle } from "@/components/ui/card"

// Hover, pressed and focus come with `interactive`: there is nothing to add.
function openProject(id: string) {
  // navigate to the project page
}

export function Example() {
  return (
    <Card
      interactive
      role="link"
      aria-label="Open Website redesign"
      onClick={() => openProject("website-redesign")}
      className="w-80"
    >
      <CardHeader>
        <CardTitle>Website redesign</CardTitle>
        <CardDescription>Launch the new marketing site before the Q4 campaign.</CardDescription>
      </CardHeader>
    </Card>
  )
}
```

### Data states: loading, empty, error, no access and refreshing

```tsx
import { Card, CardFeedback } from "@/components/ui/card"

export function Example() {
  return (
    <Card className="w-80">
      <CardFeedback kind="loading" />
    </Card>
  )
}
```

## In context

### Projects: navigation cards in a grid

Each card is one link, so it holds no other button. Switch the state to see the loading and empty card.

```tsx
import { Badge } from "@/components/ui/badge"
import { Card, CardDescription, CardHeader, CardMedia, CardMeta, CardTitle } from "@/components/ui/card"

function openProject(id: string) {
  // navigate to the project page
}

const PROJECTS = [
  { id: "checkout", name: "Checkout redesign", text: "Cart, address and payment steps.", status: "Active", color: "green", members: 8 },
  { id: "tokens", name: "Design tokens v2", text: "One source for colour, type and spacing.", status: "In review", color: "orange", members: 5 },
  { id: "billing", name: "Billing portal", text: "Invoices, plans and payment methods.", status: "Planned", color: "grey", members: 3 },
] as const

export function Example() {
  return (
    <div className="@container">
      <div className="grid grid-cols-1 gap-6 @md:grid-cols-3">
        {PROJECTS.map((project) => (
          <Card
            key={project.id}
            interactive
            role="link"
            aria-label={"Open " + project.name}
            onClick={() => openProject(project.id)}
          >
            <CardMedia ratio="16:9" />
            <CardHeader>
              <CardTitle>{project.name}</CardTitle>
              <CardDescription>{project.text}</CardDescription>
            </CardHeader>
            <CardMeta>
              <Badge color={project.color} badgeStyle="light" shape="pill">
                {project.status}
              </Badge>
              <span>{project.members} members</span>
            </CardMeta>
          </Card>
        ))}
      </div>
    </div>
  )
}
```

### Plans: selectable cards

The cards act as a radio group: one tab stop, arrow keys move the choice, and the chosen card shows the tint and a mark.

```tsx
import { useState, type KeyboardEvent } from "react"
import { Card, CardDescription, CardHeader, CardIndicator, CardTitle } from "@/components/ui/card"

const PLANS = [
  { id: "starter", name: "Starter", text: "$0 per month, 1 project" },
  { id: "team", name: "Team", text: "$24 per user / month, unlimited projects" },
  { id: "business", name: "Business", text: "$49 per user / month, SSO and audit log" },
]

export function Example() {
  const [plan, setPlan] = useState("team")

  // Each Card with role="radio" handles the arrow keys itself: one tab stop for the group, the arrows move the choice.
  return (
    <div role="radiogroup" aria-label="Choose a plan" className="flex flex-col gap-3">
      {PLANS.map((item) => (
        <Card
          key={item.id}
          interactive
          role="radio"
          aria-checked={plan === item.id}
          tabIndex={plan === item.id ? 0 : -1}
          selected={plan === item.id}
          onClick={() => setPlan(item.id)}
        >
          <CardIndicator type="radio" checked={plan === item.id} />
          <CardHeader>
            <CardTitle>{item.name}</CardTitle>
            <CardDescription>{item.text}</CardDescription>
          </CardHeader>
        </Card>
      ))}
    </div>
  )
}
```

### Profile: avatar, tags and two actions

Only the buttons are clickable here, not the card. The menu button sits in the header action.

```tsx
import { MoreHorizontal } from "lucide-react"
import { Avatar, AvatarFallback } from "@/components/ui/avatar"
import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import { Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"
import { IconButton } from "@/components/ui/icon-button"

export function Example() {
  return (
    <Card className="w-80">
      <CardHeader
        leading={
          <Avatar color="indigo">
            <AvatarFallback>NL</AvatarFallback>
          </Avatar>
        }
      >
        <CardTitle>Nora Lindgren</CardTitle>
        <CardDescription>Product lead at WunderUI</CardDescription>
        <CardAction>
          <IconButton variant="plain" size="sm" aria-label="More options for Nora Lindgren">
            <MoreHorizontal />
          </IconButton>
        </CardAction>
      </CardHeader>
      <CardContent className="flex flex-wrap gap-2">
        <Badge color="indigo" badgeStyle="light" shape="pill">
          Design
        </Badge>
        <Badge color="grey" badgeStyle="light" shape="pill">
          Remote
        </Badge>
      </CardContent>
      <CardFooter layout="stretch">
        <Button variant="plain" size="sm">
          Message
        </Button>
        <Button variant="gradient" size="sm">
          View profile
        </Button>
      </CardFooter>
    </Card>
  )
}
```

### Settings: a card with switches

One divider between the rows, a note and the actions in the footer. Reset puts the switches back.

```tsx
import { useState } from "react"
import { Bell } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Card, CardContent, CardDescription, CardFooter, CardHeader, CardIcon, CardTitle } from "@/components/ui/card"
import { Switch } from "@/components/ui/switch"

const DEFAULTS = { digests: true, updates: true, billing: false }

const ROWS = [
  { id: "digests", label: "Email digests" },
  { id: "updates", label: "Product updates" },
  { id: "billing", label: "Billing alerts" },
] as const

export function Example() {
  const [values, setValues] = useState(DEFAULTS)

  return (
    <Card className="w-96 max-w-full">
      <CardHeader
        leading={
          <CardIcon>
            <Bell />
          </CardIcon>
        }
      >
        <CardTitle>Notifications</CardTitle>
        <CardDescription>Choose what you want to hear about.</CardDescription>
      </CardHeader>
      <CardContent className="flex flex-col divide-y divide-border">
        {ROWS.map((row) => (
          <div key={row.id} className="flex items-center justify-between gap-4 py-3 text-sm first:pt-0 last:pb-0">
            <span>{row.label}</span>
            <Switch
              aria-label={row.label}
              checked={values[row.id]}
              onCheckedChange={(checked) => setValues({ ...values, [row.id]: checked })}
            />
          </div>
        ))}
      </CardContent>
      <CardFooter layout="between">
        <Button variant="plain" size="sm" onClick={() => setValues(DEFAULTS)}>
          Reset
        </Button>
        <Button variant="gradient" size="sm">
          Save preferences
        </Button>
      </CardFooter>
    </Card>
  )
}
```

### Files: select a card and keep its menu

The trigger selects the file, and the menu button sits above it with its own focus stop. A file without a preview shows the fallback.

```tsx
import { useState } from "react"
import { MoreHorizontal } from "lucide-react"
import { Card, CardAction, CardDescription, CardHeader, CardIndicator, CardMedia, CardTitle, CardTrigger } from "@/components/ui/card"
import { IconButton } from "@/components/ui/icon-button"

const FILES = [
  { id: "brand", name: "Q3 brand guidelines.pdf", meta: "PDF · 4.2 MB", missing: false },
  { id: "pricing", name: "Pricing sheet.xlsx", meta: "XLSX · 1.8 MB", missing: true },
  { id: "launch", name: "Launch checklist.docx", meta: "DOCX · 96 KB", missing: false },
]

export function Example() {
  const [selected, setSelected] = useState<string[]>(["brand"])

  const toggle = (id: string) =>
    setSelected(selected.includes(id) ? selected.filter((item) => item !== id) : [...selected, id])

  return (
    <div className="@container">
      <div className="grid grid-cols-1 gap-6 @md:grid-cols-3">
        {FILES.map((file) => {
          const on = selected.includes(file.id)
          return (
            <Card key={file.id} interactive tabIndex={-1} selected={on}>
              <CardMedia ratio="16:9" missing={file.missing} />
              <CardIndicator type="checkbox" checked={on} className="top-3 right-3" />
              <CardHeader>
                <CardTitle>{file.name}</CardTitle>
                <CardDescription>{file.meta}</CardDescription>
                <CardAction>
                  <IconButton variant="plain" size="sm" aria-label={"Actions for " + file.name} className="relative z-10">
                    <MoreHorizontal />
                  </IconButton>
                </CardAction>
              </CardHeader>
              <CardTrigger role="checkbox" aria-checked={on} aria-label={file.name} onClick={() => toggle(file.id)} />
            </Card>
          )
        })}
      </div>
    </div>
  )
}
```

### Invitation: accept, decline or expired

A pending invitation has two stacked buttons. An expired one turns invalid and says why.

```tsx
import { Button } from "@/components/ui/button"
import { Card, CardDescription, CardFooter, CardHeader, CardTitle } from "@/components/ui/card"

export function Example() {
  return (
    <Card className="w-80">
      <CardHeader>
        <CardTitle>Invitation to Q3 Planning</CardTitle>
        <CardDescription>Sent by Daniel Okafor on Nov 2, 2026.</CardDescription>
      </CardHeader>
      <CardFooter layout="stacked">
        <Button variant="gradient">Accept invitation</Button>
        <Button variant="plain">Decline</Button>
      </CardFooter>
    </Card>
  )
}
```

## For AI agents

`get_component("card")`

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