Skip to content
DocsBuild
Build

Charts

Every chart in Atmosphere is drawn by Apache ECharts. Six chart components are made for this design, and one catalog component covers thirteen more chart types.

#Two kinds of chart

Group Components Use it for
The signature set Line, Spark, Ring, Bars, Dial, Gauge The instruments of the design: carved tracks, the thermostat dial, stacked energy bands.
The catalog Chart Everything else: area, line, bar, column, donut, pie, radial bar, polar area, heatmap, scatter, radar, candlestick and treemap.

All charts are in src/components/charts/. Import each from its own file:

TSX
import { Dial } from '@/components/charts/Dial';
import { Chart } from '@/components/charts/Chart';

To see all of them, open /ui/charts and /ui/dials in the demo.

#Colors

Charts take their colors from six CSS tokens, --am-chart-1 to --am-chart-6, in src/styles/tokens/_charts.css:

Token Light theme Meaning in the demo
--am-chart-1 Tangerine #FF6A1F The main series: heating
--am-chart-2 Ice #5BB8FF Cooling, secondary series
--am-chart-3 Sun #F5C232 Lighting
--am-chart-4 Sage #3FAE7E Good, generation
--am-chart-5 Slate #5C6775 Neutral, comparison
--am-chart-6 Rose #E2566B Faults

Props such as color and colors take an index into this list, starting at 0. So colors={[0, 2, 1]} means tangerine, sun, ice.

When the theme changes, every chart reads the tokens again and changes color in place. It does not redraw from the start. To change the chart colors for your brand, change the tokens. See Theming.

#Accessibility

Screen readers cannot read a chart, so most charts take a required label: one sentence that says what the chart shows. Write what a reader should learn, for example label="Energy use by hour today, highest at 2 pm".

#Line

Area bands or lines over time. Set stacked to stack the series, as on the energy chart.

TSX
import { Line } from '@/components/charts/Line';

<Line
  series={[
    { name: 'Heating and cooling', values: hvac, color: 0 },
    { name: 'Lighting', values: lighting, color: 2 },
    { name: 'Plug loads', values: plug, color: 1 },
  ]}
  categories={hours}
  stacked
  outline
  unit="kW"
  marker={{ index: 14, label: 'Now' }}
  height={260}
/>;
Prop Type What it does
series { name, values, color? }[] The lines. color is an index into the chart colors. Required.
categories string[] One label per point. Required. Only some labels are drawn when there are many.
height number Height in pixels.
stacked boolean Stack the series into bands.
outline boolean Draw the top of the stack as a dark line.
unit string Shown after values in the tooltip and axis.
marker { index, label, tone? } A vertical line with a label, for "now" or a peak. tone is 'accent' or 'ink'.

#Spark

A small row of carved bars for a number card.

TSX
<Spark values={[4, 6, 5, 8, 7, 9, 12]} highlightLast label="Energy use, last seven days" />

Props: values, label (required), height, highlightLast.

#Ring

A full circle that shows a share of a whole.

TSX
<Ring value={71} tone="good" label="Units with someone home" />
<Ring value={38} center="38 kW" size={120} label="Solar output" />

Props: value (0 to 100), label (required), size, tone, center (the text in the middle, default the value as a percent). Tones are accent, info, good, warn and bad.

#Bars

Columns, or a ranked list on its side.

TSX
<Bars values={[42, 38, 31, 22]} categories={['Floor 12', 'Floor 4', 'Lobby', 'Garage']} horizontal unit="kWh" />

Props: values and categories (required), height, color (one index, or one per bar), unit, horizontal.

#Dial

The thermostat: an arc, ticks, a needle that sweeps to the value, and a mark for the setpoint.

TSX
import { Dial } from '@/components/charts/Dial';
import { temp } from '@/lib/format';

<Dial
  value={21.4}
  target={22}
  min={10}
  max={30}
  caption={`Target ${temp(22)}`}
  unit="°C"
  tone={mode === 'cool' ? 'info' : 'accent'}
  label="Lobby temperature"
/>;
Prop Type What it does
value number The reading the needle points at. Required.
label string Required.
target number The setpoint, marked on the rim.
min, max number The range of the scale.
size number The size in pixels.
caption string The line under the big number.
unit string The unit after the number.
tone 'accent' | 'info' Tangerine for heating, ice for cooling.

When value or target changes, the needle moves from where it was to the new value.

#Gauge

A 220-degree arc that shows a level against a limit.

TSX
<Gauge value={64} tone="info" label="Water used today" />
<Gauge value={52} center="520" tone="good" label="Carbon dioxide in the lobby" />

Props: value (0 to 100), label (required), center, tone, width.

#Chart (the catalog)

One component with one set of props for thirteen chart types. Choose the type with type.

TSX
import { Chart } from '@/components/charts/Chart';

<Chart
  type="column"
  series={[{ name: 'Cost', data: [4200, 3900, 4400, 4100] }]}
  categories={['Jun', 'Jul', 'Aug', 'Sep']}
  colors={[0]}
  unit="$"
  height={220}
  label="Monthly energy cost"
/>

<Chart
  type="donut"
  values={[52, 31, 17]}
  labels={['Heating and cooling', 'Lighting', 'Plug loads']}
  colors={[0, 2, 1]}
  centerLabel="Total"
  centerValue="1,284 kWh"
  label="Energy split by use"
/>

#Types

type Data props Notes
area, line series, categories Add stacked to stack areas.
bar, column series, categories Vertical bars. Add horizontal to lay them on their side, and stacked to stack them.
donut, pie values, labels Use centerLabel and centerValue on a donut.
radialBar values, labels Rings inside rings. Add track for a carved track behind each one.
polarArea values, labels
heatmap series of { x, y } points One series per row.
scatter series of { x, y } points
radar series, categories categories are the spokes.
candlestick series of { x, y: [open, high, low, close] }
treemap values, labels

#All props

Prop Type What it does
type see above Required.
label string The accessible summary. Required.
series { name?, data }[] For the chart types with axes. data is a list of numbers or of { x, y } points.
values number[] For donut, pie, radial bar, polar area and treemap.
categories (string | number)[] The axis labels.
labels string[] The names of values.
height number Height in pixels.
colors number[] Indexes into the chart colors.
stacked boolean Stack the series.
horizontal boolean Lay the chart on its side.
sparkline boolean Hide the axes and grid, for a tiny chart.
legend boolean Show or hide the legend.
tooltip boolean Show or hide the tooltip.
unit string Shown with values.
centerLabel, centerValue string Text in the middle of a donut or radial bar.
track boolean A carved track behind a radial bar.
className string

#Performance

ECharts is large, so it is loaded only on pages that draw a chart. It is never in the first download.

  • The six signature charts share one chunk.
  • The extra catalog types (heatmap, scatter, radar, candlestick, treemap) are in a second, smaller chunk that loads only on a page with a Chart of those types.

vite.config.ts sets this up with manualChunks. You do not need to do anything.

#Charts that are not in the set

ECharts can draw many more chart types. To add one, follow the pattern in src/components/charts/Chart.tsx:

  1. Import the chart type from echarts/charts and register it with echarts.use([...]). Import echarts from ./echarts, the one file that loads the library.
  2. Build an ECharts option from usePalette(), which gives you the theme colors, fonts and motion durations.
  3. Mount it with useChart(ref, option). It waits for the fonts, resizes with its box and updates the chart in place when the option changes.

The ECharts documentation lists every option.