Color Legend Element

<color-legend></color-legend>

A Custom Element suitable for use as a legend in data visualizations. Built with Lit/Lit-Element and D3JS.

Features

Render legends for continuous, discrete, and categorical data.
Uses d3-scale's concept of a domain and a range for mapping values to visual marks.
Compatable with color interpolators from d3-scale-chromatic
Customizable via its properties / attributes and CSS variables.
Framework and bundler not required, just add a <script> tag and use it!
Small bundle size (28kb minified and 9kb gzipped)

Installation

NOTE: the <color-legend> assumes D3JS is available as a dependency. At the very least this should include the following modules from the D3JS library: d3-scale, d3-array, d3-format, d3-interpolate, and d3-scale-chromatic (if using one of d3's color scheme interpolators).

Install via npm:

npm install color-legend-element

You may then import the <color-legend> in the desired ES Module:

import "color-legend-element";

To use without a frontend build tool, add the <color-legend> via a <script> tag in your HTML document.

<script
  type="module"
  src="color-legend-element/build/color-legend-element.js"
></script>

If you prefer to not use the ESM build, you may instead use the UMD build:

<script src="color-legend-element/build/color-legend-element.umd.js"></script>

Windows OS Install

Note that Windows OS users may experience a problem with module bundlers where the D3JS dependencies are not found by the CLE. To work around this, it is recommended to be sure to use the ESM build:

import "color-legend-element/build/color-legend-element.js";

Example Usage

The <color-legend> will render using its default settings as follows:

<color-legend></color-legend>

It may be customized by settings its properties and CSS variables (full list below).

See the color-legend website for more examples of how to use the Color Legend Element.

Properties

The following table lists the Color Legend Element's properties and attributes. See the color-legend website for examples of how these properties may be configured to render various types of legends. All properties listed have a corresponding HTML attribute of the same name except for the interpolator property which may only be set as a property using JavaScript.

Property	Type	Default Value	Description	Has Attribute
titleText	string	"Color Legend Element"	The title text that displays at the top of the legend.	Yes
width	number	325	The width of the SVG or categorical legend div element.	Yes
height	number	32	The height of the SVG element.	Yes
marginTop	number	6	The spacing between the legend bar and top most extent of the SVG.	Yes
marginRight	number	12	The spacing between the legend bar and right most extent of the SVG.	Yes
marginBottom	number	16	The spacing between the legend bar and bottom most extent of the SVG.	Yes
marginLeft	number	12	The spacing between the legend bar and left most extent of the SVG.	Yes
scaleType	ScaleType	"continuous"	The type of legend to render based on d3-scale.	Yes
domain	number\|string[]	[0, 1]	The color scale's domain values.	Yes
range	string[]	d3.schemeYlGnBu[5]	The color scale's range values.	Yes
markType	MarkType	"circle"	The symbology used for categorical legends.	Yes
ticks	number	5	The desired number of axis ticks.	Yes
tickFormat	string	".1f"	The d3-format specifier to format axis tick values.	Yes
tickSize	number	6	The size or length of the axis ticks.	Yes
tickValues	number[]	null	The explicit values to be used for axis ticks.	Yes
interpolator	Interpolator	null	The color interpolator function.	No

Note: see types for enum types such as ScaleType, MarkType, and Interpolator.

CSS Variables

The internal styling (CSS) of the Color Legend Element may be altered via the following CSS variables / custom properties:

Custom Property	Default Value	Description
--cle-font-family	sans-serif	Font used for tick and legend item text
--cle-font-family-title	var(--cle-font-family)	Font used for the legend's title text
--cle-font-size	0.75rem	Font size for the tick and legend item text
--cle-font-size-title	0.875rem	Font size for the legend title text
--cle-letter-spacing	0.3px	Letter spacing for tick and legend item text
--cle-letter-spacing-title	0.25px	Letter spacing for the legend title text
--cle-font-weight	400	Font weight for the tick and legend item text
--cle-font-weight-title	500	Font weight for the title text
--cle-color	currentColor	Font color for all text and tick lines
--cle-background	#fff	Background color for the legend
--cle-padding	0.375rem	Padding in the legend's container div
--cle-border	none	Border style of the legend's container div
--cle-border-radius	0	Border radius of the legend's container div
--cle-box-sizing	content-box	Box-sizing property of the legend's container div
--cle-columns	2	Number of columns for categorical legends
--cle-column-width	auto	Column width for categorical legends
--cle-item-margin	0.375rem 0.75rem 0 0	Margin property for categorical legend items
--cle-line-width	24px	Width of the "line" markType for categorical legends
--cle-line-height	2px	Height of the "line" markType for categorical legends
--cle-swatch-size	10px	Height & Width of "rect" and "circle" markTypes for categorical legends
--cle-swatch-width	var(--cle-swatch-size)	Width of the "rect" and "circle" markTypes for categorical legends
--cle-swatch-height	var(--cle-swatch-size)	Height of the "rect" and "circle" markTypes for categorical legends
--cle-swatch-margin	0 0.5rem 0 0	Margin of the mark (line, square, circle) for categorical legends

The following example demonstrates how to override the default values of the <color-legend>'s CSS variables:

color-legend {
  --cle-font-family: serif;
  --cle-font-family-title: Impact;
  --cle-letter-spacing-title: 0.5px;
  --cle-color: white;
  --cle-background: #222;
  --cle-border-radius: 6px;
  --cle-padding: 0.25rem 0.25rem 0.75rem;
}

Local Development

Requires Node.js v16.13.0 and NPM >=8.

In the root of this repository first install dependencies:

npm install

Building from src

All compiled files will be outputted in the build/ directory.

To create the ESM build:

npm run build

or to watch for changes:

npm run build:watch

To create both the ESM & UMD bundles:

npm run bundle

Develop

To view the <color-legend> without bundling it:

npm run serve

npm run serve:prod

This will start up a local web server for dev/index.html. You may then modify the contents of src/ and/or dev/index.html and inspect the changes in your browser.

Running tests

Tests are located in src/test and may be run in either a development or production environment via:

npm run test:dev

or:

npm run test:prod

To run tests in both a development and a production environment do:

npm run test

To have the tests run when making changes to src/:

npm run test:watch

npm run test:prod:watch

Building the docs

To generate the docs directory:

npm run docs

This will first remove the docs/ directory, build files from the src/, and build files from the docs-src/ directory into the docs/ directory. All necessary files will be copied into docs/ directory (e.g. from build/ and node_modules/) in order for the <color-legend> render as it would in a production environment.

To serve the docs directory and watch for changes:

npm run docs:serve

Then open your browser to localhost:8080 to view the site.

Updating the custom-elements.json

According to Open Web Components:

Custom Elements Manifest is a file format that describes custom elements. This format will allow tooling and IDEs to give rich information about the custom elements in a given project.

To update the custom-elements.json manifest:

npm run analyze

dalbir/color-legend-element