MetricUIMetricUI
UI

DashboardHeader

Top-level dashboard identity bar with title, live/stale status, auto-ticking 'Updated Xm ago', breadcrumbs, back navigation, and action slots.

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

Loading
// 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" }}
/>

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

PropTypeDescription
title*
string

Dashboard title. Rendered as an h1 in monospace font.

subtitle
string

Secondary label below the title.

description
string | React.ReactNode

Content shown in a '?' popover next to the title. Use for dashboard explanation or data source info.

lastUpdated
Date

Timestamp of last data refresh. Enables auto-ticking 'Updated Xm ago' label (ticks every 15s). Turns amber when older than staleAfter minutes. Also auto-derives status to 'live' or 'stale' if status prop is not set.

staleAfter
number

Minutes before 'last updated' turns amber and status auto-switches to 'stale'. Default: 5 minutes.

status
DashboardStatus

Status badge: 'live' (green pulsing dot), 'stale' (amber dot), 'offline' (red dot), 'loading' (gray pulsing dot). Auto-derived from lastUpdated/staleAfter if not set explicitly.

back
{ href?: string; label?: string; onClick?: () => void }

Back navigation link/button. Shows arrow icon + label. Rendered as <a> if href provided, <button> otherwise. Hidden when breadcrumbs are present.

breadcrumbs
BreadcrumbItem[]

Breadcrumb trail. Each item: { label, href?, onClick? }. Last item is styled as current page. Chevron separators between items.

actions
React.ReactNode

Right-aligned action slot. Place PeriodSelector, SegmentToggle, buttons, or any controls here.

variant
CardVariant

Card variant. Falls back to MetricProvider.

dense
boolean

Compact layout. Falls back to MetricProvider.

className
string

Additional CSS class names.

classNames
{ root?, title?, subtitle?, breadcrumbs?, status?, actions? }

Sub-element class overrides.

id
string

HTML id attribute.

data-testid
string

Test id.

Data Shape

interface BreadcrumbItem {
  label: string;
  href?: string;
  onClick?: () => void;
}

type DashboardStatus = "live" | "stale" | "offline" | "loading";

Notes

  • Uses forwardRef — attach a ref to the root div.
  • Wrapped in ErrorBoundary for graceful error handling.
  • Has __gridHint = 'header' for MetricGrid auto-layout — always renders full-width at the top.
  • The status badge has a pulsing dot animation for 'live' and 'loading' states.
  • lastUpdated auto-ticks every 15s — no manual polling needed.
  • If both back and breadcrumbs are provided, breadcrumbs take priority (back is hidden).
  • Uses the card shell (border, noise texture) for consistent visual hierarchy with other MetricUI components.
  • The aiContext prop (inherited from BaseComponentProps) adds business context for AI Insights analysis. See the AI Insights guide for details.