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. 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`, `alpha`, `label`
`geom.area()`	A filled band under a line	`x`, `y`, `color`, `strokeWidth`, `lineType`, `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; cartesian only	`x`, `y`, `color` (required), `label`

Each is a function that returns a layer. Pass options to configure the layer, and geom-specific params for its geometry and behavior. Paint (colors, widths, opacities) lives in the stylesheet instead:

geom.line({ params: { curve: 'smooth', missingValues: 'connect' } });
geom.bar({ position: 'stack', params: { width: 0.8 } });

Params and paint, geom by geom

params set geometry and behavior; the style.* target beside them holds the geom’s paint.

Geom	Params	Paint target
`point`	none	`style.geom.point({ size, symbol, stroke, strokeWidth })`
`line`	`curve: 'linear' \| 'smooth'` (default `'linear'`), `missingValues: 'zero' \| 'gap' \| 'connect'` (default `'gap'`)	`style.geom.line({ strokeWidth, dashArray, fillAlpha })`
`area`	the same two, but `missingValues` defaults to `'zero'` — an area can’t hold a gap mid-stack	`style.geom.area({ alpha, strokeWidth, dashArray, strokeAlpha })`
`bar`	`width` (default `0.7`, or `1` in polar) — the fraction of the band the bar fills, in `(0, 1]`	`style.geom.bar({ cornerRadius, stroke, strokeWidth })`
`rule`	`label` (optional text), `labelPosition: 'start' \| 'end'` (default `'start'`)	`style.geom.rule({ stroke, strokeWidth, dashArray })`, and `style.geom.rule.label({ … })` for its text
`tile`	none — a cell’s geometry is the two bands it sits in	`style.geom.tile({ cornerRadius, stroke, strokeWidth })`

Every target also takes the shared alpha and saturation, plus its paint word: fill on a bar, area, point or tile, stroke on a line or rule. A dash pattern is a dashArray in the stylesheet ([] solid, [4, 2] dashed) and a lineType name ('solid', 'dashed', 'dotted') when mapped from data. Two things catch people out. A geom’s cornerRadius is a token ('none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full') or a number of pixels. And a defaults entry loses to a mapped aesthetic, while an overrides entry beats it. Styling has the full cascade.

A params key the geom does not declare is accepted and ignored.

Layers

Every geom.*() you pipe in adds a layer. Layers draw in order, so later ones sit on top. They share the spec-level mapping unless one overrides it. This is how 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. `style.*(…, { layer: id })`, highlights and annotation anchors point at it. Set one to style a single layer 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 answers hover. `true` for every geom except `geom.rule()`
`attachTo`	The layer this one describes: `'previous'`, `'none'` or a layer `id`. An attached layer joins that layer’s hover and its tooltip rows sit under that layer’s. `'none'` for every built-in geom; see Interactivity

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 normalize each stack to 100%
`'dodge'`	Place observations side by side within the band

Each geom has 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 comes out grouped and an area chart comes out stacked, with no position of your own. geom.tile() accepts only 'identity'; any other value fails to compile.

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

Dodge works the same way for every geom: each group gets a share of the band. A bar fills its share; a point or line vertex stands at its center. Dodged layers line up, so dodge the points over a grouped bar chart and each point lands on its own bar:

geom.bar(); // grouped: 'dodge' by default
geom.point({ position: 'dodge' }); // each group's point on its own bar

A dodged line moves with its points, so the two stay together. Dodge needs a band, so it only moves anything on a band axis. On a continuous x axis a dodged layer stays at its values.

Scales — map values to positions, colors and sizes
Styling — the stylesheet that paints every geom
Statistics — summarize 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

Themes

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