Geoms & layers

A geom is what a chart draws for its data — a line, a bar, a point. Each geom is a layer in the spec; add several and they stack into one chart. Geoms are the visible half of the grammar: mappings and scales decide where things go, geoms decide what is drawn there.

The built-in geoms

Geom	Draws	Reads
`geom.point()`	A point per observation	`x`, `y`, `color`, `size`, `alpha`, `label`
`geom.line()`	A path connecting observations	`x`, `y`, `color`, `strokeWidth`, `lineType`, `label`
`geom.area()`	A filled band under a line	`x`, `y`, `color`, `alpha`, `label`
`geom.bar()`	A rectangle (or arc, in polar) per observation	`x`, `y`, `color`, `alpha`, `label`
`geom.rule()`	A single reference line across the panel	`x` or `y`
`geom.tile()`	A cell filling its band on both axes	`x`, `y`, `color` (required), `label`

Each is a factory that returns a layer. Call it with options to configure the layer, and geom-specific params for its geometry and behavior knobs — paint (colors, widths, opacities) lives in the stylesheet instead:

geom.line({ params: { interpolate: 'catmull-rom', missingValues: 'connect' } });
geom.bar({ position: 'stack', params: { width: 0.8 } });

Params and paint, geom by geom

params are geometry and behaviour; the style.* target beside them is where that geom’s paint is authored.

Geom	Params	Paint target
`point`	none	`style.geom.point({ size, borderColor, borderWidth })`
`line`	`interpolate: 'linear' \| 'catmull-rom'` (default `'linear'`), `missingValues: 'zero' \| 'gap' \| 'connect'` (default `'gap'`)	`style.geom.line({ strokeWidth, lineType, fillAlpha })`
`area`	the same two, but `missingValues` defaults to `'zero'` — an area can’t hold a gap mid-stack	`style.geom.area({ alpha, strokeWidth, lineType, strokeAlpha })`
`bar`	`width` (default `0.7`) — the fraction of the category’s band the bar fills, in `(0, 1]`	`style.geom.bar({ borderRadius, borderColor, borderWidth })`
`rule`	`label` (optional text), `labelPosition: 'start' \| 'end'` (default `'start'`)	`style.geom.rule({ color, strokeWidth, lineType })`, and `style.geom.rule.label({ … })` for its text
`tile`	none — a cell’s geometry is the two bands it sits in	no target of its own: the fill comes from the `color` scale, the shared `style.geom({ alpha, saturation })` still applies

Every target also takes the shared color, alpha and saturation. Two things catch people out: a bar’s borderRadius is a token ('none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full'), not a pixel count; and a defaults entry loses to a mapped aesthetic while an overrides entry beats it. Styling has the full cascade.

Params merge without validation, so a key a geom doesn’t declare is accepted and quietly ignored.

Layers

Every geom.*() you pipe in adds a layer, drawn in order — later layers sit on top. Layers share the spec-level mapping unless one overrides it. This is how decorated and combo charts are built:

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

Common layer options

Beyond params, every geom accepts these options:

Option	Purpose
`id`	A stable name for the layer. It’s the handle `style.*(…, { layer: id })`, highlights and annotation anchors point at — set one to style a single series of a multi-layer chart
`aes`	A layer-local mapping, merged over the spec’s
`position`	How overlapping observations arrange — see below
`stat`	A statistical transform for this layer — `stat.count()`, `stat.sum()`, `stat.mean()`, `stat.smooth()`; the default is `stat.identity()`
`yScaleType`	Bind the layer to the `'primary'` or `'secondary'` y-axis
`dataLabels`	Show value labels on each observation
`transforms`	Transforms applied to this layer’s view of the data
`interactive`	Whether the layer takes part in hover hit-testing. `true` everywhere except `geom.rule()`, which stays out of it by default

Position modes

When several observations share the same x (because color or group splits the data), a layer’s position decides how they arrange:

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

Each geom picks its own default: geom.bar() is 'dodge', geom.area() is 'stack', and geom.point(), geom.line(), geom.rule() and geom.tile() are 'identity'. So a bar chart with a color mapping arrives grouped and an area chart arrives stacked, with no position of your own.

geom.bar({ position: 'stack' }); // stacked columns instead of grouped
geom.bar({ position: 'fill' }); // 100% stacked columns
geom.area({ position: 'identity' }); // overlapping bands instead of stacked

Scales — map values to positions, colors and sizes
Styling — the stylesheet that paints every geom
Statistics — summarise a layer before drawing it
Chart types — geoms assembled into recipes
Heatmap & waffle — the tile geom end to end

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

The built-in geoms

Params and paint, geom by geom

Layers

Common layer options

Position modes

Next

​The built-in geoms

​Params and paint, geom by geom

​Layers

​Common layer options

​Position modes

​Next

The built-in geoms

Params and paint, geom by geom

Layers

Common layer options

Position modes

Next