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:
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.
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.
<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.
<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.
<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.
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.
<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.
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
Chartof 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:
-
Import the chart type from
echarts/chartsand register it withecharts.use([...]). Importechartsfrom./echarts, the one file that loads the library. -
Build an ECharts option from
usePalette(), which gives you the theme colors, fonts and motion durations. -
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.