Overview

A chart type is a recipe you compose — a geom, a coordinate system, a position mode, and the scales you declare. A vertical bar chart and a pie chart use the same geom.bar(); they differ only in coordinate system.

The building blocks

Every spec is assembled from five kinds of ingredient:

Ingredient	Builder	What it does
Mapping	`mapping({ ... })` / `createSpec({ ... })`	Binds data columns to aesthetics (`x`, `y`, `color`, `size`, …)
Geom	`geom.*()`	The shape drawn for each observation
Scale	`scale.*()`	Turns data values into positions, colors and sizes
Coord	`coord.*()`	The coordinate system the geom is drawn in
Styles	`styles({ ... })` with `style.*`	Paint: color, opacity, borders, corner radius, stroke width, marker size

A geom’s params are geometry — the bar’s band width, the line’s curve family, how a path handles nulls. Everything a mark is painted with lives in the stylesheet: see Styling.

Geoms

There are six built-in geoms. Everything in the recipes below is one of these, sometimes layered. A plugin can contribute more — see custom geoms:

Geom	Draws	Typical use
`geom.point()`	A point per observation	Scatter, bubble, dot plots
`geom.line()`	A path connecting observations	Line charts, trends
`geom.area()`	A filled band under a line	Area charts
`geom.bar()`	A rectangle (or arc, in polar) per observation	Columns, bars, pie, donut
`geom.rule()`	A single reference line across the panel	Goal lines, thresholds
`geom.tile()`	A cell filling its band on both axes	Heatmaps, matrices, waffles

Position modes

When a geom maps color (or group), multiple observations share an x value. The layer’s position decides how they arrange:

Position	Effect
`'identity'`	Draw at the raw value; observations may overlap
`'stack'`	Stack observations on top of each other
`'fill'`	Stack, then normalise each stack to 100%
`'dodge'`	Place observations side by side within the band

geom.bar({ position: 'stack' }); // stacked columns
geom.bar({ position: 'dodge' }); // grouped columns

Each geom brings its own default, so a multi-series layer arranges sensibly before you say anything:

Geom	Default position
`geom.bar()`	`'dodge'`
`geom.area()`	`'stack'`
`geom.point()`, `geom.line()`, `geom.rule()`, `geom.tile()`	`'identity'`

Coordinate systems

Coord	Effect
`coord.cartesian()`	Standard x–y plane (the default)
`coord.flip()`	Swap the axes — turns columns into horizontal bars
`coord.polar({ theta, startAngle, innerRadius })`	Bend the plane into a circle — turns bars into pie/donut wedges

startAngle is in degrees and defaults to 0; innerRadius is a 0–1 fraction of the outer radius and defaults to 0.

Common recipes

Reach for these as starting points. Each is a pipe(createSpec(...), ...) chain; the scales are elided for brevity but always required for mapped position aesthetics.

Chart	Recipe
Line	`geom.line()`
Smooth line	`geom.line({ params: { interpolate: 'catmull-rom' } })`
Area	`geom.area()`
Stacked area	`geom.area({ position: 'stack' })`, `color` mapped
Column (vertical)	`geom.bar()` + `scale.x.discrete()`
Bar (horizontal)	`geom.bar()` + `coord.flip()`
Stacked column	`geom.bar({ position: 'stack' })`, `color` mapped
100% stacked column	`geom.bar({ position: 'fill' })`, `color` mapped
Grouped column	`geom.bar({ position: 'dodge' })`, `color` mapped
Pie	`geom.bar({ position: 'fill' })` + `coord.polar({ theta: 'y' })`
Donut	`geom.bar({ position: 'fill' })` + `coord.polar({ theta: 'y', innerRadius: 0.5 })`
Radar	`geom.line()` + `coord.polar({ theta: 'x' })` + `scale.x.discrete()` + `scale.y({ zero: true })`
Rose / coxcomb	`geom.bar()` + `coord.polar({ theta: 'x' })` + `scale.x.discrete()` + `scale.y({ zero: true })`
Radial bar	`geom.bar({ position: 'stack' })` + `coord.polar({ theta: 'y', innerRadius: 0.15 })` + `scale.y({ zero: true })`
Scatter	`geom.point()` + `scale.x.continuous()` + `scale.y.continuous()`
Bubble	`geom.point()` + `size` mapped + `scale.size.continuous()`
Heatmap	`geom.tile()` + a category on `x` and `y` + `scale.color.continuous()`
Waffle	`geom.tile()` over a 10×10 grid + `scale.color.discrete()`
Combo	`geom.bar()` + `geom.line()` layered, the line on `ySecondary`

Layers

A geom is a layer. Add several to one spec and they draw over each other, sharing the spec-level mapping unless a layer overrides it. This is how combos and decorated lines are built:

const spec = pipe(
  createSpec({ x: 'month', y: 'revenue' }),
  geom.line(), // the trend
  geom.point(), // a dot on every vertex
  scale.x(),
  scale.y()
);

Layers are drawn in the order you pipe them — later geoms sit on top. Give a layer an id and a stylesheet entry can scope to it with { layer: 'trend' }, which is how one series in a stack of layers reads differently from the rest. Every recipe here also gets an entrance animation when it mounts, tuned through the renderer’s animation prop.

Guides for each type

The pages in this section walk through a specific chart type end to end — data shape, spec, and the options that matter most.

Line — trends over a continuous or ordered x-axis
Bar & column — vertical columns for comparing categories, horizontal bars for ranking
Area — filled trends, stacked or plain
Pie & donut — parts of a whole
Radar & radial — categories compared around a circle
Scatter & bubble — correlation and three-variable plots
Heatmap & waffle — a value per cell of a category × category grid
Combo — two metrics on dual axes

Don’t see the chart you need? Because charts are composed from these ingredients, most are a small tweak to a recipe above — swap the geom, add coord.flip(), or change the position.

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

The building blocks

Geoms

Position modes

Coordinate systems

Common recipes

Layers

Guides for each type

​The building blocks

​Geoms

​Position modes

​Coordinate systems

​Common recipes

​Layers

​Guides for each type

The building blocks

Geoms

Position modes

Coordinate systems

Common recipes

Layers

Guides for each type