Ordinal scales

Unlike continuous scales, ordinal scales have a discrete domain and range. For example, an ordinal scale might map a set of named categories to a set of colors, or determine the horizontal positions of columns in a column chart.

scaleOrdinal(domain, range)

Examples · Source · Constructs a new ordinal scale with the specified domain and range.

const color = d3.scaleOrdinal(["a", "b", "c"], ["red", "green", "blue"]);

If domain is not specified, it defaults to the empty array. If range is not specified, it defaults to the empty array; an ordinal scale always returns undefined until a non-empty range is defined.

ordinal(value)

Examples · Source · Given a value in the input domain, returns the corresponding value in the output range.

color("a") // "red"

If the given value is not in the scale’s domain, returns the unknown value; or, if the unknown value is implicit (the default), then the value is implicitly added to the domain and the next-available value in the range is assigned to value, such that this and subsequent invocations of the scale given the same input value return the same output value.

ordinal.domain(domain)

Examples · Source · If domain is specified, sets the domain to the specified array of values.

const color = d3.scaleOrdinal(["red", "green", "blue"]).domain(["a", "b", "c"]);
color("a"); // "red"
color("b"); // "green"
color("c"); // "blue"

The first element in domain will be mapped to the first element in the range, the second domain value to the second range value, and so on. Domain values are stored internally in an InternMap from primitive value to index; the resulting index is then used to retrieve a value from the range. Thus, an ordinal scale’s values must be coercible to a primitive value, and the primitive domain value uniquely identifies the corresponding range value.

color.domain() // ["a", "b", "c"]

If domain is not specified, this method returns the current domain.

Setting the domain on an ordinal scale is optional if the unknown value is implicit (the default). In this case, the domain will be inferred implicitly from usage by assigning each unique value passed to the scale a new value from the range.

const color = d3.scaleOrdinal(["red", "green", "blue"]);
color("b"); // "red"
color("a"); // "green"
color("c"); // "blue"
color.domain(); // inferred ["b", "a", "c"]

CAUTION

An explicit domain is recommended for deterministic behavior; inferring the domain from usage is dependent on ordering.

ordinal.range(range)

Examples · Source · If range is specified, sets the range of the ordinal scale to the specified array of values.

const color = d3.scaleOrdinal().range(["red", "green", "blue"]);

The first element in the domain will be mapped to the first element in range, the second domain value to the second range value, and so on. If there are fewer elements in the range than in the domain, the scale will reuse values from the start of the range. If range is not specified, this method returns the current range.

ordinal.unknown(value)

Examples · Source · If value is specified, sets the output value of the scale for unknown input values and returns this scale.

const color = d3.scaleOrdinal(["a", "b", "c"], d3.schemeTableau10).unknown(null);
color("a"); // "#4e79a7"
color("b"); // "#f28e2c"
color("c"); // "#e15759"
color("d"); // null

If value is not specified, returns the current unknown value, which defaults to implicit. The implicit value enables implicit domain construction; see ordinal.domain.

ordinal.copy()

Examples · Source · Returns an exact copy of this ordinal scale.

const c1 = d3.scaleOrdinal(["a", "b", "c"], d3.schemeTableau10);
const c2 = c1.copy();

Changes to this scale will not affect the returned scale, and vice versa.

scaleImplicit

Examples · Source · A special value for ordinal.unknown that enables implicit domain construction: unknown values are implicitly added to the domain.

const color = d3.scaleOrdinal(["a", "b", "c"], d3.schemeTableau10);
color.unknown(); // d3.scaleImplicit

CAUTION

An explicit domain is recommended for deterministic behavior; inferring the domain from usage is dependent on ordering.