Dashboard Components
Compose accessible dashboard headers, statistics, activity feeds, progress cards, and layouts with Puzzle Pieces.
Dashboard compositions provide reusable structure for product and admin interfaces without coupling presentation to a router, data model, or framework.
Beta API maturity: Beta. These compositions are new and may evolve based on feedback.
Installation
Import the dashboard components from Puzzle Pieces:
import {
DashboardActivityFeed,
DashboardHeader,
DashboardProgressCard,
DashboardShell,
DashboardStatCard,
DashboardStatGroup,
} from "@puzzle-ui/pieces";Dashboard header
Use the header for the page title, supporting text, and caller-provided actions.
Statistics
DashboardStatGroup arranges any children into a responsive grid. Compose it with DashboardStatCard; the card supports an icon, trend, description, action slot, and loading state.
Activity feed
Activity items are generic records supplied by the consuming application. Use renderItem when an item needs a custom presentation; otherwise the component renders optional avatars, links, and semantic timestamps.
Progress card
Use a native progress element with a title-derived accessible label.
Dashboard shell
DashboardShell composes caller-provided topbar, sidebar, and page content. Navigation and routing remain the responsibility of the application.
<DashboardShell
topbar={<WorkspaceTopbar />}
sidebar={<WorkspaceNavigation />}
sidebarLabel="Workspace navigation"
>
<DashboardHeader title="Overview" />
<DashboardStatGroup>{/* cards */}</DashboardStatGroup>
</DashboardShell>Accessibility and responsive behavior
- The header uses a level-one heading; place only one
DashboardHeaderon a page. DashboardStatGroupis a labelled region. Cards expose their labels as headings.- Loading cards expose
aria-busyand hide decorative placeholders from assistive technology. - Activity feeds use an ordered list and native
<time>elements; provide stable item IDs and machine-readabledateTimevalues when available. - Progress cards use the native
<progress>element. Provide a value from0to100. - Shell landmarks and sidebar labels are semantic; supply meaningful labels when composing multiple landmarks.
- Layouts adapt to narrow viewports and use Puzzle theme tokens for colors, spacing, borders, and typography.
API
| Component | Props |
|---|---|
DashboardHeader | title (required), eyebrow, description, actions, className |
DashboardStatCard | label (required), value, description, icon, trend (value, label, optional direction), action, loading, className |
DashboardStatGroup | children (required), label, columns (2, 3, or 4), className |
DashboardActivityFeed | items (required; each has id, description, timestamp, optional dateTime, avatar, href), title, emptyState, renderItem, className |
DashboardProgressCard | title (required), value (required, from 0 to 100), description, status, action, className |
DashboardShell | children (required), sidebar, topbar, sidebarLabel, className |
All content and action slots accept React nodes. Callbacks and data retrieval belong to the application.