Dashboard

The Dashboard view is the primary landing page for authenticated users, showing key metrics, recent activity, and quick actions. It adapts to display relevant KPIs and widgets based on your application type.

Type Signature

interface DashboardViewProps {
  /** Page title */
  title?: string
  /** Page description */
  description?: string
  /** View layout mode */
  layout?: 'single' | 'column' | 'canvas' | 'vibe'
  /** Metrics/KPIs to display */
  metrics?: Array<{
    id: string
    label: string
    value: string | number
    change?: number
    trend?: 'up' | 'down' | 'neutral'
    icon?: string
  }>
  /** Widgets to display */
  widgets?: any[]
  /** Time period filter */
  period?: 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year'
  /** Enable real-time updates */
  realtime?: boolean
  /** Dashboard grid columns */
  gridColumns?: number
  /** Page-level action buttons */
  actions?: Array<{
    id: string
    label: string
    icon?: string
    onClick?: () => void
    variant?: 'default' | 'primary' | 'destructive'
  }>
  /** Child content */
  children?: React.ReactNode
}

Usage

<App name="Acme Dashboard">
  <Shell>
    <DashboardView
      title="Overview"
      period="month"
      realtime={true}
      gridColumns={3}
    >
      <MetricsPanel />
      <ChartPanel />
      <ActivityPanel />
    </DashboardView>
  </Shell>
</App>

Props

title

The page title displayed in the header. Defaults to "Dashboard".

<DashboardView title="Overview">

description

Optional page description or subtitle.

<DashboardView
  title="Overview"
  description="Key metrics and activity for the last 30 days"
>

layout

Layout mode for the dashboard content. Defaults to 'single'.

// Single column layout (default)
<DashboardView layout="single">

// Multi-column layout
<DashboardView layout="column">

// Freeform canvas layout
<DashboardView layout="canvas">

metrics

Array of key performance indicators to display at the top of the dashboard.

<DashboardView
  metrics={[
    {
      id: 'revenue',
      label: 'Revenue',
      value: '$45,231',
      change: 12.5,
      trend: 'up',
      icon: 'DollarSign'
    },
    {
      id: 'users',
      label: 'Active Users',
      value: 2350,
      change: -2.3,
      trend: 'down',
      icon: 'Users'
    },
    {
      id: 'growth',
      label: 'Growth',
      value: '18.2%',
      trend: 'up',
      icon: 'TrendingUp'
    }
  ]}
>

widgets

Dashboard widgets/panels to display. Can be any components or data.

<DashboardView
  widgets={[
    <ChartWidget type="line" data={chartData} />,
    <ActivityWidget items={recentActivity} />,
    <StatsWidget metrics={statsData} />
  ]}
>

period

Default time period for filtering dashboard data.

<DashboardView period="month">
  {/* Data filtered to last 30 days */}
</DashboardView>

<DashboardView period="quarter">
  {/* Data filtered to last 90 days */}
</DashboardView>

Available periods: 'hour', 'day', 'week', 'month', 'quarter', 'year'

realtime

Enable automatic data refresh at regular intervals.

<DashboardView realtime={true}>
  {/* Dashboard refreshes automatically */}
</DashboardView>

gridColumns

Number of columns in the dashboard grid layout. Defaults to 3.

// Two-column layout
<DashboardView gridColumns={2}>

// Four-column layout
<DashboardView gridColumns={4}>

actions

Page-level action buttons displayed in the header.

<DashboardView
  actions={[
    {
      id: 'refresh',
      label: 'Refresh',
      icon: 'RefreshCw',
      onClick: () => fetchData()
    },
    {
      id: 'export',
      label: 'Export',
      icon: 'Download',
      onClick: () => exportData()
    }
  ]}
>

App Type Specializations

Different app types show different dashboard content:

DeveloperApp Dashboard

<DashboardView
  title="API Overview"
  metrics={[
    { label: 'Requests', value: '1.2M', trend: 'up' },
    { label: 'Errors', value: '0.02%', trend: 'down' },
    { label: 'Latency', value: '45ms', trend: 'neutral' }
  ]}
>
  <APIUsageChart />
  <RecentRequestsPanel />
  <APIStatusPanel />
</DashboardView>

AdminApp Dashboard

<DashboardView
  title="Admin Overview"
  metrics={[
    { label: 'Total Users', value: 2350 },
    { label: 'Active Sessions', value: 187 },
    { label: 'Storage Used', value: '45.2 GB' }
  ]}
>
  <UserGrowthChart />
  <RecentActivityPanel />
  <SystemHealthPanel />
</DashboardView>

SaaSApp Dashboard

<DashboardView
  title="Dashboard"
  metrics={[
    { label: 'MRR', value: '$45,231', change: 12.5, trend: 'up' },
    { label: 'Customers', value: 127, change: 8, trend: 'up' },
    { label: 'Churn Rate', value: '2.1%', change: -0.5, trend: 'down' }
  ]}
>
  <RevenueChart />
  <CustomerGrowthChart />
  <UpcomingRenewalsPanel />
</DashboardView>

CRMApp Dashboard

<DashboardView
  title="Sales Dashboard"
  metrics={[
    { label: 'Pipeline Value', value: '$248K', trend: 'up' },
    { label: 'Deals Closed', value: 12, change: 3 },
    { label: 'Win Rate', value: '34%', change: 2.5, trend: 'up' }
  ]}
>
  <PipelineChart />
  <DealsClosedChart />
  <TopDealsPanel />
  <UpcomingActivitiesPanel />
</DashboardView>

Common Patterns

Metrics Grid

Display KPI cards in a responsive grid:

<DashboardView gridColumns={4}>
  <MetricCard title="Revenue" value="$45,231" change={12.5} />
  <MetricCard title="Users" value={2350} change={8} />
  <MetricCard title="Conversion" value="3.2%" change={-0.5} />
  <MetricCard title="Retention" value="94%" change={2} />
</DashboardView>

Charts and Visualizations

Mix metrics with charts:

<DashboardView
  metrics={[
    { label: 'Revenue', value: '$45,231', trend: 'up' },
    { label: 'Growth', value: '12.5%', trend: 'up' }
  ]}
  gridColumns={2}
>
  <LineChart data={revenueData} />
  <BarChart data={growthData} />
  <PieChart data={distributionData} />
  <AreaChart data={trendData} />
</DashboardView>

Activity Feed

Show recent activity alongside metrics:

<DashboardView layout="column">
  <div className="col-span-2">
    <MetricsGrid />
    <ChartsRow />
  </div>
  <div className="col-span-1">
    <ActivityFeed items={recentActivity} />
  </div>
</DashboardView>

Real-Time Dashboard

Auto-refresh for live data:

<DashboardView
  realtime={true}
  period="hour"
  actions={[
    {
      id: 'pause',
      label: 'Pause Updates',
      onClick: () => setPaused(true)
    }
  ]}
>
  <LiveMetrics />
  <RealtimeChart />
</DashboardView>

Responsive Behavior

The dashboard adapts to screen size:

Desktop (≥1024px)

┌─────────────────────────────────────┐
│  Metric  │  Metric  │  Metric       │
├─────────────────────────────────────┤
│        Chart        │   Activity    │
│                     │     Feed      │
└─────────────────────────────────────┘
3-column grid, side-by-side layout

Tablet (768px - 1023px)

┌─────────────────────────┐
│  Metric  │  Metric      │
├─────────────────────────┤
│       Chart             │
├─────────────────────────┤
│    Activity Feed        │
└─────────────────────────┘
2-column grid, stacked

Mobile (under 768px)

┌───────────────┐
│    Metric     │
├───────────────┤
│    Metric     │
├───────────────┤
│     Chart     │
├───────────────┤
│ Activity Feed │
└───────────────┘
Single column

Time Period Filtering

Control the dashboard time window:

const [period, setPeriod] = useState<TimePeriod>('month')

<DashboardView
  period={period}
  actions={[
    {
      id: 'period-selector',
      label: period,
      onClick: () => showPeriodMenu()
    }
  ]}
>
  <MetricsPanel period={period} />
  <ChartPanel period={period} />
</DashboardView>

Integration with Payload CMS

The Dashboard can auto-wire to Payload collections for data:

// Auto-fetches from Payload 'analytics' collection
<DashboardView
  collection="analytics"
  period="month"
>
  <MetricsPanel />
</DashboardView>

Best Practices

Prioritize Key Metrics

Show the most important metrics first:

// Good - focused on core business metrics
<DashboardView
  metrics={[
    { label: 'MRR', value: '$45,231' },
    { label: 'Customer Count', value: 127 },
    { label: 'Churn Rate', value: '2.1%' }
  ]}
>

// Bad - too many metrics creates noise
<DashboardView
  metrics={[
    // 15+ metrics...
  ]}
>

Use Visual Hierarchy

Organize content by importance:

<DashboardView gridColumns={3}>
  {/* Primary metrics - full width */}
  <div className="col-span-3">
    <MetricsRow />
  </div>

  {/* Main chart - 2/3 width */}
  <div className="col-span-2">
    <RevenueChart />
  </div>

  {/* Secondary info - 1/3 width */}
  <div className="col-span-1">
    <ActivityFeed />
  </div>
</DashboardView>

Optimize Loading States

Show skeleton loaders while data loads:

<DashboardView>
  {isLoading ? (
    <MetricsSkeleton />
  ) : (
    <MetricsPanel metrics={data} />
  )}
</DashboardView>

Support Empty States

Handle cases with no data gracefully:

<DashboardView>
  {data.length === 0 ? (
    <EmptyState
      title="No data yet"
      description="Connect a data source to see metrics"
      action={{ label: 'Add Data Source', onClick: () => {} }}
    />
  ) : (
    <MetricsPanel metrics={data} />
  )}
</DashboardView>

Accessibility

The Dashboard implements accessibility features:

Semantic HTML - <main>, <section>, <article>
Heading hierarchy - Proper h1-h6 nesting
Keyboard navigation - All interactive elements focusable
Screen reader labels - Descriptive ARIA labels for metrics

<DashboardView
  title="Dashboard"
  aria-label="Main dashboard with key business metrics"
>
  <section aria-labelledby="metrics-heading">
    <h2 id="metrics-heading" className="sr-only">Key Metrics</h2>
    <MetricsGrid />
  </section>

  <section aria-labelledby="charts-heading">
    <h2 id="charts-heading" className="sr-only">Performance Charts</h2>
    <ChartsGrid />
  </section>
</DashboardView>

Shell - App shell layout
Settings - Settings view
Profile - User profile view

Dashboard

On this page