Band scales

Band scales are like ordinal scales except the output range is continuous and numeric. The scale divides the continuous range into uniform bands. Band scales are typically used for bar charts with an ordinal or categorical dimension.

scaleBand(domain, range)

Examples · Source · Constructs a new band scale with the specified domain and range, no padding, no rounding and center alignment.

const x = d3.scaleBand(["a", "b", "c"], [0, 960]);

If a single argument is specified, it is interpreted as the range. If domain is not specified, it defaults to the empty domain. If range is not specified, it defaults to the unit range [0, 1].

band(value)

Examples · Source · Given a value in the input domain, returns the start of the corresponding band derived from the output range.

const x = d3.scaleBand(["a", "b", "c"], [0, 960]);
x("a"); // 0
x("b"); // 320
x("c"); // 640
x("d"); // undefined

If the given value is not in the scale’s domain, returns undefined.

band.domain(domain)

Domain:

Examples · Source · If domain is specified, sets the domain to the specified array of values and returns this scale.

const x = d3.scaleBand([0, 960]).domain(["a", "b", "c", "d", "e", "f"]);

The first element in domain will be mapped to the first band, the second domain value to the second band, and so on. Domain values are stored internally in an InternMap from primitive value to index; the resulting index is then used to determine the band. Thus, a band scale’s values must be coercible to a primitive value, and the primitive domain value uniquely identifies the corresponding band. If domain is not specified, this method returns the current domain.

band.range(range)

Examples · Source · If range is specified, sets the scale’s range to the specified two-element array of numbers and returns this scale.

const x = d3.scaleBand().range([0, 960]);

If the elements in the given array are not numbers, they will be coerced to numbers. If range is not specified, returns the scale’s current range, which defaults to [0, 1].

band.rangeRound(range)

Examples · Source · Sets the scale’s range to the specified two-element array of numbers while also enabling rounding; returns this scale.

const x = d3.scaleBand().rangeRound([0, 960]);

This is a convenience method equivalent to:

band.range(range).round(true)

Rounding is sometimes useful for avoiding antialiasing artifacts, though also consider the shape-rendering “crispEdges” styles.

band.round(round)

Round:

Examples · Source · If round is specified, enables or disables rounding accordingly and returns this scale.

const x = d3.scaleBand(["a", "b", "c"], [0, 960]).round(false);

If round is not specified, returns whether rounding is enabled.

x.round() // false

If rounding is enabled, the start and stop of each band will be integers. Rounding is sometimes useful for avoiding antialiasing artifacts, though also consider the shape-rendering “crispEdges” styles. Note that if the width of the domain is not a multiple of the cardinality of the range, there may be leftover unused space, even without padding! Use band.align to specify how the leftover space is distributed.

band.paddingInner(padding)

Inner padding:0.10

Examples · Source · If padding is specified, sets the inner padding to the specified number which must be less than or equal to 1 and returns this scale.

const x = d3.scaleBand(["a", "b", "c"], [0, 960]).paddingInner(0.1);

If padding is not specified, returns the current inner padding which defaults to 0.

x.paddingInner() // 0.1

The inner padding specifies the proportion of the range that is reserved for blank space between bands; a value of 0 means no blank space between bands, and a value of 1 means a bandwidth of zero.

band.paddingOuter(padding)

Outer padding:0.10

Examples · Source · If padding is specified, sets the outer padding to the specified number which is typically in the range [0, 1] and returns this scale.

const x = d3.scaleBand(["a", "b", "c"], [0, 960]).paddingOuter(0.1);

If padding is not specified, returns the current outer padding which defaults to 0.

x.paddingOuter() // 0.1

The outer padding specifies the amount of blank space, in terms of multiples of the step, to reserve before the first band and after the last band.

band.padding(padding)

Padding:0.10

Examples · Source · A convenience method for setting the inner and outer padding to the same padding value.

const x = d3.scaleBand(["a", "b", "c"], [0, 960]).padding(0.1);

If padding is not specified, returns the inner padding.

x.padding() // 0.1

band.align(align)

Align:0.50

Examples · Source · If align is specified, sets the alignment to the specified value which must be in the range [0, 1], and returns this scale.

const x = d3.scaleBand(["a", "b", "c"], [0, 960]).align(0.5);

If align is not specified, returns the current alignment which defaults to 0.5.

x.align() // 0.5

The alignment specifies how outer padding is distributed in the range. A value of 0.5 indicates that the outer padding should be equally distributed before the first band and after the last band; i.e., the bands should be centered within the range. A value of 0 or 1 may be used to shift the bands to one side, say to position them adjacent to an axis. For more, see this explainer.

band.bandwidth()

Examples · Source · Returns the width of each band.

x.bandwidth() // 50.8235294117647

band.step()

Examples · Source · Returns the distance between the starts of adjacent bands.

x.step() // 63.529411764705884

band.copy()

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

const x1 = d3.scaleBand(["a", "b", "c"], [0, 960]);
const x2 = x1.copy();

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