developer guide
Charts
Thirty-five chart types drawn from a grid's own filtered rows. Optional, and it imports nothing from the grid core.
Load the module
The charts module is a separate entry point, so a page that never charts never loads it. It imports nothing from the grid core, the grid is handed in, so the bundle carries the drawing and none of the grid.
import { createChart } from '@toclocoinc/lattice-grid/modules/charts';A chart is one call
Hand createChart a grid, a container, a type, and the columns for the category
(x) and the measure (y). A categorical chart groups by x and
reduces y for you.
const chart = createChart({
grid, // the grid to read
container: '#revenue', // an element or a selector
type: 'bar',
x: 'region', // the category column
y: 'charge', // the measure column
});It follows the grid
A chart reads the grid's filtered rows, not a snapshot taken when it was made. Filter, sort or edit the grid and every chart bound to it redraws on the next frame, with nothing to subscribe to and nothing to keep in step. A chart of rows the user cannot see would be describing a different data set.
Measures and reductions
y is a column name for the common case. When the reduction matters, or a chart carries
more than one measure, give an object or a measures array. series splits a
measure into one series per distinct value.
// A measure that needs a particular reduction:
createChart({ grid, container, type: 'bar', x: 'region',
y: { col: 'charge', fn: 'sum' } });
// Several measures at once:
createChart({ grid, container, type: 'line', x: 'date',
measures: [{ col: 'in', fn: 'sum' }, { col: 'out', fn: 'sum' }] });The thirty-five types
What a family reads is the encoding it takes.
| Family | Types | Takes |
|---|---|---|
| Cartesian | line, step, area, rangeArea, bar, horizontalBar, waterfall, scatter, bubble | x, y, optional series |
| Two axes | combo, pareto | x, measures |
| Distribution | histogram, boxplot | y alone |
| Matrix | heatmap | x, y, series |
| Part to whole | pie, donut, sunburst, treemap | x, y |
| Specialist | radar, gauge, funnel, candlestick | varies; candlestick takes open, high, low, close |
| Geographic | geomap | an ISO code, a value |
| Flow | sankey, chord, network | source, target, y |
| Over time | stream, marimekko, violin, gantt | varies; gantt takes label, start, end |
| Statistical | correlogram, qq, ecdf, lorenz, control | a column, or a set of them |
A chart given data it cannot draw, a candlestick with three measures rather than four, says so on the chart rather than drawing nothing, because a chart that silently draws nothing is indistinguishable from one that is broken.
Events and click-to-filter
A chart emits point:click, point:hover and series:toggle. The
common use is filtering the grid from a mark, which makes the pair two views of one selection rather
than a chart beside a table.
chart.on('point:click', ({ point }) => {
grid.filters.set({ col: 'region', op: 'eq', value: point.x });
});The geomap and ISO codes
A geomap reads a code column and a value column. Codes are accepted as ISO 3166-1 alpha-2
(GB), alpha-3 (GBR) or numeric (826) and normalised to
alpha-2. By default a country code lands on the continent it belongs to, so a grid of country data
produces a continent map with no second column; supplying shapes switches it to countries. A code
that matches nothing is reported rather than dropped. The full list is the
geomap demo's reference.
createChart({
grid,
container: '#map',
type: 'geomap',
code: 'country', // the column holding ISO codes
y: { col: 'revenue', fn: 'sum' },
});See the charts overview and the live demos.