d3-color

Even though your browser understands a lot about colors, it doesn’t offer much help in manipulating colors through JavaScript. The d3-color module therefore provides representations for various color spaces, allowing specification, interpolation, conversion and manipulation.

For example, take the color named “steelblue”:

color("steelblue"); // {r: 70, g: 130, b: 180}

Let’s try converting it to HSL:

hsl("steelblue"); // {h: 207.27272727272728, s: 0.44, l: 0.4901960784313726}

Now rotate the hue by 90°, bump up the saturation, and format as hex:

c.h += 90;
c.s += .2;
c + ""; // #c62dcd

Or to find the perceptual halfway point between steelblue and brown:

interpolateLab("steelblue", "brown")(.5); // #8e5c6d

In addition to the ubiquitous and machine-friendly RGB and HSL color space, d3-color supports two color spaces that are designed for humans:

• Dave Green’s Cubehelix
• Lab (CIELAB) and HCL (CIELCH)

Cubehelix features monotonic lightness, while Lab and HCL are perceptually uniform. Note that HCL is the cylindrical form of Lab, similar to how HSL is the cylindrical form of RGB.

Installing

If you use NPM, npm install d3-color. Otherwise, download the latest release.

API Reference

# color(specifier)

Parses the specified CSS Color Module Level 3 specifier string, returning an RGB or HSL color. If the specifier was not valid, null is returned. Some examples:

• "rgb(255,255,255)"
• "hsl(120,50%,20%)"
• "#ffeeaa"
• "#fea"
• "steelblue"

The list of supported named colors is specified by CSS.

Note: this function may also be used with instanceof to test if an object is a color instance. The same is true of color subclasses, allowing you to test whether a color is in a particular color space.

# color.rgb()

Returns the RGB equivalent of this color. For RGB colors, that’s this.

# color.brighter([k])

Returns a brighter copy of this color. If k is specified, it controls how much brighter the returned color should be. If k is not specified, it defaults to 1. The behavior of this method is dependent on the implementing color space.

# color.darker([k])

Returns a darker copy of this color. If k is specified, it controls how much brighter the returned color should be. If k is not specified, it defaults to 1. The behavior of this method is dependent on the implementing color space.

# color.displayable()

Returns true if and only if the color is displayable on standard hardware. For example, this returns false for an RGB color if any channel value is less than zero or greater than 255.

# color.toString()

Returns the RGB hexadecimal string representing this color, such as "#f7eaba". If this color is not displayable, a suitable displayable color is returned instead. For example, RGB channel values greater than 255 are clamped to 255.

# rgb(r, g, b)
# rgb(specifier)
# rgb(color)

Constructs a new RGB color. The channel values are exposed as r, g and b properties on the returned instance. Use the RGB color picker to explore this color space.

If r, g and b are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to the RGB color space. See color for examples. If a color instance is specified, it is converted to the RGB color space using color.rgb. Note that unlike color.rgb this method always returns a new instance, even if color is already an RGB color.

# hsl(h, s, l)
# hsl(specifier)
# hsl(color)

Constructs a new HSL color. The channel values are exposed as h, s and l properties on the returned instance. Use the HSL color picker to explore this color space.

If h, s and l are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to the HSL color space. See color for examples. If a color instance is specified, it is converted to the RGB color space using color.rgb and then converted to HSL. (Colors already in the HSL color space skip the conversion to RGB.)

# lab(l, a, b)
# lab(specifier)
# lab(color)

Constructs a new Lab color. The channel values are exposed as l, a and b properties on the returned instance. Use the Lab color picker to explore this color space.

If l, a and b are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to the Lab color space. See color for examples. If a color instance is specified, it is converted to the RGB color space using color.rgb and then converted to Lab. (Colors already in the Lab color space skip the conversion to RGB, and colors in the HCL color space are converted directly to Lab.)

# hcl(h, c, l)
# hcl(specifier)
# hcl(color)

Constructs a new HCL color. The channel values are exposed as h, c and l properties on the returned instance. Use the HCL color picker to explore this color space.

If h, c and l are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to the HCL color space. See color for examples. If a color instance is specified, it is converted to the RGB color space using color.rgb and then converted to HCL. (Colors already in the HCL color space skip the conversion to RGB, and colors in the Lab color space are converted directly to HCL.)

# cubehelix(h, s, l)
# cubehelix(specifier)
# cubehelix(color)

Constructs a new Cubehelix color. The channel values are exposed as h, s and l properties on the returned instance. Use the Cubehelix color picker to explore this color space.

If h, s and l are specified, these represent the channel values of the returned color. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to the Cubehelix color space. See color for examples. If a color instance is specified, it is converted to the RGB color space using color.rgb and then converted to Cubehelix. (Colors already in the Cubehelix color space skip the conversion to RGB.)

# interpolateRgb(a, b)

Returns an RGB color space interpolator between the two colors a and b. The colors a and b need not be in RGB; they will be converted to RGB using rgb. The return value of the interpolator is a hexadecimal RGB string.

# interpolateHsl(a, b)

Returns an HSL color space interpolator between the two colors a and b. The colors a and b need not be in HSL; they will be converted to HSL using hsl. If either color’s hue or saturation is NaN, the opposing color’s channel value is used. The shortest path between hues is used. The return value of the interpolator is a hexadecimal RGB string.

# interpolateHslLong(a, b)

Like interpolateHsl, but does not use the shortest path between hues.

# interpolateLab(a, b)

Returns a Lab color space interpolator between the two colors a and b. The colors a and b need not be in Lab; they will be converted to Lab using lab. The return value of the interpolator is a hexadecimal RGB string.

# interpolateHcl(a, b)

Returns an HCL color space interpolator between the two colors a and b. The colors a and b need not be in HCL; they will be converted to HCL using hcl. If either color’s hue or chroma is NaN, the opposing color’s channel value is used. The shortest path between hues is used. The return value of the interpolator is a hexadecimal RGB string.

# interpolateHclLong(a, b)

Like interpolateHcl, but does not use the shortest path between hues.

# interpolateCubehelix(a, b)

Returns a Cubehelix color space interpolator between the two colors a and b using the default gamma of 1.0. The colors a and b need not be in Cubehelix; they will be converted to Cubehelix using cubehelix. If either color’s hue or saturation is NaN, the opposing color’s channel value is used. The shortest path between hues is used. The return value of the interpolator is a hexadecimal RGB string.

# interpolateCubehelixLong(a, b)

Like interpolateCubehelix, but does not use the shortest path between hues.

# interpolateCubehelixGamma(gamma)

Returns a Cubehelix color space interpolator factory using the specified gamma. A gamma value less than one emphasizes low intensity values, while a gamma value greater than one emphasizes high intensity values. For example:

var i = interpolateCubehelixGamma(1.5)("red", "blue");

# interpolateCubehelixGammaLong(gamma)

Like interpolateCubehelixGamma, but does not use the shortest path between hues.

Changes from D3 3.x:

• A new cubehelix color space!

• New “long” methods for hue interpolation in HSL, HCL and Cubehelix.

• A new color method parses the specified string according to the CSS specification and returns the corresponding color in its color space. For HSL color values, this is the HSL color space; for other values, the RGB color space is used. This method correctly parses RGB colors with percentages (e.g., rgb(30%,40%,50%)). Decimal values where integers are required are no longer allowed (e.g., rgb(100.5,0,0) is not a valid color).

• The color.brighter method no longer special-cases behavior for black and very dark channels in RGB; it is now a simple channel multiplier, consistent with color.darker and other color spaces.

• The rgb.hsl method has been removed; use the hsl constructor to convert to HSL instead.

• All color spaces, including RGB, now support the color.rgb method. This method returns a color instance representing the nearest-equivalent color in the RGB color space. Use the rgb constructor if you want a copy.

• When converting from Lab to HCL, hue and chroma are no longer undefined if the luminance is zero. Thus, the roundtrip from Lab to HCL and back again no longer loses information.