Charts

On this page

phApp.chart() draws charts in the Performance Hub palette and font. They redraw when the theme changes, reserve their height so the page doesn't jump, show a message when there's no data, and have an accessible name. They're built on Chart.js 4.

Add ph-app-charts.js after ph-app.js on pages with charts:

<script defer src="https://app.performancehub.co/assets/app-kit/v1/ph-app-charts.js"></script>

Usage

A line chartA line chart

Figure 1: A line chart comparing two stores

<article class="ph-card">
  <header class="ph-card-header">
    <div>
      <h2 class="ph-card-title">Orders per day</h2>
      <p class="ph-card-description">Last 14 days, all stores</p>
    </div>
  </header>
  <div id="chart"></div>
</article>
const chart = phApp.chart('#chart', {
  type: 'line',
  labels: ['3 Nov', '4 Nov', '5 Nov' /* … */],
  series: [
    { label: 'Ormsby Point', data: [410, 432, 455 /* … */] },
    { label: 'Harrow Bay', data: [180, 176, 190 /* … */] },
  ],
  format: phApp.format.compact, // axis ticks and tooltips
  height: 240,
});

chart.update({ labels: newLabels, series: newSeries }); // after a refresh
chart.destroy();

Chart types

typeDataUse for
linelabels, seriesTrends over time
arealabels, seriesTrends where the volume matters
stacked-arealabels, seriesHow a total over time splits into parts
barlabels, seriesComparing periods or categories
stacked-barlabels, seriesParts of a total, per period
horizontal-barlabels, seriesRanking categories, especially with long names
donutslices, centerLabel, centerSubLabelShare of a whole (five slices or fewer)
gaugevalue, min, max, thresholds, labelOne value against a limit
scatterseries with { x, y } pointsWhether two values move together
sparklineOne seriesA tiny trend in a tile or table cell

Area and stacked area

An area chartAn area chart

Figure 2: An area chart

A stacked area chartA stacked area chart

Figure 3: A stacked area chart of covers by service

Bars

A bar chartA bar chart

Figure 4: A bar chart comparing this year with last year

A stacked bar chartA stacked bar chart

Figure 5: A stacked bar chart of staff and visitors per hour

A horizontal bar chartA horizontal bar chart

Figure 6: A horizontal bar chart ranking stores

Donut and gauge

A donut chart and a gaugeA donut chart and a gauge

Figure 7: A donut chart with a centre label, and a gauge in its warning band

phApp.chart('#donut', {
  type: 'donut',
  slices: [
    { label: 'Check-up', value: 620 },
    { label: 'Treatment', value: 310 },
    { label: 'Follow-up', value: 140 },
  ],
  centerLabel: '1,070',
  centerSubLabel: 'appointments',
});

phApp.chart('#gauge', {
  type: 'gauge',
  value: 72,
  max: 100,
  label: 'CPU',
  format: (n) => `${Math.round(n)}%`,
  thresholds: [
    { upTo: 70, color: 'rgb(var(--ph-green-3))' },
    { upTo: 90, color: 'rgb(var(--ph-orange-3))' },
    { upTo: 100, color: 'rgb(var(--ph-red-3))' },
  ],
});

A gauge takes the colour of the first threshold its value is at or below, or the last threshold's colour when it's above them all. Without thresholds it uses the first chart colour.

Scatter

A scatter chartA scatter chart

Figure 8: A scatter chart with one dot per customer

phApp.chart('#chart', {
  type: 'scatter',
  series: [{ label: 'Customers', data: [{ x: 12, y: 18 }, { x: 3, y: 4 } /* … */] }],
});

Sparklines

Sparklines in a tableSparklines in a table

Figure 9: Sparklines in a table column

phApp.chart(cell, { type: 'sparkline', series: [{ label: 'Orders', data: [380, 421, 455 /* … */] }] });

Sparklines are 36px tall, with no axes, legend or tooltip.

Empty charts

A chart with no dataA chart with no data

Figure 10: A chart with no data shows a message in the space it reserved

When there's nothing to draw, the chart keeps its height and shows "No data yet", or your own emptyText. A series of only zeros counts as no data; so does a donut with no slice above zero.

Options

OptionDefaultWhat it does
type(required)One of the types above
labels[]The x-axis labels (category axis)
series[]{ label, data, color? }. null in data leaves a gap.
slices[]Donut slices: { label, value, color? }
centerLabel, centerSubLabelnoneDonut centre text
value, min, maxmin, 0, 100Gauge value and range
thresholdsnoneGauge colour bands: { upTo, color }
labelthe card's titleThe chart's accessible name, and the gauge caption
formattoLocaleString()Formats axis ticks, tooltips and the gauge value
height240px (gauge 160px, sparkline 36px)The height reserved before data arrives
legendon for more than one series (always on for donuts)Shows the legend
emptyText"No data yet"The message when there's no data
optionsnoneChart.js options, merged over the kit's

phApp.chart() returns { chart, update(next), destroy() }. chart is the Chart.js instance (null while the empty state shows).

Colours

Series take the eight chart tokens in order (--ph-chart-1 to --ph-chart-8), in their light or dark values. Set color on a series or slice only when the colour means something, such as red for "Declined". See Theming.

color takes any CSS colour, in phApp.chart(), phApp.kpi() and the React chart components. Prefer tokens such as rgb(var(--ph-red-3)): the kit resolves them each time it draws, so they switch with the theme like the default colours do.

Your own Chart.js charts

ph-app-charts.js also exposes Chart.js 4 as window.Chart, with the kit's text colour, grid colour and font already set as defaults. Series colours are yours, and Chart.js draws on a canvas, which can't read CSS variables (rgb(var(--ph-red-3)) draws black). Read the token values instead, and set them again when the theme changes.

const token = (name) => `rgb(${getComputedStyle(document.documentElement).getPropertyValue(name).trim()})`;
const myChart = new Chart(canvas, {
  type: 'radar',
  data: { labels, datasets: [{ label: 'This week', data, borderColor: token('--ph-chart-1') }] },
});
phApp.onThemeChange(() => {
  myChart.data.datasets[0].borderColor = token('--ph-chart-1');
  myChart.update();
});

React

React charts come from their own entry point, so Chart.js only downloads where a chart is drawn:

import { TimeSeriesChart, BarChart, DonutChart, GaugeChart, RankedBars, HeatmapCalendar, KpiCard, Sparkline } from 'ph-app-kit-react/charts';

<TimeSeriesChart labels={labels} series={[{ label: 'Orders', data }]} area format={format.compact} height={240} />
<BarChart labels={labels} series={series} stacked />
<GaugeChart value={72} max={100} label="CPU" format={(n) => `${Math.round(n)}%`} />
<RankedBars items={[{ label: 'Ormsby Point', value: 1840 }]} limit={8} />

Load chart views lazily (React.lazy) with a skeleton of the same height as the fallback.

Accessibility

  • Each chart's canvas is an image with an accessible name: label, or else the card's title.
  • Put the key numbers in text as well (a KPI tile, a table, or the card description), since a canvas can't be read in detail.
  • Charts skip their animation when the viewer asks for reduced motion.

Choosing a chart

  • Time on the x-axis: line or area, up to about five series. For more, split the chart or let people filter.
  • Categories: bars, sorted by value. Horizontal bars when labels are long.
  • Part of a whole: a donut with five slices or fewer (group the rest as "Other"), or a stacked bar over time.
  • One number against a target: a gauge or a progress bar.
  • Daily patterns over months: a heatmap.
  • Always say the unit and period in the card title or description, and format ticks with phApp.format.