ColorScale

Creates an SVG color scale based on an array of data.

Linear scale

The default scale: "linear" maps values to a continuous single-hue gradient (blue). A smooth ramp is best when every value matters equally and you want to read magnitude by eye.

const skewed = [
  {value: 200},
  {value: 1000},
  {value: 2000},
  {value: 2010},
  {value: 2020},
  {value: 2030},
  {value: 2040},
  {value: 2100},
  {value: 6400},
];

const config = {
  data: skewed,
  height: 100,
  width: 500,
};

Jenks scale

scale: "jenks" splits the data into natural-breaks (ckmeans) buckets — discrete steps placed where the data clusters, minimizing within-bucket variance. This is the default for charts (Geomap choropleths) because it reveals grouping in skewed data that a linear ramp flattens.

const skewed = [
  {value: 200},
  {value: 1000},
  {value: 2000},
  {value: 2010},
  {value: 2020},
  {value: 2030},
  {value: 2040},
  {value: 2100},
  {value: 6400},
];

const config = {
  data: skewed,
  scale: "jenks",
  height: 100,
  width: 500,
};

Buckets scale

scale: "buckets" divides the domain into equal-width steps — the breakpoints are evenly spaced by value (unlike jenks, which follows the data). Set the count with buckets.

const skewed = [
  {value: 200},
  {value: 1000},
  {value: 2000},
  {value: 2010},
  {value: 2020},
  {value: 2030},
  {value: 2040},
  {value: 2100},
  {value: 6400},
];

const config = {
  data: skewed,
  scale: "buckets",
  buckets: 5,
  height: 100,
  width: 500,
};

Quantile scale

scale: "quantile" puts an equal count of data points in each bucket, so every color represents the same share of the data. Breakpoints bunch up where values are dense.

const skewed = [
  {value: 200},
  {value: 1000},
  {value: 2000},
  {value: 2010},
  {value: 2020},
  {value: 2030},
  {value: 2040},
  {value: 2100},
  {value: 6400},
];

const config = {
  data: skewed,
  scale: "quantile",
  buckets: 5,
  height: 100,
  width: 500,
};

Log scale

scale: "log" spaces the gradient logarithmically, so each order of magnitude gets comparable color range. Use it when values span several powers of ten (all values must share a sign).

const config = {
  // Values spanning orders of magnitude — the case log scaling is for.
  data: [
    {value: 100},
    {value: 1000},
    {value: 10000},
    {value: 100000},
    {value: 1000000},
  ],
  scale: "log",
  height: 100,
  width: 500,
};

Diverging scale

When the data spans both sides of the midpoint (default 0), the scale becomes diverging automatically: red (low) → neutral gray → blue (high), so the two directions read as opposites around the center. Move the center with midpoint.

const config = {
  data: [
    {value: -6400},
    {value: -2000},
    {value: -500},
    {value: 0},
    {value: 500},
    {value: 2000},
    {value: 6400},
  ],
  height: 100,
  width: 500,
};

Scale function

scale also accepts a function that picks the scale on every render. It receives the numeric values the scale is built from (sorted, without null or NaN) and their [min, max] extent, and returns a scale name. Here a range wider than 5 gets jenks buckets and a narrower one gets a linear gradient, so new data (from a timeline or a filter) can switch between them.

const skewed = [
  {value: 200},
  {value: 1000},
  {value: 2000},
  {value: 2010},
  {value: 2020},
  {value: 2030},
  {value: 2040},
  {value: 2100},
  {value: 6400},
];

const pickScale = (values, [min, max]) => (max - min > 5 ? "jenks" : "linear");

const config = {
  data: skewed,
  scale: pickScale,
  height: 100,
  width: 500,
};

Hover mark

hover marks a value on the scale, as a chart does while one of its shapes is hovered: an extra axis tick marks the value on the bar, and a badge reads it where that tick’s label would sit. A bucketed bar (bucketAxis) also outlines the value’s bucket; a scale drawn as swatches draws no mark. hoverMark(false) turns it off; hoverMarkConfig styles the tickConfig, badgeConfig, and outlineConfig.

hover

Marks a value on the scale: an extra axis tick where the value falls on the color bar and a badge reading it where that tick's label would sit, plus an outline around its bucket on a bucketed bar (bucketAxis). A scale drawn as discrete swatches draws no mark. A chart sets this while one of its shapes is hovered. Pass false to clear it. Turned off with hoverMark(false).

Configuration

import {ColorScale} from "@d3plus/core";

Extends BaseClass.

Filter 18 config keys

axisConfigrecord: The ColorScale is constructed by combining an Axis for the ticks/labels and a Rect for the actual color box (or multiple boxes, as in a jenks scale). Because of this, there are separate configs for the Axis class used to display the text (axisConfig) and the Rect class used to draw the color breaks (rectConfig). This method acts as a pass-through to the config method of the Axis.
classNamestring | array.<string> | undefined: CSS classes added to the outermost element this chart or component draws into, next to its fixed d3plus classes, so page CSS can target it: a chart's root <svg class="d3plus-viz"> (its <canvas> with the Canvas renderer) and a standalone component's <svg>. Takes a space-separated string or an array. A new value replaces the classes the previous one added; unset adds none. Tooltips take their own tooltipConfig.className.
colorDefaultscolordefaultsconfig: Overrides the default colors used when assigning fills from data and choosing legible text colors: dark and light (the text colors picked for contrast against a background), missing (null/undefined values), on/off (true/false values), sequential (the anchor hue for magnitude ramps), and scale (the categorical palette, given as a d3 ordinal scale or an array of colors). Keys are merged into the current defaults, and a Viz passes its overrides down to the shapes and components it draws.
configd3plusconfig: Methods that correspond to the key/value pairs and returns this class.
dataarray.<datapoint>Default [ ]: The data array used to create shapes. A shape key will be drawn for each object in the array.
hovernumber | false: Marks a value on the scale: an extra axis tick where the value falls on the color bar and a badge reading it where that tick's label would sit, plus an outline around its bucket on a bucketed bar (bucketAxis). A scale drawn as discrete swatches draws no mark. A chart sets this while one of its shapes is hovered. Pass false to clear it. Turned off with hoverMark(false).
labelConfigrecord: A pass-through for the TextBox class used to style the labelMin and labelMax text.
labelMaxstring: Defines a text label to be displayed off of the end of the maximum point in the scale (currently only available in horizontal orientation).
labelMinstring: Defines a text label to be displayed off of the end of the minimum point in the scale (currently only available in horizontal orientation).
legendConfigrecord: Configuration passed to the Legend that draws the scale when its values are rendered as discrete swatches instead of a continuous bar (for example a categorical or buckets scale), acting as a pass-through to that Legend's config method.
localestring | object: The locale used for all text and number formatting. Supports the locales defined in d3plus-format. The locale can be a complex Object, a locale code (like "en-US"), or a 2-digit language code (like "en"). If a 2-digit code is provided, the "findLocale" function is used to identify the most approximate locale.
onstring: Event listener for the specified event typenames. Mirrors the core d3-selection behavior.
parentunknown: Parent config used by the wrapper.
rectConfigrecord: The ColorScale is constructed by combining an Axis for the ticks/labels and a Rect for the actual color box (or multiple boxes, as in a jenks scale). Because of this, there are separate configs for the Axis class used to display the text (axisConfig) and the Rect class used to draw the color breaks (rectConfig). This method acts as a pass-through to the config method of the Rect.
renderfunction: Renders the current ColorScale to the page.
selectstring | htmlelement: The SVG container element for this visualization. 3 selector or DOM element.
shapeConfigd3plusconfig: Configuration object with key/value pairs applied as method calls on each shape.
translatefunction: Defines how informational text strings should be displayed. By default, this function will try to find the string in question (which is the first argument provided to this function) inside of an internally managed translation Object. If you'd like to override to use custom text, simply pass this method your own custom formatting function.