Socket
Socket
Sign inDemoInstall

d3-color

Package Overview
Dependencies
0
Maintainers
2
Versions
45
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

d3-color

Color spaces! RGB, HSL, Cubehelix, Lab and HCL (Lch).


Version published
Maintainers
2
Weekly downloads
6,271,233
decreased by-8.63%

Weekly downloads

Package description

What is d3-color?

The d3-color npm package provides a robust framework for color manipulation and conversion. It allows users to parse color strings, manipulate colors in different color spaces, and format colors for display. It is part of the larger D3 (Data-Driven Documents) suite of tools, which are used for manipulating documents based on data.

What are d3-color's main functionalities?

Parsing and Formatting Colors

This feature allows users to parse CSS color strings and then format them back into a string. The example shows how to parse 'steelblue' into a color object and then output it as an RGB string.

"var color = d3.color('steelblue');\nconsole.log(color.toString()); // 'rgb(70, 130, 180)'"

Manipulating Color Channels

Users can directly manipulate the channels of a color, including its opacity. In the example, an RGB color is created and its opacity is set before converting it back to a string.

"var color = d3.rgb(70, 130, 180);\ncolor.opacity = 0.5;\nconsole.log(color.toString()); // 'rgba(70, 130, 180, 0.5)'"

Working with Different Color Spaces

d3-color supports various color spaces such as RGB, HSL, and LAB. This example demonstrates converting an HSL color to its equivalent RGB string.

"var color = d3.hsl(210, 0.44, 0.49);\nconsole.log(color.toString()); // 'rgb(70, 130, 180)'"

Other packages similar to d3-color

Readme

Source

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, conversion and manipulation. (Also see d3-interpolate for color interpolation.)

For example, take the color named “steelblue”:

const c = d3.color("steelblue"); // {r: 70, g: 130, b: 180, opacity: 1}

Let’s try converting it to HSL:

const c = d3.hsl("steelblue"); // {h: 207.27…, s: 0.44, l: 0.4902…, opacity: 1}

Now rotate the hue by 90°, bump up the saturation, and format as a string for CSS:

c.h += 90;
c.s += 0.2;
c + ""; // rgb(198, 45, 205)

To fade the color slightly:

c.opacity = 0.8;
c + ""; // rgba(198, 45, 205, 0.8)

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

  • CIELAB (a.k.a. “Lab”)
  • CIELChab (a.k.a. “LCh” or “HCL”)
  • Dave Green’s Cubehelix

Cubehelix features monotonic lightness, while CIELAB and its polar form CIELChab are perceptually uniform.

Extensions

For additional color spaces, see:

To measure color differences, see:

Installing

If you use npm, npm install d3-color. You can also download the latest release on GitHub. For vanilla HTML in modern browsers, import d3-color from Skypack:

<script type="module">

import {rgb} from "https://cdn.skypack.dev/d3-color@3";

const steelblue = d3.rgb("steelblue");

</script>

For legacy environments, you can load d3-color’s UMD bundle from an npm-based CDN such as jsDelivr; a d3 global is exported:

<script src="https://cdn.jsdelivr.net/npm/d3-color@3"></script>
<script>

const steelblue = d3.rgb("steelblue");

</script>

Try d3-color in your browser.

API Reference

# d3.color(specifier) <>

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

  • rgb(255, 255, 255)
  • rgb(10%, 20%, 30%)
  • rgba(255, 255, 255, 0.4)
  • rgba(10%, 20%, 30%, 0.4)
  • hsl(120, 50%, 20%)
  • hsla(120, 50%, 20%, 0.4)
  • #ffeeaa
  • #fea
  • #ffeeaa22
  • #fea2
  • 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.opacity

This color’s opacity, typically in the range [0, 1].

# color.rgb() <>

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

# color.copy([values]) <>

Returns a copy of this color. If values is specified, any enumerable own properties of values are assigned to the new returned color. For example, to derive a copy of a color with opacity 0.5, say

color.copy({opacity: 0.5})

# 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 darker 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 when rounded, or if the opacity is not in the range [0, 1].

# color.formatHex() <>

Returns a hexadecimal string representing this color in RGB space, 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.

# color.formatHsl() <>

Returns a string representing this color according to the CSS Color Module Level 3 specification, such as hsl(257, 50%, 80%) or hsla(257, 50%, 80%, 0.2). If this color is not displayable, a suitable displayable color is returned instead by clamping S and L channel values to the interval [0, 100].

# color.formatRgb() <>

Returns a string representing this color according to the CSS Object Model specification, such as rgb(247, 234, 186) or rgba(247, 234, 186, 0.2). If this color is not displayable, a suitable displayable color is returned instead by clamping RGB channel values to the interval [0, 255].

# color.toString() <>

An alias for color.formatRgb.

# d3.rgb(r, g, b[, opacity]) <>
# d3.rgb(specifier)
# d3.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; an opacity may also be specified. 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.

# rgb.clamp() <>

Returns a new RGB color where the r, g, and b channels are clamped to the range [0, 255] and rounded to the nearest integer value, and the opacity is clamped to the range [0, 1].

# d3.hsl(h, s, l[, opacity]) <>
# d3.hsl(specifier)
# d3.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; an opacity may also be specified. 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.)

# hsl.clamp() <>

Returns a new HSL color where the h channel is clamped to the range [0, 360), and the s, l, and opacity channels are clamped to the range [0, 1].

# d3.lab(l, a, b[, opacity]) <>
# d3.lab(specifier)
# d3.lab(color)

Constructs a new CIELAB color. The channel values are exposed as l, a and b properties on the returned instance. Use the CIELAB color picker to explore this color space. The value of l is typically in the range [0, 100], while a and b are typically in [-160, +160].

If l, a and b are specified, these represent the channel values of the returned color; an opacity may also be specified. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to the CIELAB 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 CIELAB. (Colors already in the CIELAB color space skip the conversion to RGB, and colors in the HCL color space are converted directly to CIELAB.)

# d3.gray(l[, opacity]) <>

Constructs a new CIELAB color with the specified l value and a = b = 0.

# d3.hcl(h, c, l[, opacity]) <>
# d3.hcl(specifier)
# d3.hcl(color)

Equivalent to d3.lch, but with reversed argument order.

# d3.lch(l, c, h[, opacity]) <>
# d3.lch(specifier)
# d3.lch(color)

Constructs a new CIELChab color. The channel values are exposed as l, c and h properties on the returned instance. Use the CIELChab color picker to explore this color space. The value of l is typically in the range [0, 100], c is typically in [0, 230], and h is typically in [0, 360).

If l, c, and h are specified, these represent the channel values of the returned color; an opacity may also be specified. If a CSS Color Module Level 3 specifier string is specified, it is parsed and then converted to CIELChab 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 CIELChab. (Colors already in CIELChab color space skip the conversion to RGB, and colors in CIELAB color space are converted directly to CIELChab.)

# d3.cubehelix(h, s, l[, opacity]) <>
# d3.cubehelix(specifier)
# d3.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; an opacity may also be specified. 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.)

Keywords

FAQs

Last updated on 28 Mar 2022

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc