# Widget

A generic dashboard widget shell: header, body, footer.

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

## Install

```bash
npx wunderui-cli add widget
```

## Import

```tsx
import { Widget } from "@/components/wunderui/widget"
```

## Minimal usage

Then use it:

```tsx
import { Widget } from "@/components/ui/widget"

export function Visits() {
  return (
    <Widget title="Visits" description="Last 7 days" className="w-full max-w-[360px]">
      <p className="text-2xl font-bold text-foreground">12,480</p>
    </Widget>
  )
}
```

Expected result: A bordered tile with the bold title Visits, the description Last 7 days under it and the number 12,480 below.

## Usage

```tsx
import { Button } from "@/components/ui/button"
import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"
import { Widget } from "@/components/ui/widget"

export function TrafficSources() {
  return (
    <Widget
      title="Traffic sources"
      description="Visitors by channel, last 7 days"
      action={<Button variant="plain" size="sm">View all</Button>}
      footer={<p className="text-xs text-text-tertiary">Updated 2 minutes ago</p>}
      className="w-full max-w-[400px]"
    >
      <div className="flex flex-col gap-4">
        <Progress value={42}>
          <ProgressLabel>Direct</ProgressLabel>
          <ProgressValue />
        </Progress>
        <Progress value={31}>
          <ProgressLabel>Search</ProgressLabel>
          <ProgressValue />
        </Progress>
        <Progress value={18}>
          <ProgressLabel>Referral</ProgressLabel>
          <ProgressValue />
        </Progress>
        <Progress value={9}>
          <ProgressLabel>Social</ProgressLabel>
          <ProgressValue />
        </Progress>
      </div>
    </Widget>
  )
}
```

## When to use

### Use Widget for

- A tile on a dashboard: a list, a chart, a usage meter or a task list with a title above it
- A group of small summaries in a grid, each with an action in the header and a note in the footer
- A frame for a body you compose yourself, loading, empty and error states included

### Use something else

- [Card](https://wunderui.com/components/card) for content with media, a custom header, or a tile that is one press target
- [List Panel](https://wunderui.com/components/list-panel) for a titled list with the loading, empty and error states already built in
- [Empty State](https://wunderui.com/components/empty-state) for the message inside a body that has nothing to show

## Behavior

What the Widget does with its header, its body, its width and its states.

- **A frame, not a layout:** The Widget draws the border, card surface and spacing, and nothing else. The body is yours and takes any content, and there are no variant, size or state props.
- **The header appears with a title or an action:** The header row renders when there is a title or an action. A description is only a second line of the title, so it needs one of the two, and with neither you get just the body and footer.
- **Width and height:** The Widget fills its container and has no width prop. Figma names three widths, Compact 280, Default 360 and Wide 560 px, which you set with a class, and in a grid row the body grows to align footers.
- **Spacing:** The body sits 16 px from the border, the same as the corner radius, so a framed box inside stays square or lightly rounded. The footer sits 16 px below the body with 12 px under its divider.
- **States are content:** Loading, empty, error, stale and the other Figma body states aren't props. Keep the header and swap the body: a Skeleton, an Empty State, or a message with Retry for a failure.
- **Nothing is interactive:** The Widget has no hover, press or focus state and takes no keyboard input. Buttons in the action, body or footer are normal controls with their own focus order.
- **Plain markup:** The Widget is a plain div, not a landmark or a list, and the title is the only heading in it. Name a group of widgets with a level-two heading above them.
- **Motion and reduced motion:** The Widget adds no animation. A Skeleton or Progress bar in the body brings its own motion and its own reduced-motion fallback.

## Anatomy

- `Widget`: The frame of one dashboard tile: a bordered card with a 16 px radius, 16 px of padding and 16 px between header, body and footer.
- `Header`: A row with the title and description on the left and the action on the right. It only renders when there is a title or an action, so a description alone doesn't show.
- `Title`: The title as an h3 in bold 16 px text, so heading order stays intact under a level-two page heading.
- `Description`: The description under the title in small secondary text: the period, scope or unit of the data.
- `Action`: The action at the right end of the header, usually a plain View all button or an icon button with an aria-label.
- `Body`: The content. The body grows to fill the tile, so in a grid row the footers of tiles with different bodies line up at the bottom.
- `Footer`: The footer below a divider line: a note on the data such as Updated 2 minutes ago, or one link.

## Best practices

### Do

- Put widgets under a level-two page heading. The title renders as an h3, so the heading order stays intact.
- Keep the header to one action, such as a plain View all button or an icon button with an aria-label. More than one belongs in a menu.
- Keep the frame in loading, empty and error states and swap only the body. The tile keeps its title and place, so the page doesn't jump.
- Set the width on the box around the Widget or with a class. It fills its container, so a grid cell or a maximum width decides how wide it is.
- Use the footer for a note about the data or one link, such as Updated 2 minutes ago or Manage plan.

### Don't

- Don't set a description without a title or an action. The header isn't rendered then, so the description doesn't appear.
- Don't put a Card or another bordered box in the body. The Widget is already the frame, so use rows, dividers and Progress bars inside it.
- Don't use a Widget for content with media, a custom header or one press target for the whole tile. Use a Card.

## API reference

### Widget

| Prop | Type | Default | Description |
|---|---|---|---|
| children* | ReactNode |  | The body of the tile: a list, a chart, a meter or the content of a state. It grows to fill the height of the tile. |
| action | ReactNode |  | A control at the right end of the header, usually a plain `View all` button or an icon button. It renders the header row even without a title. |
| className | string |  | Extra classes for the frame, merged after the defaults. Use it for the width, for example `w-full max-w-[360px]`. |
| description | ReactNode |  | A second line under the title in small secondary text. It shows only when `title` or `action` is set. |
| footer | ReactNode |  | Content below a divider line: a note about the data or one link. The line and the space only render when the footer is set. |
| title | ReactNode |  | The heading of the tile, rendered as an `<h3>` at the left of the header. With `title` or `action` set, the header row renders. |

## Examples

### Width: compact, default or wide

```tsx
import { Button } from "@/components/ui/button"
import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"
import { Widget } from "@/components/ui/widget"

export function PlanUsage() {
  return (
    <Widget
      title="Plan usage"
      description="Team plan, 10 seats"
      action={<Button variant="plain" size="sm">View all</Button>}
      className="w-full max-w-[360px]"
    >
      <div className="flex flex-col gap-4">
        <Progress value={80}>
          <ProgressLabel>Seats</ProgressLabel>
          <ProgressValue />
        </Progress>
        <Progress value={62}>
          <ProgressLabel>Storage</ProgressLabel>
          <ProgressValue />
        </Progress>
        <Progress value={35}>
          <ProgressLabel>API calls</ProgressLabel>
          <ProgressValue />
        </Progress>
      </div>
    </Widget>
  )
}
```

### Content: activity, a task list, usage or recent files

```tsx
import { Button } from "@/components/ui/button"
import { Timeline } from "@/components/ui/timeline"
import { Widget } from "@/components/ui/widget"

export function ActivityWidget() {
  return (
    <Widget
      title="Activity"
      description="Checkout redesign"
      action={<Button variant="plain" size="sm">View all</Button>}
      className="w-full max-w-[360px]"
    >
      <Timeline
        compact
        items={[
          { id: "deploy", title: "Deploy finished", timestamp: "2 min ago", color: "var(--success)" },
          { id: "comment", title: "Priya Raman commented", timestamp: "1 h ago", color: "var(--primary)" },
          { id: "merge", title: "Pull request 482 merged", timestamp: "Yesterday", color: "var(--muted)" },
        ]}
      />
    </Widget>
  )
}
```

### Body state: loading, empty or error

```tsx
import { Button } from "@/components/ui/button"
import { Skeleton } from "@/components/ui/skeleton"
import { Widget } from "@/components/ui/widget"

export function TrafficSources() {
  return (
    <Widget
      title="Traffic sources"
      description="Visitors by channel, last 7 days"
      action={<Button variant="plain" size="sm">View all</Button>}
      className="w-full max-w-[360px]"
    >
      <div role="status" className="flex flex-col gap-3">
        <span className="sr-only">Loading traffic sources</span>
        <Skeleton variant="text" />
        <Skeleton variant="text" className="w-5/6" />
        <Skeleton variant="text" className="w-2/3" />
        <Skeleton variant="text" className="w-3/4" />
      </div>
    </Widget>
  )
}
```

## In context

### Dashboard row: two widgets that wrap into one column

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"
import { Widget } from "@/components/ui/widget"

export function DashboardRow() {
  return (
    <div className="grid grid-cols-[repeat(auto-fit,minmax(240px,1fr))] gap-6">
      <Widget title="Traffic sources" description="Last 7 days">
        <div className="flex flex-col gap-4">
          <Progress value={42}>
            <ProgressLabel>Direct</ProgressLabel>
            <ProgressValue />
          </Progress>
          <Progress value={31}>
            <ProgressLabel>Search</ProgressLabel>
            <ProgressValue />
          </Progress>
          <Progress value={18}>
            <ProgressLabel>Referral</ProgressLabel>
            <ProgressValue />
          </Progress>
          <Progress value={9}>
            <ProgressLabel>Social</ProgressLabel>
            <ProgressValue />
          </Progress>
        </div>
      </Widget>
      <Widget title="Tasks" description="Due this week">
        <ul className="flex flex-col gap-3">
          <li>
            <label className="flex items-center gap-3 text-sm text-foreground">
              <Checkbox defaultChecked />
              Review pull request 482
            </label>
          </li>
          <li>
            <label className="flex items-center gap-3 text-sm text-foreground">
              <Checkbox />
              Update the billing FAQ
            </label>
          </li>
          <li>
            <label className="flex items-center gap-3 text-sm text-foreground">
              <Checkbox />
              Send the Q4 report to Daniel Okafor
            </label>
          </li>
        </ul>
      </Widget>
    </div>
  )
}
```

### Plan usage: one action in the footer

```tsx
import { Button } from "@/components/ui/button"
import { Progress, ProgressLabel, ProgressValue } from "@/components/ui/progress"
import { Widget } from "@/components/ui/widget"

export function PlanUsage() {
  return (
    <Widget
      title="Plan usage"
      description="Team plan, 10 seats"
      footer={<Button variant="plain" size="sm">Manage plan</Button>}
      className="w-full max-w-[400px]"
    >
      <div className="flex flex-col gap-4">
        <Progress value={80}>
          <ProgressLabel>Seats</ProgressLabel>
          <ProgressValue />
        </Progress>
        <Progress value={62}>
          <ProgressLabel>Storage</ProgressLabel>
          <ProgressValue />
        </Progress>
        <Progress value={35}>
          <ProgressLabel>API calls</ProgressLabel>
          <ProgressValue />
        </Progress>
      </div>
    </Widget>
  )
}
```

### Open tickets: the four states, with a working Retry

```tsx
import { Badge } from "@/components/ui/badge"
import { Button } from "@/components/ui/button"
import { EmptyState } from "@/components/ui/empty-state"
import { Skeleton } from "@/components/ui/skeleton"
import { Widget } from "@/components/ui/widget"
import { CircleAlert, Inbox } from "lucide-react"

type State = "ready" | "loading" | "empty" | "error"

const tickets = [
  { id: "refund", title: "Refund for order 1,842", who: "Nora Lindgren", age: "12 min" },
  { id: "address", title: "Invoice address change", who: "Daniel Okafor", age: "1 h" },
  { id: "code", title: "Login code not received", who: "Priya Raman", age: "3 h" },
]

export function OpenTickets({ state, onRetry }: { state: State; onRetry: () => void }) {
  return (
    <Widget
      title="Open tickets"
      description="Support inbox"
      action={
        state === "ready" || state === "empty" ? (
          <Badge color="indigo" badgeStyle="light" shape="pill">
            {state === "ready" ? `${tickets.length} open` : "0 open"}
          </Badge>
        ) : undefined
      }
      className="w-full max-w-[400px]"
    >
      {state === "loading" && (
        <div role="status" className="flex flex-col gap-3">
          <span className="sr-only">Loading tickets</span>
          <Skeleton variant="text" />
          <Skeleton variant="text" className="w-5/6" />
          <Skeleton variant="text" className="w-2/3" />
        </div>
      )}
      {state === "empty" && (
        <EmptyState variant="default" className="p-6" icon={<Inbox />} title="No open tickets" description="New tickets appear here." />
      )}
      {state === "error" && (
        <div className="flex flex-col items-center gap-3 py-6 text-center">
          <p className="flex items-center gap-2 text-sm text-text-error">
            <CircleAlert className="size-4" />
            Tickets could not be loaded.
          </p>
          <Button variant="plain" size="sm" onClick={onRetry}>
            Retry
          </Button>
        </div>
      )}
      {state === "ready" && (
        <ul className="flex flex-col divide-y divide-border">
          {tickets.map((ticket) => (
            <li key={ticket.id} className="flex items-center justify-between gap-3 py-2 first:pt-0 last:pb-0">
              <div className="min-w-0">
                <p className="truncate text-sm font-medium text-foreground">{ticket.title}</p>
                <p className="text-xs text-text-tertiary">{ticket.who}</p>
              </div>
              <span className="shrink-0 text-xs text-text-tertiary">{ticket.age}</span>
            </li>
          ))}
        </ul>
      )}
    </Widget>
  )
}
```

### Widget

Title, description, action and footer around any content.

```tsx
<Widget title="Weekly active users" description="Last 7 days" action={<Button size="sm">Details</Button>}>…</Widget>
```

## For AI agents

`get_component("widget")`

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