Scales

A scale turns data values into visual values — a number into a pixel position, a category into a color, a magnitude into a point size. Every aesthetic you map needs a scale to interpret it.

scale.x(); // infer an x-axis scale from the data
scale.y.continuous({ domainMin: 0 }); // an explicit continuous y-axis, pinned to zero
scale.color.discrete({ range: ['#4C6EF5', '#F76707'] });

Position scales must be declared

Position scales are never created automatically. If you map x or y, you must add scale.x() / scale.y(). Miss one and that axis has no scale, producing NaN positions and a blank chart.

pipe(
  createSpec({ x: 'month', y: 'revenue' }),
  geom.line(),
  scale.x(), // required
  scale.y() // required
);

Visual scales (color, size, …) are more forgiving — a mapped color without an explicit scale falls back to the default palette — but declaring them keeps a chart predictable.

Inference vs explicit types

Position scales are callable to infer their type from the mapped column’s value format:

text → discrete (band) scale
number / percentage / currency → continuous scale
date → temporal scale

scale.x(); // inferred
scale.x({ nice: true }); // inferred, with options

Or name the type explicitly when you want to force a treatment:

scale.x.continuous();
scale.x.discrete();
scale.x.datetime();
scale.x.log();
scale.x.sqrt();

Scales by aesthetic

Aesthetic	Methods
`x`, `y`, `ySecondary`	callable (inferred), `.continuous()`, `.discrete()`, `.datetime()`, `.log()`, `.sqrt()`
`color`	`.continuous()`, `.discrete()`, `.palette()`
`size`, `alpha`, `strokeWidth`	`.continuous()`, `.discrete()`, `.identity()`
`lineType`	`.discrete()`, `.identity()`

Color scales

scale.color.palette(); // Graphy's default palette
scale.color.discrete({ domain: ['A', 'B'], range: ['#4C6EF5', '#F76707'] }); // fixed colors
scale.color.continuous(); // a numeric gradient

Identity scales

An identity scale passes data values straight through as visual values — { size: 10 } becomes 10px, no transformation. Useful when your data already holds pixel sizes or CSS colors.

scale.size.identity();

Continuous scale options

The continuous methods (and .log() / .sqrt(), which are continuous with a transform) accept:

domainMin

number | null

Force the lower bound of the domain. domainMin: 0 makes an axis start at zero.

domainMax

number | null

Force the upper bound of the domain.

nice

boolean

Extend the domain to round values — [3, 97] becomes [0, 100].

zero

boolean

Include zero in the domain.

reverse

boolean

Reverse the direction of the scale.

transform

'linear' | 'log' | 'sqrt'

A mathematical transform applied to the scale. scale.y.log() is shorthand for transform: 'log'.

Discrete scale options

domain

string[]

The categories, in the order they should appear. Omit to derive them from the data.

range

Array<string | number>

Explicit output values — colors, sizes, or dash patterns — aligned to domain.

Coordinate systems — the plane scales place values into
Chart types — scales at work in each recipe

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Position scales must be declared

Inference vs explicit types

Scales by aesthetic

Color scales

Identity scales

Continuous scale options

Discrete scale options

Next

​Position scales must be declared

​Inference vs explicit types

​Scales by aesthetic

​Color scales

​Identity scales

​Continuous scale options

​Discrete scale options

​Next

Position scales must be declared

Inference vs explicit types

Scales by aesthetic

Color scales

Identity scales

Continuous scale options

Discrete scale options

Next