API Reference ▸ Core ▸ Colors
The D3 4.0 API Reference has moved. This page describes the D3 3.x API.
Constructing visualizations often involves working with colors. Even though your browser understands a lot about colors, it doesn't offer much help in manipulating colors through JavaScript. So D3 provides representations for various color spaces, including RGB, HSL, LAB and HCL, allowing specification, interpolation, conversion and manipulation (such as making colors brighter or darker).
Note: while you can work with colors directly, you might also want to take a look at D3's built-in color interpolation, such as interpolateRgb, interpolateHsl and scales. If you are looking for color palettes, see the ordinal scales reference.
# d3.rgb(r, g, b)
Constructs a new RGB color with the specified r, g and b channel values. Each channel must be specified as an integer in the range [0,255]. The channels are available as the r, g and b attributes of the returned object.
# d3.rgb(color)
Constructs a new RGB color by parsing the specified color string. If color is not a string, it is coerced to a string; thus, this constructor can also be used to create a copy of an existing color, or force the conversion of a d3.hsl color to RGB. The color string may be in a variety of formats:
- rgb decimal - "rgb(255,255,255)"
- hsl decimal - "hsl(120,50%,20%)"
- rgb hexadecimal - "#ffeeaa"
- rgb shorthand hexadecimal - "#fea"
- named - "red", "white", "blue"
The resulting color is stored as red, green and blue integer channel values in the range [0,255]. The channels are available as the r, g and b attributes of the returned object. The list of supported named colors is specified by CSS. If the color is specified in HSL space, it is converted to RGB in a manner equivalent to hsl.rgb.
# rgb.brighter([k])
Returns a brighter copy of this color. Each channel is multiplied by 0.7 ^ -k. If the gamma value k is omitted, it defaults to 1. Channel values are capped at the maximum value of 255, and the minimum value of 30.
# rgb.darker([k])
Returns a darker copy of this color. Each channel is multiplied by 0.7 ^ k. If the gamma value k is omitted, it defaults to 1.
# rgb.hsl()
Returns the equivalent color in HSL space; see d3.hsl for details on the returned object. The conversion from HSL to RGB is described in CSS3 Color Module Level 3; this is the equivalent reverse operation.
# rgb.toString()
Converts this RGB color to a hexadecimal string, such as "#f7eaba".
# d3.hsl(h, s, l)
Constructs a new HSL color with the specified hue h, saturation s and lightness l. The hue must be a number in the range [0,360]. The saturation and lightness must be in the range [0,1] (not percentages). These values are available as the h, s and l attributes of the returned object.
# d3.hsl(color)
Constructs a new HSL color by parsing the specified color string. If color is not a string, it is coerced to a string; thus, this constructor can also be used to create a copy of an existing color, or force the conversion of a d3.rgb color to HSL. The color string may be in a variety of formats:
- rgb decimal - "rgb(255,255,255)"
- hsl decimal - "hsl(120,50%,20%)"
- rgb hexadecimal - "#ffeeaa"
- rgb shorthand hexadecimal - "#fea"
- named - "red", "white", "blue"
The resulting color is stored as hue in the range [0,360], and saturation and lightness values in the range [0,1]. These values are available as the h, s and l attributes of the returned object. The list of supported named colors is specified by CSS. If the color is specified in RGB space, it is converted to HSL in a manner equivalent to rgb.hsl.
# hsl.brighter([k])
Returns a brighter copy of this color. The lightness channel is multiplied by 0.7 ^ -k. If the gamma value k is omitted, it defaults to 1.
# hsl.darker([k])
Returns a darker copy of this color. The lightness channel is multiplied by 0.7 ^ k. If the gamma value k is omitted, it defaults to 1.
# hsl.rgb()
Returns the equivalent color in RGB space; see d3.rgb for details on the returned object. The conversion from HSL to RGB is described in CSS3 Color Module Level 3.
# hsl.toString()
Converts this HSL color to an RGB hexadecimal string, such as "#f7eaba".
# d3.hcl(h, c, l)
Constructs a new HCL color with the specified hue h, chroma c, and luminance l. The hue must be a number in the range [0,360]. The chroma and luminance must be in the range [0,1] (not percentages). These values are available as the h, c, and l attributes of the returned object.
# d3.hcl(color)
Constructs a new HCL color by parsing the specified color string. If color is not a string, it is coerced to a string; thus, this constructor can also be used to create a copy of an existing color, or force the conversion of a d3.rgb color to HCL. The color string may be in a variety of formats:
- rgb decimal - "rgb(255,255,255)"
- hsl decimal - "hsl(120,50%,20%)"
- rgb hexadecimal - "#ffeeaa"
- rgb shorthand hexadecimal - "#fea"
- named - "red", "white", "blue"
The resulting color is stored as hue in the range [0,360], and chroma and luminance values in the range [0,1]. These values are available as the h, c and l attributes of the returned object. The list of supported named colors is specified by CSS.
# hcl.brighter([k])
Returns a brighter copy of this color. The luminance channel is multiplied by 18 * k. If the gamma value k is omitted, it defaults to 1. The greatest brightness possible is 100.
# hcl.darker([k])
Returns a darker copy of this color. The luminance channel is multiplied by -18 * k. If the gamma value k is omitted, it defaults to 1. The lowest darkness possible is 0.
# hcl.rgb()
Returns the equivalent color in RGB space; see d3.rgb for details on the returned object.
# hcl.toString()
Converts this HCL color to an RGB hexadecimal string, such as "#f7eaba".
# d3.lab(l, a, b)
Constructs a new L*a*b* color with the specified lightness l, a, and b; with a and b being the color-opponent dimensions. The lightness must be in a range from [0,100]. These values are available as the l, a, and b attributes of the returned object.
# d3.lab(color)
Constructs a new L*a*b* color by parsing the specified color string. If color is not a string, it is coerced to a string; thus, this constructor can also be used to create a copy of an existing color, or force the conversion of a d3.rgb color to L*a*b*. The color string may be in a variety of formats:
- rgb decimal - "rgb(255,255,255)"
- hsl decimal - "hsl(120,50%,20%)"
- rgb hexadecimal - "#ffeeaa"
- rgb shorthand hexadecimal - "#fea"
- named - "red", "white", "blue"
The resulting color is stored as lightness in the range [0,100], and corresponding a and b values. These values are available as the l, a, and b attributes of the returned object. The list of supported named colors is specified by CSS. If the color is specified in RGB space, it is converted to L*a*b* by first being converted to XYZ space, then to RGB space.
# lab.brighter([k])
Returns a brighter copy of this color. The lightness channel is multiplied by 18 * k. If the gamma value k is omitted, it defaults to 1. The greatest brightness possible is 100.
# lab.darker([k])
Returns a darker copy of this color. The lightness channel is multiplied by -18 * k. If the gamma value k is omitted, it defaults to 1. The lowest darkness possible is 0.
# lab.rgb()
Returns the equivalent color in RGB space; see d3.rgb for details on the returned object.
# lab.toString()
Converts this L*a*b* color to an RGB hexadecimal string, such as "#f7eaba".
A d3.color base type is provided if you want to extend D3 with additional color spaces. This type enables automatic RGB interpolation by d3.interpolate (detected via instanceof d3.color).
# d3.color()
The base constructor for color types.
# color.rgb()
Returns the RGB equivalent of this color. Must be implemented by all color spaces.
# color.toString()
Converts an RGB hexadecimal string representing this color, such as "#f7eaba".