# Dashboards

Summarizes system metrics, such as throughput, in tiles, filters, and charts.

## Overview

A dashboard addresses one question, such as how the latest benchmark run performed. [Tempo Performance](/docs/products/tempo-performance) uses the pattern: a run header, filters for the run and scenario, a row of metric tiles, and sections of charts.

> [!NOTE]
> The library has no chart component. The examples are reference layouts with placeholder bars drawn with `style`. Render the plot with your charting library.

## Recommended Structure

Build the page in this order, from top to bottom.

* **Header (1):** The page title, the run's date, commit, and duration, and a [Badge](/docs/components/badge) for its type, such as Nightly.
* **Filters (2):** One row of labelled controls that apply on change.
* **Metric Tiles (3):** Four to eight headline numbers in [Surface](/docs/components/surface) tiles, most important first.
* **Chart Sections (4):** One [Surface](/docs/components/surface) per chart, under section headings such as Throughput.
* **Detail Tables (5):** A [Table](/docs/components/table) of exact values, such as p50, p95, and p99 timings.

```tsx
import { Badge, Button, ChoiceGroup, Field, Grid, Popover, Select, Skeleton, Stack, style, Surface } from '@tempoxyz/ds'
import { InfoCircle } from '@tempoxyz/ds/icons'
import { useState } from 'react'

export const fill = true
const runs = {
  'main-2026-10-17-8c1d04ef': 'main-2026-10-17-8c1d04ef',
  'main-2026-10-18-a41f9e20': 'main-2026-10-18-a41f9e20',
  'main-2026-10-19-296be2ab': 'main-2026-10-19-296be2ab',
}

const scenarios = { mix: 'Public mix, multi-region', transfers: 'Transfers, single region' }

const metrics = [
  ['Settled TPS', '14,960', 'TPS', 'Median settled throughput across 142 measured blocks.'],
  ['Block time', '633', 'ms', 'Median time between consecutive blocks.'],
  ['Blocks', '142', undefined, 'Blocks produced during the measured window.'],
  ['Avg gas/s', '1.38', 'Ggas', 'Mean gas processed per second.'],
  ['Peak gas/s', '2.00', 'Ggas', 'Highest gas processed in any one second.'],
  ['Accounts', '1,000', undefined, 'Accounts sending transactions during the run.'],
] as const

const throughput = [14.2, 14.8, 15.1, 14.6, 15.4, 14.9, 15.0, 14.4, 15.2, 14.7, 15.3, 14.9]

function Metric(props: { info: string; label: string; unit?: string | undefined; value: string }) {
  return (
    <Surface size="small">
      <dt {...styles.label()}>
        {props.label}
        <Popover.Root>
          <Popover.Trigger
            aria-label={`About ${props.label}`}
            openOnHover
            render={<Button shape="icon" size="small" variant="tertiary" />}
          >
            <InfoCircle />
          </Popover.Trigger>
          <Popover.Popup>
            <Popover.Title>{props.label}</Popover.Title>
            <Popover.Description>{props.info}</Popover.Description>
          </Popover.Popup>
        </Popover.Root>
      </dt>
      <dd {...styles.value()}>
        {props.value}
        {props.unit && <span {...styles.unit()}> {props.unit}</span>}
      </dd>
    </Surface>
  )
}

export function Demo() {
  const [quantile, setQuantile] = useState('p50')

  return (
    <Stack gap="24" {...styles.page()}>
      <header {...styles.header()}>
        <Badge size="small">Nightly</Badge>
        <h1 {...styles.title()}>Benchmark run</h1>
        <p {...styles.meta()}>
          Oct 20, 2026, 3:01 AM · Commit <code {...styles.mono()}>296be2a</code> · 2m 35s
        </p>
      </header>
      <div {...styles.filters()}>
        <Field.Root {...styles.filter()}>
          <Field.Label>Run</Field.Label>
          <Select.Root defaultValue="main-2026-10-19-296be2ab" items={runs}>
            <Select.Trigger>
              <Select.Value {...styles.mono()} />
              <Select.Icon />
            </Select.Trigger>
            <Select.Popup size="small">
              {Object.entries(runs).map(([value, label]) => (
                <Select.Item key={value} value={value}>
                  <Select.ItemText {...styles.mono()}>{label}</Select.ItemText>
                </Select.Item>
              ))}
            </Select.Popup>
          </Select.Root>
        </Field.Root>
        <Field.Root {...styles.filter()}>
          <Field.Label>Scenario</Field.Label>
          <Select.Root defaultValue="mix" items={scenarios}>
            <Select.Trigger>
              <Select.Value />
              <Select.Icon />
            </Select.Trigger>
            <Select.Popup size="small">
              {Object.entries(scenarios).map(([value, label]) => (
                <Select.Item key={value} value={value}>
                  <Select.ItemText>{label}</Select.ItemText>
                </Select.Item>
              ))}
            </Select.Popup>
          </Select.Root>
        </Field.Root>
        <div {...styles.quantile()}>
          <span id="quantile-label" {...styles.legend()}>
            Timing quantile
          </span>
          <ChoiceGroup.Root
            aria-labelledby="quantile-label"
            onValueChange={(value) => setQuantile(String(value))}
            size="small"
            value={quantile}
          >
            <ChoiceGroup.Item value="p50">p50</ChoiceGroup.Item>
            <ChoiceGroup.Item value="p95">p95</ChoiceGroup.Item>
            <ChoiceGroup.Item value="p99">p99</ChoiceGroup.Item>
          </ChoiceGroup.Root>
        </div>
      </div>
      <dl {...styles.tiles()}>
        {metrics.map(([label, value, unit, info]) => (
          <Metric info={info} key={label} label={label} unit={unit} value={value} />
        ))}
      </dl>
      <Grid fit="large" gap="16">
        <Surface render={<section aria-labelledby="tps-title" />} size="medium">
          <Surface.Header>
            <Surface.Title id="tps-title">Settled TPS</Surface.Title>
          </Surface.Header>
          <div
            aria-label="Settled TPS per block, between 14,200 and 15,400"
            role="img"
            {...styles.plot()}
          >
            {throughput.map((value, index) => (
              <span key={index} {...styles.bar({ style: { height: `${(value - 13) * 40}%` } })} />
            ))}
          </div>
          <p {...styles.caption()}>Thousands of transactions per second, per block</p>
        </Surface>
        <Surface render={<section aria-labelledby="validation-title" />} size="medium">
          <Surface.Header>
            <Surface.Title id="validation-title">Block validation ({quantile})</Surface.Title>
          </Surface.Header>
          <Skeleton {...styles.plot()} />
          <p role="status" {...styles.caption()}>
            Loading chart data
          </p>
        </Surface>
      </Grid>
    </Stack>
  )
}

namespace styles {
  export const bar = style({
    backgroundColor: 'accent.blue.background',
    borderTopLeftRadius: '3xs',
    borderTopRightRadius: '3xs',
    flex: '1 !custom',
  })

  export const caption = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })

  export const filter = style({ flex: '1 1 12rem !custom', minWidth: '0' })

  export const filters = style({
    alignItems: 'flex-end',
    display: 'flex',
    flexWrap: 'wrap',
    gap: '12',
  })

  export const header = style({
    alignItems: 'flex-start',
    display: 'flex',
    flexDirection: 'column',
    rowGap: '8',
  })

  export const label = style({
    alignItems: 'center',
    color: 'content.secondary',
    columnGap: '4',
    display: 'flex',
    marginBlockEnd: '8',
    typography: 'body.b3',
    // A 24px info button keeps the label line at its text height.
    selectors: { '& button': { height: '24', marginBlock: '-4px !custom' } },
  })

  export const legend = style({ color: 'content.primary', typography: 'body.b3Strong' })

  export const meta = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })

  export const mono = style({ typography: 'mono.m1' })

  export const page = style({
    backgroundColor: 'background.primary',
    padding: '16',
    '@media 640': { padding: '32' },
  })

  export const plot = style({
    alignItems: 'flex-end',
    display: 'flex',
    gap: '4',
    height: '160',
    marginBlockEnd: '12',
  })

  export const quantile = style({ display: 'flex', flexDirection: 'column', rowGap: '8' })

  export const tiles = style({
    display: 'grid',
    gap: '12',
    gridTemplateColumns: 'repeat(2, minmax(0, 1fr)) !custom',
    margin: '0',
    '@media 768': { gridTemplateColumns: 'repeat(3, minmax(0, 1fr)) !custom' },
    '@media 1280': { gridTemplateColumns: 'repeat(6, minmax(0, 1fr)) !custom' },
  })

  export const title = style({ margin: '0', typography: 'heading.h2' })

  export const unit = style({ color: 'content.secondary', typography: 'body.b2' })

  export const value = style({
    fontVariantNumeric: 'tabular-nums !custom',
    margin: '0',
    typography: 'heading.h2',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/DashboardsOverview.tsx)

## Metric Tiles

Each tile holds a label, a value, a unit in a separate smaller span after the value, and an optional info button. Mark up the tiles as a `dl`, with each label in a `dt` and the value and unit together in a `dd`.

**Do:** Label every tile and set the unit beside the value.

```tsx
/**
 * Do example for "Dashboards" on the Dashboards page.
 * Label every tile and set the unit beside the value.
 * @module
 */
import { style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="small" {...styles.tile()}>
      <p {...styles.label()}>Block time</p>
      <p {...styles.value()}>
        633<span {...styles.unit()}> ms</span>
      </p>
    </Surface>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })

  export const tile = style({
    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
    width: '10rem !custom',
  })

  export const unit = style({ color: 'content.secondary', typography: 'body.b2' })

  export const value = style({
    fontVariantNumeric: 'tabular-nums !custom',
    margin: '0',
    paddingBlockStart: '8',
    typography: 'heading.h2',
  })
}
```

**Don't:** Show a bare number without its label or unit.

```tsx
/**
 * Don't example for "Dashboards" on the Dashboards page.
 * Don't show a bare number without its label or unit.
 * @module
 */
import { style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="small" {...styles.tile()}>
      <p {...styles.value()}>633</p>
    </Surface>
  )
}

namespace styles {
  export const tile = style({
    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
    width: '10rem !custom',
  })

  export const value = style({ margin: '0', typography: 'heading.h1' })
}
```

### Put Definitions in a Popover

A [Tooltip](/docs/components/tooltip) stays closed on touch input, and screen readers do not announce it. Put the definition in a [Popover](/docs/components/popover), and set `openOnHover` on `Popover.Trigger`. Write it in one or two sentences, such as Median settled throughput across 142 measured blocks.

### Show Change With Text

If a tile compares against a baseline, state the direction and the baseline in text, such as +4.2% vs previous run. Color can reinforce the change but never carries it alone.

## Filters

* **Short or Medium List (Select):** One choice from a short or medium list, such as the scenario.
* **Long List (Combobox):** One choice from a long, searchable list, such as 60 run IDs.
* **Few Short Options (ChoiceGroup):** Two to four short options that readers compare often, such as p50, p95, and p99.

**Do:** If a few short options fit, use a [ChoiceGroup](/docs/components/choice-group).

```tsx
/**
 * Do example for "Show Change With Text" on the Dashboards page.
 * If a few short options fit, use a ChoiceGroup.
 * @module
 */
import { ChoiceGroup } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <ChoiceGroup.Root aria-label="Timing quantile" defaultValue="p95" size="small">
      <ChoiceGroup.Item value="p50">p50</ChoiceGroup.Item>
      <ChoiceGroup.Item value="p95">p95</ChoiceGroup.Item>
      <ChoiceGroup.Item value="p99">p99</ChoiceGroup.Item>
    </ChoiceGroup.Root>
  )
}
```

**Don't:** Hide three short options behind a [Select](/docs/components/select).

```tsx
/**
 * Don't example for "Show Change With Text" on the Dashboards page.
 * Don't hide three short options behind a Select.
 * @module
 */
import { Select, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.frame()}>
      <Select.Root defaultValue="p95" items={{ p50: 'p50', p95: 'p95', p99: 'p99' }}>
        <Select.Trigger aria-label="Timing quantile">
          <Select.Value />
          <Select.Icon />
        </Select.Trigger>
      </Select.Root>
    </div>
  )
}

namespace styles {
  export const frame = style({ width: '8rem !custom' })
}
```

* **Visible labels:** Label every filter. Name a [ChoiceGroup](/docs/components/choice-group) with `aria-labelledby`.
* **Apply on change:** Do not add an Apply button for single-choice controls.
* **State in the URL:** Keep filter state in the URL, so a shared link opens the same view.
* **Scope in titles:** Name the active scope in chart titles, such as Block validation (p95).
* **One control size:** In dense dashboards, use `small` for every control in the row.

## Values and Identifiers

* **Tabular figures:** Set metric values in tabular figures, so digits keep their width on update. [Amount](/docs/components/amount) and `numeric` table cells apply them already.
* **Monospace identifiers:** Set commits and run IDs in monospace. [Hex](/docs/components/hex) and `mono` table cells apply it already.
* **One precision:** Round to the precision readers act on, such as 1.38, not 1.3812. Keep it the same across tiles, charts, and runs.
* **Larger units:** Switch to a larger unit before values pass four digits, such as 1.38 Ggas.

## Chart Containers

Frame every chart the same way, whatever library renders it.

* **Labelled Section (section):** Render each medium [Surface](/docs/components/surface) as a section, labelled by its title.
* **Fixed Height (12rem):** Keep the plot area at one height in every state and at every width.
* **Caption (Units and scope):** Place it below the plot, such as Milliseconds per block, p50.
* **Legend and Contrast (3:1):** Label series in a legend, and give each color 3:1 contrast. Teal falls short on light surfaces.
* **Text Alternative (role=img):** Summarize the plot in `aria-label`, such as its range. If readers need the values, add a [Table](/docs/components/table).

```tsx
import { Alert, ChoiceGroup, Empty, Skeleton, Stack, style, Surface } from '@tempoxyz/ds'
import { ChartBar } from '@tempoxyz/ds/icons'
import { useState } from 'react'

export const fill = true
const latency = [42, 38, 45, 51, 40, 37, 44, 48, 39, 41, 46, 43, 38, 40]

type State = 'empty' | 'error' | 'loaded' | 'loading'

export function Demo() {
  const [state, setState] = useState<State>('loaded')

  return (
    <Stack gap="16">
      <ChoiceGroup.Root
        aria-label="Chart state"
        onValueChange={(value) => setState(value as State)}
        size="small"
        value={state}
      >
        <ChoiceGroup.Item value="loaded">Loaded</ChoiceGroup.Item>
        <ChoiceGroup.Item value="loading">Loading</ChoiceGroup.Item>
        <ChoiceGroup.Item value="empty">Empty</ChoiceGroup.Item>
        <ChoiceGroup.Item value="error">Error</ChoiceGroup.Item>
      </ChoiceGroup.Root>
      <Surface render={<section aria-labelledby="latency-title" />} size="medium">
        <Surface.Header>
          <Surface.Title id="latency-title">New payload validation latency</Surface.Title>
        </Surface.Header>
        {/* The plot area keeps one height in every state, so the grid around it never shifts. */}
        <div {...styles.area()}>
          {state === 'loaded' && (
            <div
              aria-label="Validation latency per block, p50, between 37 and 51 ms"
              role="img"
              {...styles.plot()}
            >
              {latency.map((value, index) => (
                <span key={index} {...styles.bar({ style: { height: `${value * 1.6}%` } })} />
              ))}
            </div>
          )}
          {state === 'loading' && <Skeleton {...styles.fill()} />}
          {state === 'empty' && (
            <Empty.Root>
              <Empty.Icon>
                <ChartBar />
              </Empty.Icon>
              <Empty.Title>No blocks in this range</Empty.Title>
              <Empty.Description>Pick a longer range or another run.</Empty.Description>
            </Empty.Root>
          )}
          {state === 'error' && (
            <Alert intent="negative">
              <Alert.Icon />
              <Alert.Content>
                Validator telemetry didn't load.
                <Alert.Action>Retry</Alert.Action>
              </Alert.Content>
            </Alert>
          )}
        </div>
        <p role="status" {...styles.caption()}>
          {state === 'loading' ? 'Loading chart data' : 'Milliseconds per block, p50'}
        </p>
      </Surface>
    </Stack>
  )
}

namespace styles {
  export const area = style({
    alignItems: 'center',
    display: 'flex',
    height: '200',
    justifyContent: 'center',
    marginBlockEnd: '12',
  })

  export const bar = style({
    backgroundColor: 'accent.blue.background',
    borderTopLeftRadius: '3xs',
    borderTopRightRadius: '3xs',
    flex: '1 !custom',
  })

  export const caption = style({ color: 'content.secondary', margin: '0', typography: 'body.b3' })

  export const fill = style({ alignSelf: 'stretch', flex: '1 !custom' })

  export const plot = style({
    alignItems: 'flex-end',
    alignSelf: 'stretch',
    display: 'flex',
    flex: '1 !custom',
    gap: '4',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Patterns/DashboardsChartStates.tsx)

## Grid Reflow

Lay out tiles in a [Grid](/docs/components/grid) with `fit="small"` and charts with `fit="large"`, which keeps each chart at least 20rem wide. Neither needs a media query. On narrow screens, stack charts instead of shrinking them. [Responsive Layout](/docs/patterns/responsive-layout#app-shell-with-content) covers the full-width shell.

## States

* **Empty (Empty):** Inside the plot area, state why and what to try next, such as No blocks in this range.
* **Error (negative):** Place an [Alert](/docs/components/alert) with a Retry action inside the failed chart. Other charts keep working.
* **Partial Data:** Name what is missing, such as Loading validator telemetry, instead of hiding the section.
* **Updating:** Show when data last changed, such as Updated 30 s ago. Update values in place without layout shift.

**Do:** Show titles at once, and hold the plot height with a [Skeleton](/docs/components/skeleton) while
data loads.

```tsx
/**
 * Do example for "Show Change With Text" on the Dashboards page.
 * Show titles at once, and hold the plot height with a Skeleton while data loads.
 * @module
 */
import { Skeleton, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="medium" {...styles.card()}>
      <Surface.Header>
        <Surface.Title>Gas throughput</Surface.Title>
      </Surface.Header>
      <Skeleton {...styles.plot()} />
    </Surface>
  )
}

namespace styles {
  export const card = style({
    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
    width: '16rem !custom',
  })

  export const plot = style({ height: '120' })
}
```

**Don't:** Collapse the chart to a [Spinner](/docs/components/spinner), which shifts every section
below it.

```tsx
/**
 * Don't example for "Show Change With Text" on the Dashboards page.
 * Don't collapse the chart to a Spinner, which shifts every section below it.
 * @module
 */
import { Spinner, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Surface size="medium" {...styles.card()}>
      <Surface.Header>
        <Surface.Title>Gas throughput</Surface.Title>
        <Spinner aria-label="Loading gas throughput" />
      </Surface.Header>
    </Surface>
  )
}

namespace styles {
  export const card = style({
    boxShadow: '0 0 0 1px light-dark(#0000001a, #ffffff1f) !custom',
    width: '16rem !custom',
  })
}
```

## Accessibility

* **Description Lists (dl):** Screen readers pair each value with its label, and read the unit with the value.
* **Info Buttons (About Block time):** Name each by its metric. Give it more room on touch screens.
* **Announce Once (status):** Announce loading and errors once, through a status region or a [Alert](/docs/components/alert). Do not announce every live update.

## Related

[Surface](/docs/components/surface)

Use for tiles and chart containers.

[Grid](/docs/components/grid)

Use for reflowing tiles and charts.

[ChoiceGroup](/docs/components/choice-group)

Use for a few short filter options.

[Select](/docs/components/select)

Use for filters with a medium list.

[Combobox](/docs/components/combobox)

Use for filters with a long list.

[Popover](/docs/components/popover)

Use for metric definitions.

[Skeleton](/docs/components/skeleton)

Use for loading plots.

[Responsive Layout](/docs/patterns/responsive-layout)

Covers the shared breakpoints.

[Tables and Lists](/docs/patterns/tables-and-lists)

Covers exact values.

[Tempo Performance](/docs/products/tempo-performance)

Covers the benchmark dashboard.
