d3plus-legend

d3plus-legend

A collection of chart legends/keys.

Installation Options

• NPM
• Browser
• AMD and CommonJS
• Custom Builds

NPM

npm install d3plus-legend

Browser

In a vanilla environment, a d3plus_legend global is exported. To use a compiled version hosted on d3plus.org that includes all dependencies:

<script src="https://d3plus.org/js/d3plus-legend.v0.2.full.min.js"></script>

Otherwise, click here to download the latest release.

AMD and CommonJS

The released bundle natively supports both AMD and CommonJS, in addition to vanilla environments.

Custom Builds

The source code is written using standard import and export statements. Create a custom build using Rollup or your preferred bundler. Take a look at the index.js file to see the modules exported.

---

API Reference

shape([data])

Creates an SVG shape legend based on an array of data. If data is specified, immediately draws based on the specified array and returns this generator. If data is not specified on instantiation, it can be passed/updated after instantiation using the data method.

Kind: global function

Param	Type	Default
[data]	Array	[]

Example (a sample dataset)

var data = [
  {"id": 0, "color": "brickred"},
  {"id": 1, "color": "cornflowerblue"}
];

Example (passed to the generator)

shape([data]);

Example (creates the following)

<g class="d3plus-shape-rect" id="d3plus-shape-rect-0" transform="translate(100,50)">
  <rect width="200" height="100" x="-100" y="-50" fill="black"></rect>
</g>

Example (this is shorthand for the following)

shape().data([data])();

Example (which also allows a post-draw callback function)

shape().data([data])(function() { alert("draw complete!"); })

• shape([data])
  • .align([value])
  • .backgroundColor([color])
  • .data([data])
  • .fill([value])
  • .fontColor([value])
  • .fontFamily([value])
  • .fontResize([value])
  • .fontSize([value])
  • .height([value])
  • .id([value])
  • .label([value])
  • .labelBounds([bounds])
  • .on([typenames], [listener])
  • .orient([orient])
  • .outerBounds()
  • .padding([value])
  • .select([selector])
  • .shapeImage([value])
  • .size([value])
  • .verticalAlign([value])
  • .width([value])
  • .x([value])
  • .y([value])

shape.align([value])

If value is specified, sets the horizontal alignment to the specified value and returns this generator. If value is not specified, returns the current horizontal alignment.

Kind: static method of shape

Param	Type	Default	Description
[value]	String	"center"	Supports "left" and "center" and "right".

shape.backgroundColor([color])

If a valid CSS color is specified, sets the overall background color to the specified value and returns this generator. If color is not specified, returns the current background color.

Kind: static method of shape

Param	Type	Default
[color]	String	[]

shape.data([data])

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

Kind: static method of shape

Param	Type	Default
[data]	Array	[]

shape.fill([value])

If value is specified, sets the fill accessor to the specified function and returns this generator. If value is not specified, returns the current fill accessor.

Kind: static method of shape

Param	Type
[value]	function

Example

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

shape.fontColor([value])

If value is specified, sets the font-color accessor to the specified function or string and returns this generator. If value is not specified, returns the current font-color accessor, which by default returns a color that contrasts the fill color.

Kind: static method of shape

Param	Type
[value]	function | String

shape.fontFamily([value])

If value is specified, sets the font-family accessor to the specified function or string and returns this generator. If value is not specified, returns the current font-family accessor.

Kind: static method of shape

Param	Type
[value]	function | String

shape.fontResize([value])

If value is specified, sets the font resizing accessor to the specified function or boolean and returns this generator. If value is not specified, returns the current font resizing accessor. When font resizing is enabled, the font-size of the value returned by label will be resized the best fit the rectangle.

Kind: static method of shape

Param	Type
[value]	function | Boolean

shape.fontSize([value])

If value is specified, sets the font-size accessor to the specified function or string and returns this generator. If value is not specified, returns the current font-size accessor.

Kind: static method of shape

Param	Type
[value]	function | String

shape.height([value])

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

Kind: static method of shape

Param	Type	Default
[value]	Number	100

shape.id([value])

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

Kind: static method of shape

Param	Type
[value]	function

Example

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

shape.label([value])

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

Kind: static method of shape

Param	Type
[value]	function | String

shape.labelBounds([bounds])

If bounds is specified, sets the inner bounds to the specified function and returns this legend generator. If bounds is not specified, returns the current inner bounds accessor.

Kind: static method of shape

Param	Type	Description
[bounds]	function	Given a shape's width and height, the function should return an object containing the following values: width, height, x, y.

Example

function(w, h) {
  return {
    "width": w,
    "height": h,
    "x": -w / 2,
    "y": -h / 2
  };
}
      

shape.on([typenames], [listener])

Adds or removes a listener to each shape for the specified event typenames. If a listener is not specified, returns the currently-assigned listener for the specified event typename. Mirrors the core d3-selection behavior.

Kind: static method of shape

Param	Type
[typenames]	String
[listener]	function

shape.orient([orient])

If orient is specified, sets the orientation of the shape and returns this generator. If orient is not specified, returns the current orientation.

Kind: static method of shape

Param	Type	Default	Description
[orient]	String	"horizontal"	Supports "horizontal" and "vertical" orientations.

shape.outerBounds()

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

Kind: static method of shape
Example

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

shape.padding([value])

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

Kind: static method of shape

Param	Type	Default
[value]	Number	10

shape.select([selector])

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

Kind: static method of shape

Param	Type	Default
[selector]	String | HTMLElement	d3Select("body").append("svg")

shape.shapeImage([value])

If value is specified, sets the shape background image accessor to the specified function or string and returns this generator. If value is not specified, returns the current shape background image accessor, which by default returns a color that contrasts the fill color.

Kind: static method of shape

Param	Type
[value]	function | String

shape.size([value])

If value is specified, sets the size accessor to the specified function or number and returns this generator. If value is not specified, returns the current size accessor.

Kind: static method of shape

Param	Type	Default
[value]	function | Number	20

shape.verticalAlign([value])

If value is specified, sets the vertical alignment to the specified value and returns this generator. If value is not specified, returns the current vertical alignment.

Kind: static method of shape

Param	Type	Default	Description
[value]	String	"middle"	Supports "top" and "middle" and "bottom".

shape.width([value])

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

Kind: static method of shape

Param	Type	Default
[value]	Number	400

shape.x([value])

If value is specified, sets the x accessor to the specified function or number and returns this generator. If value is not specified, returns the current x accessor.

Kind: static method of shape

Param	Type
[value]	function | Number

shape.y([value])

If value is specified, sets the y accessor to the specified function or number and returns this generator. If value is not specified, returns the current y accessor.

Kind: static method of shape

Param	Type
[value]	function | Number