Widget
FreeThe frame of one dashboard tile: a header with a title, a description and an action, a body, and a footer.
npx wunderui-cli add widgetPlayground
Traffic sources
Visitors by channel, last 7 days
Updated 2 minutes ago
Traffic sources
Traffic sources
Visitors by channel, last 7 days
Traffic sources
Visitors by channel, last 7 days
Updated 2 minutes ago
Installation
npx wunderui-cli add widgetWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Widget } from "@/components/wunderui/widget"Then use it:
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
Plan usage
Team plan, 10 seats
Plan usage
Team plan, 10 seats
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 agoPriya Raman commented
1 h agoPull request 482 merged
YesterdayTasks
Due this week
Plan usage
Team plan, 10 seats
Recent files
Edited by your team
- Q4 report.pdf2 min ago
- Checkout flow.fig1 h ago
- Brand guide.pdfYesterday
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
Traffic sources
Visitors by channel, last 7 days
No visits yet
Visits appear here after the first page view.
Traffic sources
Visitors by channel, last 7 days
Traffic sources could not be loaded.
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
Updated 2 minutes ago
- 1
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.
- 2Optional
The title as an h3 in bold 16 px text, so heading order stays intact under a level-two page heading.
- 3Optional
The description under the title in small secondary text: the period, scope or unit of the data.
- 4Optional
The action at the right end of the header, usually a plain View all button or an icon button with an aria-label.
- 5
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.
- 6Optional
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| title | ReactNode | — | The heading of the tile, rendered as an at the left of the header. With or set, the header row renders. |
| description | ReactNode | — | A second line under the title in small secondary text. It shows only when or is set. |
| action | ReactNode | — | 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. |
| 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. |
| children required | 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. |
| className | string | — | 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.
get_component("widget")npx wunderui-cli add widgetThe full library index for assistants is at /llms.txt.
Related components
Recent transactions
Last 7 days
- NLNora LindgrenWunderUI Pro, one-time+$299.00Today
- DODaniel OkaforWunderUI Core, one-time+$199.00Yesterday
- PRPriya RamanWunderUI Pro, refund-$49.00Nov 4
Data & Tables7 stylesProList PanelA dashboard card with a titled list: 31 ready panels (transactions, orders, integrations, team, activity, crypto, timelines …) with loading, empty and error states, or your own rows.