Skip to content
WunderUI

Widget

Free

The frame of one dashboard tile: a header with a title, a description and an action, a body, and a footer.

npx wunderui-cli add widget

Playground

Traffic sources

Visitors by channel, last 7 days

Direct
x
Search
x
Referral
x
Social
x

Updated 2 minutes ago

Installation

bash
npx wunderui-cli add widget

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

Then import what you need:

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

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.

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 for

  • Card for content with media, a custom header, or a tile that is one press target
  • List Panel for a titled list with the loading, empty and error states already built in
  • Empty State for the message inside a body that has nothing to show

Width

A Widget fills the box it sits in. Set the width on the box: 280 px for a compact tile, 360 px by default, 560 px for a wide one.

Plan usage

Team plan, 10 seats

Seats
x
Storage
x
API calls
x

Content

The body takes any content. Build it from the components that already draw it, such as a Timeline, a list of checkboxes, Progress bars or file rows.

Activity

Checkout redesign

Deploy finished

2 min ago

Priya Raman commented

1 h ago

Pull request 482 merged

Yesterday

Body state

A Widget has no loading or error state. Keep the frame and swap the body: a Skeleton while it loads, an Empty State when there is nothing, a message with Retry when it failed.

Traffic sources

Visitors by channel, last 7 days

Loading traffic sources

Behavior and motion

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

The parts of a Widget with every slot filled, numbered in the figure. The header is the row that holds the title, description and action.

Traffic sources

Visitors by channel, last 7 days

Direct
x
Search
x

Updated 2 minutes ago

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

  • Optional

    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.

  • Optional

    The title as an h3 in bold 16 px text, so heading order stays intact under a level-two page heading.

  • Optional

    The description under the title in small secondary text: the period, scope or unit of the data.

  • Optional

    The action at the right end of the header, usually a plain View all button or an icon button with an aria-label.

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

  • Optional

    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.

  • Do

    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.

  • Do

    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.

  • Do

    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.

  • Do

    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

    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

    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 is a plain component: it takes the props below and passes nothing else on to its element.

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.

PropTypeDefaultDescription
titleReactNode—The heading of the tile, rendered as an at the left of the header. With or set, the header row renders.
descriptionReactNode—A second line under the title in small secondary text. It shows only when or is set.
actionReactNode—A control at the right end of the header, usually a plain button or an icon button. It renders the header row even without a title.
footerReactNode—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.
children requiredReactNode—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.
classNamestring—Extra classes for the frame, merged after the defaults. Use it for the width, for example .

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("widget")
Installnpx wunderui-cli add widget

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