d3plus-legend

An easy to use javascript chart legend.

Installing

If using npm, npm install d3plus-legend. Otherwise, you can download the latest release from GitHub or load from a CDN.

import modules from "d3plus-legend";

d3plus-legend can be loaded as a standalone library or bundled as part of D3plus. ES modules, AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3plus global is exported:

<script src="https://cdn.jsdelivr.net/npm/d3plus-legend@1"></script>
<script>
  console.log(d3plus);
</script>

Examples

Live examples can be found on d3plus.org, which includes a collection of example visualizations using d3plus-react. These examples are powered by the d3plus-storybook repo, and PRs are always welcome. :beers:

API Reference

• ColorScale
• Legend

ColorScale <>

This is a global class, and extends all of the methods and functionality of BaseClass.

• ColorScale ⇐ BaseClass
  • new ColorScale()
  • .render([callback]) ↩︎
  • .axisConfig([value]) ↩︎
  • .align([value]) ↩︎
  • .buckets([value]) ↩︎
  • .bucketAxis([value]) ↩︎
  • .bucketFormat([value]) ↩︎
  • .bucketJoiner([value]) ↩︎
  • .centered([value]) ↩︎
  • .color([value]) ↩︎
  • .colorMax([value]) ↩︎
  • .colorMid([value]) ↩︎
  • .colorMin([value]) ↩︎
  • .data([data]) ↩︎
  • .domain([value]) ↩︎
  • .duration([value]) ↩︎
  • .height([value]) ↩︎
  • .labelConfig([value]) ↩︎
  • .labelMin([value]) ↩︎
  • .labelMax([value]) ↩︎
  • .legendConfig([value]) ↩︎
  • .midpoint([value]) ↩︎
  • .orient([value]) ↩︎
  • .outerBounds()
  • .padding([value]) ↩︎
  • .rectConfig([value]) ↩︎
  • .scale([value]) ↩︎
  • .select([selector]) ↩︎
  • .size([value]) ↩︎
  • .value([value]) ↩︎
  • .width([value]) ↩︎

# new ColorScale()

Creates an SVG scale based on an array of data. If data is specified, immediately draws based on the specified array and returns the current class instance. If data is not specified on instantiation, it can be passed/updated after instantiation using the data method.

# ColorScale.render([callback]) <>

Renders the current ColorScale to the page. If a callback is specified, it will be called once the ColorScale is done drawing.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.axisConfig([value]) <>

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. An example usage of this method can be seen here.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.align([value]) <>

If value is specified, sets the horizontal alignment to the specified value and returns the current class instance. If value is not specified, returns the current horizontal alignment.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.buckets([value]) <>

The number of discrete buckets to create in a bucketed color scale. Will be overridden by any custom Array of colors passed to the color method. Optionally, users can supply an Array of values used to separate buckets, such as [0, 10, 25, 50, 90] for a percentage scale. This value would create 4 buckets, with each value representing the break point between each bucket (so 5 values makes 4 buckets).

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.bucketAxis([value]) <>

Determines whether or not to use an Axis to display bucket scales (both "buckets" and "jenks"). When set to false, bucketed scales will use the Legend class to display squares for each range of data. When set to true, bucketed scales will be displayed on an Axis, similar to "linear" scales.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.bucketFormat([value]) <>

A function for formatting the labels associated to each bucket in a bucket-type scale ("jenks", "quantile", etc). The function is passed four arguments: the start value of the current bucket, it's index in the full Array of buckets, the full Array of buckets, and an Array of every value present in the data used to construct the buckets. Keep in mind that the end value for the bucket is not actually the next bucket in the list, but includes every value up until that next bucket value (less than, but not equal to). By default, d3plus will make the end value slightly less than it's current value, so that it does not overlap with the start label for the next bucket.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.bucketJoiner([value]) <>

A function that receives the minimum and maximum values of a bucket, and is expected to return the full label.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.centered([value]) <>

Determines whether or not to display a midpoint centered Axis. Does not apply to quantile scales.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.color([value]) <>

Overrides the default internal logic of colorMin, colorMid, and colorMax to only use just this specified color. If a single color is given as a String, then the scale is interpolated by lightening that color. Otherwise, the function expects an Array of color values to be used in order for the scale.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.colorMax([value]) <>

Defines the color to be used for numbers greater than the value of the midpoint on the scale (defaults to 0). Colors in between this value and the value of colorMid will be interpolated, unless a custom Array of colors has been specified using the color method.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.colorMid([value]) <>

Defines the color to be used for the midpoint of a diverging scale, based on the current value of the midpoint method (defaults to 0). Colors in between this value and the values of colorMin and colorMax will be interpolated, unless a custom Array of colors has been specified using the color method.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.colorMin([value]) <>

Defines the color to be used for numbers less than the value of the midpoint on the scale (defaults to 0). Colors in between this value and the value of colorMid will be interpolated, unless a custom Array of colors has been specified using the color method.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.data([data]) <>

If data is specified, sets the data array to the specified array and returns the current class instance. If data is not specified, returns the current data array. A shape key will be drawn for each object in the array.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.domain([value]) <>

In a linear scale, this Array of 2 values defines the min and max values used in the color scale. Any values outside of this range will be mapped to the nearest color value.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.duration([value]) <>

If value is specified, sets the transition duration of the ColorScale and returns the current class instance. If value is not specified, returns the current duration.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.height([value]) <>

If value is specified, sets the overall height of the ColorScale and returns the current class instance. If value is not specified, returns the current height value.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.labelConfig([value]) <>

A pass-through for the TextBox class used to style the labelMin and labelMax text.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.labelMin([value]) <>

Defines a text label to be displayed off of the end of the minimum point in the scale (currently only available in horizontal orientation).

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.labelMax([value]) <>

Defines a text label to be displayed off of the end of the maximum point in the scale (currently only available in horizontal orientation).

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.legendConfig([value]) <>

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. An example usage of this method can be seen here.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.midpoint([value]) <>

The number value to be used as the anchor for colorMid, and defines the center point of the diverging color scale.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.orient([value]) <>

Sets the flow of the items inside the ColorScale. If no value is passed, the current flow will be returned.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.outerBounds() <>

If called after the elements have been drawn to DOM, will returns the outer bounds of the ColorScale content.

This is a static method of ColorScale.

{"width": 180, "height": 24, "x": 10, "y": 20}

# ColorScale.padding([value]) <>

If value is specified, sets the padding between each key to the specified number and returns the current class instance. If value is not specified, returns the current padding value.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.rectConfig([value]) <>

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. An example usage of this method can be seen here.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.scale([value]) <>

If value is specified, sets the scale of the ColorScale and returns the current class instance. If value is not specified, returns the current scale value.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.select([selector]) <>

If selector is specified, sets the SVG container element to the specified d3 selector or DOM element and returns the current class instance. If selector is not specified, returns the current SVG container element.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.size([value]) <>

The height of horizontal color scales, and width when positioned vertical.

This is a static method of ColorScale, and is chainable with other methods of this Class.

# ColorScale.value([value]) <>

If value is specified, sets the value accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current value accessor.

This is a static method of ColorScale, and is chainable with other methods of this Class.

function value(d) {
  return d.value;
}

# ColorScale.width([value]) <>

If value is specified, sets the overall width of the ColorScale and returns the current class instance. If value is not specified, returns the current width value.

This is a static method of ColorScale, and is chainable with other methods of this Class.

Legend <>

This is a global class, and extends all of the methods and functionality of BaseClass.

• Legend ⇐ BaseClass
  • new Legend()
  • .render([callback]) ↩︎
  • .active([value]) ↩︎
  • .align([value]) ↩︎
  • .data([data]) ↩︎
  • .direction([value]) ↩︎
  • .duration([value]) ↩︎
  • .height([value]) ↩︎
  • .hover([value]) ↩︎
  • .id([value]) ↩︎
  • .label([value]) ↩︎
  • .outerBounds()
  • .padding([value]) ↩︎
  • .select([selector]) ↩︎
  • .shape([value]) ↩︎
  • .shapeConfig([config]) ↩︎
  • .title([value]) ↩︎
  • .titleConfig([value]) ↩︎
  • .verticalAlign([value]) ↩︎
  • .width([value]) ↩︎

# new Legend()

Creates an SVG scale based on an array of data. If data is specified, immediately draws based on the specified array and returns the current class instance. If data is not specified on instantiation, it can be passed/updated after instantiation using the data method.

# Legend.render([callback]) <>

Renders the current Legend to the page. If a callback is specified, it will be called once the legend is done drawing.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.active([value]) <>

If value is specified, sets the active method for all shapes to the specified function and returns the current class instance. If value is not specified, returns the current active method.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.align([value]) <>

If value is specified, sets the horizontal alignment to the specified value and returns the current class instance. If value is not specified, returns the current horizontal alignment.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.data([data]) <>

If data is specified, sets the data array to the specified array and returns the current class instance. If data is not specified, returns the current data array. A shape key will be drawn for each object in the array.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.direction([value]) <>

Sets the flow of the items inside the legend. If no value is passed, the current flow will be returned.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.duration([value]) <>

If value is specified, sets the transition duration of the legend and returns the current class instance. If value is not specified, returns the current duration.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.height([value]) <>

If value is specified, sets the overall height of the legend and returns the current class instance. If value is not specified, returns the current height value.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.hover([value]) <>

If value is specified, sets the hover method for all shapes to the specified function and returns the current class instance. If value is not specified, returns the current hover method.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.id([value]) <>

If value is specified, sets the id accessor to the specified function and returns the current class instance. If value is not specified, returns the current id accessor.

This is a static method of Legend, and is chainable with other methods of this Class.

function value(d) {
  return d.id;
}

# Legend.label([value]) <>

If value is specified, sets the label accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current label accessor, which is the id accessor by default.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.outerBounds() <>

If called after the elements have been drawn to DOM, will returns the outer bounds of the legend content.

This is a static method of Legend.

{"width": 180, "height": 24, "x": 10, "y": 20}

# Legend.padding([value]) <>

If value is specified, sets the padding between each key to the specified number and returns the current class instance. If value is not specified, returns the current padding value.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.select([selector]) <>

If selector is specified, sets the SVG container element to the specified d3 selector or DOM element and returns the current class instance. If selector is not specified, returns the current SVG container element.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.shape([value]) <>

If value is specified, sets the shape accessor to the specified function or string and returns the current class instance. If value is not specified, returns the current shape accessor.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.shapeConfig([config]) <>

If config is specified, sets the methods that correspond to the key/value pairs for each shape and returns the current class instance. If config is not specified, returns the current shape configuration.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.title([value]) <>

If value is specified, sets the title of the legend and returns the current class instance. If value is not specified, returns the current title.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.titleConfig([value]) <>

If value is specified, sets the title configuration of the legend and returns the current class instance. If value is not specified, returns the current title configuration.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.verticalAlign([value]) <>

If value is specified, sets the vertical alignment to the specified value and returns the current class instance. If value is not specified, returns the current vertical alignment.

This is a static method of Legend, and is chainable with other methods of this Class.

# Legend.width([value]) <>

If value is specified, sets the overall width of the legend and returns the current class instance. If value is not specified, returns the current width value.

This is a static method of Legend, and is chainable with other methods of this Class.

Documentation generated on Fri, 16 Aug 2024 19:26:03 GMT