Layout

DashboardHeader

A full-width header bar with title, live status badge, breadcrumbs, back navigation, and an actions slot. The "Updated X ago" timestamp auto-ticks every 15 seconds.

import { DashboardHeader } from "metricui";

Use DashboardHeader at the top of every dashboard page. It provides a consistent identity bar with the dashboard title, an optional subtitle, a live/stale/offline status indicator, and a right-aligned slot for action buttons or controls like PeriodSelector. Pass a lastUpdateddate and the header will automatically display "Updated Xm ago" text that re-renders every 15 seconds — no polling logic required on your side.

Basic Example

Revenue Overview

North America region

<DashboardHeader
  title="Revenue Overview"
  subtitle="North America region"
/>

Status Badges

Pass a lastUpdated date to show an auto-ticking "Updated X ago" label. The status badge is automatically derived: live when the data is fresh, stale when it exceeds staleAfter minutes (default: 5). You can also set status explicitly to override auto-derivation.

Live (just updated)

Sales Dashboard

Live

Real-time pipeline

·Updated just now

Stale (updated 10 minutes ago)

Sales Dashboard

Stale

Real-time pipeline

·Updated 10m ago

Offline (explicit status)

Sales Dashboard

Offline

Connection lost

Loading (explicit status)

Sales Dashboard

// Auto-derived from lastUpdated
<DashboardHeader
  title="Sales Dashboard"
  lastUpdated={new Date()}          // "live" badge + "Updated just now"
  staleAfter={5}                    // turns "stale" after 5 min (default)
/>

// Explicit status override
<DashboardHeader
  title="Sales Dashboard"
  status="offline"
/>

Back Navigation

The back prop renders an arrow-left link above the title. Pass an href for link navigation or an onClick for programmatic routing. The back link is hidden when breadcrumbs are also provided (breadcrumbs take precedence).

All Orders

Order #12847

Placed Jan 15, 2026

<DashboardHeader
  title="Order #12847"
  subtitle="Placed Jan 15, 2026"
  back={{ href: "/orders", label: "All Orders" }}
/>

Breadcrumbs

Pass an array of BreadcrumbItem objects to render a breadcrumb trail above the title. Each item can have an href, onClick, or neither (plain text). The last item is automatically styled as the current page.

Q1 Revenue

Live

North America

·Updated just now

<DashboardHeader
  title="Q1 Revenue"
  subtitle="North America"
  breadcrumbs={[
    { label: "Home", href: "/" },
    { label: "Dashboards", href: "/dashboards" },
    { label: "Q1 Revenue" },
  ]}
  lastUpdated={new Date()}
/>

Actions Slot

The actions prop accepts any React node and renders it right-aligned. Use it for buttons, dropdowns, a PeriodSelector, or any other control your dashboard needs.

Team Performance

Live

Engineering

·Updated just now

<DashboardHeader
  title="Team Performance"
  subtitle="Engineering"
  lastUpdated={new Date()}
  actions={
    <>
      <button className="rounded-md border border-[var(--card-border)] px-3 py-1.5 text-xs text-[var(--muted)] hover:text-[var(--foreground)]">
        Export
      </button>
      <button className="rounded-md bg-[var(--accent)] px-3 py-1.5 text-xs text-white">
        Share
      </button>
    </>
  }
/>

Dense Mode

The dense prop reduces the title size for tighter layouts. Also inherits from MetricProvider.

Normal

Revenue Overview

Live

North America

·Updated just now

Dense

Revenue Overview

Live

North America

·Updated just now

<DashboardHeader title="Revenue" dense />

// or via MetricProvider
<MetricProvider dense>
  <DashboardHeader title="Revenue" /> {/* inherits dense */}
</MetricProvider>

Props

Prop	Type	Default	Description
`title`	`string`	`(required)`	Dashboard title displayed as an h1.
`subtitle`	`string`	`—`	Secondary label below the title.
`description`	`string \| ReactNode`	`—`	Content for the info popover beside the title.
`lastUpdated`	`Date`	`—`	Enables the auto-ticking "Updated Xm ago" label. Also auto-derives the status badge.
`staleAfter`	`number`	`5`	Minutes before lastUpdated turns the status to stale (amber).
`status`	`"live" \| "stale" \| "offline" \| "loading"`	`—`	Explicit status badge. Overrides auto-derivation from lastUpdated.
`back`	`{ href?, label?, onClick? }`	`—`	Renders a back-arrow link above the title. Hidden when breadcrumbs are set.
`breadcrumbs`	`BreadcrumbItem[]`	`—`	Breadcrumb trail above the title. Each item: { label, href?, onClick? }.
`actions`	`ReactNode`	`—`	Right-aligned action slot for buttons, controls, or dropdowns.
`variant`	`CardVariant`	`—`	Card variant override. Falls back to MetricProvider.
`dense`	`boolean`	`false`	Compact title size. Falls back to MetricProvider.
`className`	`string`	`—`	Additional CSS classes on the root element.
`classNames`	`{ root?, title?, subtitle?, ... }`	`—`	Sub-element class name overrides for fine-grained styling.
`id`	`string`	`—`	HTML id attribute.
`data-testid`	`string`	`—`	Test id for automated testing.

Notes

The "Updated X ago" label auto-ticks every 15 seconds via an internal interval. No polling or manual re-renders needed on your side.
Status is auto-derived from lastUpdated and staleAfter when you don't set status explicitly. Fresh data shows a green pulsing "Live" badge; stale data shows amber "Stale".
The back link is automatically hidden when breadcrumbs are provided, so you don't need to conditionally render one or the other.
DashboardHeader uses forwardRef and passes through id, data-testid, and className.
Dense mode can be set per-component or inherited from MetricProvider.
The component is wrapped in an error boundary. If it throws, a fallback message is rendered instead of crashing the page.
The classNames prop lets you target individual sub-elements (title, subtitle, breadcrumbs, status, actions) for custom styling without overriding the root.