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


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
type | Data | Use for |
|---|---|---|
line | labels, series | Trends over time |
area | labels, series | Trends where the volume matters |
stacked-area | labels, series | How a total over time splits into parts |
bar | labels, series | Comparing periods or categories |
stacked-bar | labels, series | Parts of a total, per period |
horizontal-bar | labels, series | Ranking categories, especially with long names |
donut | slices, centerLabel, centerSubLabel | Share of a whole (five slices or fewer) |
gauge | value, min, max, thresholds, label | One value against a limit |
scatter | series with { x, y } points | Whether two values move together |
sparkline | One series | A tiny trend in a tile or table cell |
Area and stacked area


Figure 2: An area chart


Figure 3: A stacked area chart of covers by service
Bars


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


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


Figure 6: A horizontal bar chart ranking stores
Donut and 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


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


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


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
| Option | Default | What 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, centerSubLabel | none | Donut centre text |
value, min, max | min, 0, 100 | Gauge value and range |
thresholds | none | Gauge colour bands: { upTo, color } |
label | the card's title | The chart's accessible name, and the gauge caption |
format | toLocaleString() | Formats axis ticks, tooltips and the gauge value |
height | 240px (gauge 160px, sparkline 36px) | The height reserved before data arrives |
legend | on for more than one series (always on for donuts) | Shows the legend |
emptyText | "No data yet" | The message when there's no data |
options | none | Chart.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.
Related
- KPI tiles
- Heatmap
- Page patterns: the dashboard