Skip to main content
A mapping binds your data columns to aesthetics — the visual properties a chart draws with, like horizontal position, vertical position, and color. It’s the bridge between a row of data and what’s drawn on screen.
This reads: put month on the x-axis, revenue on the y-axis, and give each product its own color. The strings are column keys.

​
Built-in aesthetics

These are the built-in aesthetics you can map: Not every geom reads every aesthetic — a size mapping means something to geom.point() but nothing to geom.line(). Each geom documents the aesthetics it uses.

​
group vs color

Both color and group split data into series. The difference: color also assigns a visual (a hue per category, with a legend); group only separates the observations. Use group when you want, say, one line per category but a single color for all of them.

​
Variables and constants

An aesthetic can be bound to a variable (a column, read per row) or a constant (one literal value applied to every observation):
  • 'revenue' — string shorthand for a variable mapping.
  • { variable: 'revenue' } — the explicit variable form.
  • { value: 'red' } — a constant. The value still flows through the aesthetic’s scale, so { value: 'Pro' } on color resolves to whatever color the scale assigns the Pro category.

​
Where a mapping lives

A mapping can sit at two levels: Spec-level — shared by every layer. Set it with createSpec({ ... }):
Layer-level — merged over the spec-level mapping for one geom only, via a geom’s aes option. This is how combos give each layer a different y:
Layer mappings win where they overlap; anything they don’t set falls through to the spec-level mapping.

​
Every mapped position needs a scale

Mapping a column to x or y is only half the story — you must also declare the scale that turns those values into positions. scale.x() and scale.y() are never created automatically.
A mapped position aesthetic with no matching scale.*() produces NaN positions. If a chart renders blank, a missing scale is the first thing to check.

​
Next

  • Scales — turn mapped values into positions and colors
  • Geoms & layers — which aesthetics each geom reads