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 four 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

Geoms

There are five built-in geoms. Everything in the recipes below is one of these, sometimes layered:

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

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 (default for most geoms)
`'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

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, innerRadius })`	Bend the plane into a circle — turns bars into pie/donut wedges

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: 'stack' })` + `coord.polar({ theta: 'y' })`
Donut	`geom.bar({ position: 'stack' })` + `coord.polar({ theta: 'y', innerRadius: 0.5 })`
Radar	`geom.line()` + `coord.polar({ theta: 'x' })` + `scale.x.discrete()`
Rose / coxcomb	`geom.bar()` + `coord.polar({ theta: 'x' })` + `scale.x.discrete()`
Radial bar	`geom.bar({ position: 'stack' })` + `coord.polar({ theta: 'y', innerRadius: 0.15 })`
Scatter	`geom.point()` + `scale.x.continuous()` + `scale.y.continuous()`
Bubble	`geom.point()` + `size` mapped + `scale.size.continuous()`
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.

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
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