Charts and interaction

Start with the chart gallery to choose a form. Each type has a live example, its source, the fields that matter and the interactions it supports. The generated format reference defines every accepted field and each type’s required channels.

Map columns to marks

A chart needs a type, a title, one data source and an encoding. This example is fictional:

color separates series; facet makes panels. Scatter can size bubbles and label selected points. Other types require other channels: a range needs lower and upper bounds, a flow needs source and target, and a combo needs its bar and line measures. Choose those from the type’s page rather than guessing fields.

Axes, gaps and precision

Bar and area baselines start at zero. Scatter and line axes can focus on their data range; explicit axis bounds carry responsibility for what is clipped. A numeric year can use year formatting without grouping separators. Calendar strings retain their authored time precision, with UTC calendar arithmetic. Missing observations stay gaps unless the author explicitly bridges them.

Printed and readout precision use significant digits, not decimal places. readout_digits cannot be below digits. A percentage expects a fraction; a unit labels values and does not convert them. A source note should name the population, period, source and any transformation. Readers do not get invented precision.

Lines use bounded monotone smoothing by default. Choose style.curve: linear for straight segments or previous for steps. Sparse scatter highlights can prioritize named observations without labelling every point. Use the type pages and generated reference for exact options.

Give readers a useful control

The Gapminder report has real country observations and a year playback control. Controls belong to the chart: filters select rows, metric choices select a measure, variants select an authored representation, and playback steps through a field. These do not turn a report into an arbitrary dashboard query engine.

This small filter example works without a data service:

Inspect, expand and download

Hover or keyboard focus exposes readouts. Series controls preserve focus as the chart redraws. The Table view and CSV expose observations; the image download captures the current view. Expand widens the figure on desktop and opens a modal on a phone. Some phone charts use a landscape presentation to show more of the x axis; the chart’s state survives closing it. Facets export together.

Dense charts may reduce drawing geometry using M4 for lines/areas or screen-space representatives for scatter. Readouts, Table and CSV retain the observations at the author’s precision. The chart discloses its retained density. Explicit style.points: all accepts the cost of drawing every point. Native check estimates text bounds; the browser measures actual glyphs. Read diagnostics and inspect the result at its intended width.