Coordinate systems

A coordinate system decides the plane a geom is drawn in. The same geom and scales produce very different charts depending on the coord: a stacked bar is a stacked column in cartesian coordinates, a set of horizontal bars when the axes are flipped, and a pie when the plane is bent into a circle. Set the coordinate system by piping a coord.*() part into the spec. When you don’t, the chart is cartesian.

Cartesian

The standard x–y plane, and the default.

pipe(
  createSpec({ x: 'month', y: 'revenue' }),
  geom.bar(),
  scale.x(),
  scale.y(),
  coord.cartesian() // optional — this is the default
);

Flip

coord.flip() swaps the x and y axes. Its main use is turning vertical columns into horizontal bars — you keep the natural mapping (category on x, value on y) and the flip lays it on its side.

pipe(
  createSpec({ x: 'country', y: 'population' }),
  geom.bar(),
  scale.x(),
  scale.y(),
  coord.flip() // horizontal bars
);

Polar

coord.polar() bends the plane into a circle — this is how pie, donut, rose and radial charts are made. It takes:

'x' | 'y'

default:"x"

Which aesthetic maps to the angle. theta: 'y' sweeps the value around the circle (pie/donut); theta: 'x' sweeps the category around it, with the value as radius (rose / coxcomb). A bare coord.polar() gives you the rose form — pass theta: 'y' for a pie.

number

default:"0"

Inner radius as a fraction 0–1. 0 is a full pie; a value like 0.5 cuts out the centre for a donut.

number

default:"0"

Starting angle in degrees.

A pie chart is a single stacked-fill bar wrapped around theta: 'y'. The 'fill' position normalises the stack to 100%, which is what closes the circle:

pipe(
  createSpec({ x: '', y: 'revenue', color: 'region' }),
  geom.bar({ position: 'fill' }),
  coord.polar({ theta: 'y' }),
  scale.x(),
  scale.y(),
  scale.color.palette()
);

The rest of the polar family follows from the same two knobs:

Chart	Recipe
Pie	`geom.bar({ position: 'fill' })` + `coord.polar({ theta: 'y' })`
Donut	the same, plus `innerRadius: 0.5`
Radar	`geom.line()` or `geom.area()` + `coord.polar({ theta: 'x' })`
Rose	`geom.bar()` + `coord.polar({ theta: 'x' })`

See Pie & donut and Radar & radial for worked examples. Polar coordinates also flatten the padding on every discrete scale to 0, so wedges meet edge to edge and a scale.x.discrete({ padding: 0.2 }) has no visible effect inside a pie.

One coord per spec

Only one coordinate system is in play at a time, and piping a second coord.*() replaces the first outright rather than merging into it:

// theta is gone — the second call is the whole coord.
pipe(spec, coord.polar({ theta: 'y' }), coord.polar({ innerRadius: 0.5 }));

// Pass both params in one call instead.
pipe(spec, coord.polar({ theta: 'y', innerRadius: 0.5 }));

Axis limits

Every coord accepts optional xLimits / yLimits as [min, max] to clip the drawing region; both are null unless you set them. For most charts you’ll control the visible range through scale domainMin / domainMax instead — limits operate on the coordinate space rather than the data domain.

Chart types — coords combined with geoms and positions
Pie & donut — the theta: 'y' polar recipes in full
Radar & radial — the theta: 'x' polar family

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Cartesian

Flip

Polar

One coord per spec

Axis limits

Next

​Cartesian

​Flip

​Polar

​One coord per spec

​Axis limits

​Next

Cartesian

Flip

Polar

One coord per spec

Axis limits

Next