Legend

live example

Explore the API in the live example.

api reference

Legend(name[, parent])

The legend control widget. This widget extends the following components:

Color
Font
Highlight: plot groups can be highlighted by passing their names as specified in the data array.
Mouse: The entry name is passed to the mouse callbacks.
Widget

Parameters

Name	Type	Description
name	string	Name of the legend. Should be a unique identifier.
parent	string	optionalSee [Widget] ../components/widget.html for description. Default value is `body`.

Legend.columns([columns])

Sets the number of columns to organize legend entries in.

Parameters

Name	Type	Description
columns	number	optionalNumber of columns. Default value is `1`.

Returns

Object

Reference to the Legend's API.

Examples

// Have 3 columns in the legend.
const legend = dalian.Legend('my-legend')
  .columns(3)
  .render()

// Reset to single column.
legend.columns()
  .render()

Legend.entries(entries)

Sets the entries of the legend. Legend entries follow the same order as provided by this method.

Parameters

Name	Type	Description
entries	Object[]	Array of objects representing the legend entries. Each entry is defined by a `name` and a `label` property. The name is used for coloring, styling and interactions whereas the label is the displayed name of the entry.

Returns

Object

Reference to the Legend's API.

Examples

// Set labels to the legend.
const legend = dalian.Legend('my-legend')
  .entries([
    {name'a', label: 'Apple'},
    {name: 'b', label: 'Banana'},
    {name: 'c', label: 'Cranberries'}
  ])
  .render()

// Change labels.
legend.entries([
  {name: 'a', label: 'Alice'},
  {name: 'b', label: 'Bob'},
  {name: 'c', label: 'Charlie'}
]).render()

Legend.hSep([length])

Sets the horizontal separation between the legend entries. The separation is measured between the center of the entry markers.

Parameters

Name	Type	Description
length	number	optionalSize of the horizontal separation in units of the current font size. Default value is `6`.

Returns

Object

Reference to the Legend's API.

Examples

// Set horizontal separation to 10 em.
const legend = dalian.Legend('my-legend')
  .hSep(10)
  .render()

// Reset vertical separation to 6 em.
legend.hSep()
  .render()

Legend.insert(widget, pos)

Inserts the legend in a widget if that widget supports the Objects component. Note that this will remove the legend's widget as such and makes the legend part of the parent widget. However, all Legend API methods continue to function as expected.

Parameters

Name	Type	Description
widget	Widget	Any widget that supports inserting objects. If not specified, the legend is removed from the current parent widget (if there is any).
pos	Object	Object representing the position within the widget where the legend should be inserted.

Returns

Object

Reference to the Legend's API.

Examples

// Insert legend in the top left corner of a chart called 'figure'.
const legend = dalian.Legend('my-legend')
  ...
  .render()
legend.insert(figure, {x: 10, y: 10}).

// Remove the legend from 'figure' and move it back to its own container.
legend.insert()

Legend.markers([markers])

Sets the legend marker shape.

Parameters

Name	Type	Description
markers	string	optionalMarker shape. Either one of the supported values (square, circle) or a custom path. In case of a custom marker, the passed string is used as the d attribute of a path. Note that the path origin is set to the center of the square marker. Default value is `square`.

Returns

Object

Reference to the Legend's API.

Examples

// Set markers to circles.
const legend = dalian.Legend('my-legend')
  .markers('circle')
  .render()

// Set markers to an equilateral triangle.
legend.markers('m -0.5 4.33 l 0.5 -8.66 l 0.5 8.66 z')
  .render()

Legend.styles(styles)

Sets the background style of the legend entry markers.

Parameters

Name	Type	Description
styles	Object	Object mapping from the entry names to style strings. If an entry's name is not present in the mapping, it defaults to solid. Default value is solid for all entries. A typical parameter is the return value from the LineStyle component's mapper function.

Returns

Object

Reference to the Legend's API.

Examples

// Set styles.
const legend = dalian.Legend('my-legend')
  .entries([
    {name: 'a', label: 'Alice'},
    {name: 'b', label: 'Bob'},
    {name: 'c', label: 'Charlie'}
  ])
  .styles({
    b: 'dashed',
    c: 'dotted'
  }).render()

Legend.vSep([length])

Sets the vertical separation between the legend entries. The separation is measured between the baseline of the entry labels.

Parameters

Name	Type	Description
length	number	optionalSize of the vertical separation in units of the current font size. Default value is `1.4`.

Returns

Object

Reference to the Legend's API.

Examples

// Set vertical separation to 2 em.
const legend = dalian.Legend('my-legend')
  .vSep(2)
  .render()

// Reset vertical separation to 1.4 em.
legend.vSep()
  .render()