Overview

A chart type is a recipe: a geom, a coordinate system, a position mode and the scales you declare. A column chart and a pie chart use the same geom.bar(); only the coordinate system differs.

The building blocks

Every spec combines 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, how a path handles nulls. Paint lives in the stylesheet: see Styling.

Geoms

Six geoms are built in, and every recipe below uses one or more of them. Six more ship as geom packages (@graphysdk/geom-<name>) registered through createGraphyKit; their pages are listed at the end. Your own plugin can add 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 layer maps color or group, several observations share one x value. The layer’s position decides how they are arranged:

Position	Effect
`'identity'`	Draw at the raw value; observations may overlap
`'stack'`	Stack observations on top of each other
`'fill'`	Stack, then normalize 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 has its own default, so a multi-group layer looks right before you set 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

theta names the aesthetic that sweeps the angle and defaults to 'x'. startAngle is in degrees and defaults to 0. innerRadius is a fraction of the outer radius, from 0 to 1, and defaults to 0.

Common recipes

Each is a pipe(createSpec(...), ...) chain. The scales are left out here, but every mapped position aesthetic needs one.

Chart	Recipe
Line	`geom.line()`
Smooth line	`geom.line({ params: { curve: 'smooth' } })`
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({ domainMin: 0 })`
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()`
Heatmap	`geom.tile()` + a band 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. They share 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 draw in the order you pipe them, so later geoms sit on top. Give a layer an id and a stylesheet entry can target it with { layer: 'trend' }, which is how one layer is styled apart from the rest. Every recipe also animates in when it mounts, tuned through the renderer’s animation prop.

Guides for each type

Each page in this section covers one 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 band × band grid
Dumbbell — two or more values per band, joined by a connector
Lollipop — a head at the value on a stem from zero
Candlestick — open, high, low and close per session
Boxplot — the spread of values per band
Waterfall — a running total, step by step
Funnel — how many reach each stage
Combo — two metrics on dual axes

Most other charts are a small change to a recipe above: swap the geom, add coord.flip(), or change the position.

Get Started

Core concepts

Chart types

Themes

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