Legend

• Overview
• Auto Legend
• Easy Auto Legend for Single Series Charts
• Title
• Positioning
  • Outside
  • Inside
  • Drag and Drop
• Layout
• Size
  • Expandable
  • Fixed
• Paging
• Visualization
  • Background
  • Marker Symbol
  • Mouse Cursor
  • Tooltip
• Series Management
• Custom Item
• Custom Legend
• One Legend for Several Charts
• One Legend for Several Series

Overview

Legend is a element of a chart that lists and explains the symbols and colors used on a chart or a map. Sometimes it contains additional information that helps user to understand a chart.

Auto Legend

By default legend shows all series names with a symbol that shows the color and the type of the series.

To enable legend you have to pass "true" to enabled() method or legend() constructor:

Enable using the *legend()# method:

chart.legend(true);

Enable using the enabled() method:

// create chart
var chart = anychart.line();

// enable legend
var legend = chart.legend();
legend.enabled(true);

In the live sample, please notice that when you move the mouse over the series name in legend - all series elements are highlighted and if you click on legend element - series is hidden.

Easy Auto Legend for Single Series Charts

If you are showing a single series chart and want your legend to show all points names and values you should configure the legend:

var legend = chart.legend();
// enable legend
legend.enabled(true);
// set source of legend items
legend.itemsSourceMode("categories");

To create a legend for a single series chart you have to set categories value for itemsSourceMode().

Title

To enable or disable a legend title you have to use the enabled() method of the legend title():

var title = chart.legend().title();
title.enabled(true);

To specify and format the legend title use the text() method of a title(). Settings of a legend title are very similar to the Chart Title article.

var title = chart.legend().title();
title.useHtml(true);

// enable legend title
title.enabled(true);
title.text("Total sales<br><i style=\"color: #999; font-weight: 400; font-size: 11px;\">(Year 2004)</i>");

// set font size and align
title.fontSize(14);
title.hAlign("center");

Here is a sample of a chart and the legend title is configured:

Positioning

Depending on the layout and type of your chart you can position legend to a desired place using the positionMode(), position() and align() methods of a legend().

Outside

"Outside" is a default legend position mode for the most of the charts. In this mode you define the side of the chart it should be placed to, and the alignement:

var legend = chart.legend();
legend.enabled(true);

// set position mode
legend.positionMode("outside");
// set position and alignement
legend.position("bottom");
legend.align("center");
legend.itemsLayout("horizontalExpandable");

Inside

"Inside" position mode is when legend is placed within a data plot (inner area of a chart). In this mode you define the side of a data plot it should be placed to, and the alignement:

var legend = chart.legend();
legend.enabled(true);

// set position mode
legend.positionMode("inside");
// set position and alignement
legend.position("top");
legend.align("right");

Drag and Drop

You can enable the "Drag and Drop" feature of a legend, it allows user to move the legend to any position on a chart. Use the drag() to enable this mode:

var legend = chart.legend();

// Enable drag and drop
legend.drag(true);

Note that drag and drop always works withing constraints set by the position mode and align. It means if a legend positionMode() is set to Inside - you can't move it outside of a data plot, and if it is Outside - you can't move it inside of a data plot.

Here is a sample of a legend that can be moved around:

Layout

The itemsLayout() method controls how the items of a legend are placed. Possible values are listed in anychart.enums.LegendLayout and they are:

• "horizontal",
• "horizontalExpandable",
• "vertical",
• "verticalExpandable".

The legend layout mode works in conjunction with position and size settings.

Size

Legend size is controlled by the following methods:

• maxHeight(),
• maxWidth(),
• height(),
• width(),
• padding(),
• margin().

Expandable

When the legend layout mode is set to "horizontalExpandable" or "verticalExpandable" it makes sense to use maxHeight() and maxWidth() methods control the extent to which legend can expand to. It can be set both in pixels and percents. This way you can ensure that a legend does not grab to much space when there are a few elements and that it will not squeeze the chart into nothingness if there are to many elements.

// Set maximum width and height.
legend.maxWidth("30%");
legend.maxHeight("30%");

// legend mode and position
legend.itemsLayout("verticalExpandable");
legend.position("right");

// paginator position
legend.paginator().orientation("bottom");

See how these settings work in the following interactive sample: you can click buttons to add or remove series and see how legend and chart change their sizes. Once the legend reached maximum allowed size - paging starts.

Fixed

height() and width() methods are used to set the fixed size in pixels or percents. They override maxHeight() and maxWidth() if both are set simultaneously.

Sample Pie Chart with a legend of a fixed (75px - width, 140px height) size positioned to the "Left" of the chart, aligned to "Top", with padding of 10 pixels:

var legend = chart.legend();
// set height
legend.height(140);
// set width
legend.width(95);
// set position
legend.position("left");
// set align
legend.align("top");
// set padding
legend.padding(10);

Here is a sample a legend with a fixed size:

Paging

If legend items can't fit into an area legend can occupy (this is controlled by size settings) paginator() appears. You can choose paginator layout and position:

// legend settings
var paginator = chart.legend().paginator();
// set paginator layout
paginator.layout("vertical");
// place paginator on the right
paginator.orientation("right");

Visualization

Background

To configure the border and the inner color of the legend use the background() method. To learn more about background setting please see the background tutorial.

Marker Symbol

When you are working with line and spline charts you can use markers to distinguish different series. By default AnyChart charting library shows marker symbols in legend - only color representation is used in a small line icon. If you want to tune markers in legend icons you have to adjust legendItem() method. Sample code presented below:

// chart data 
var series = chart.line([
  {x: "John", value: 16000},
  {x: "Jake", value: 21000},
  {x: "Peter", value: 22000}
]);
// enable markers
series.markers(true);
// settings for legend item of the series
var item = series.legendItem()
// set inner color of icon marker
item.iconType("line");

It may be bothersome to tune legend item for each series, you can set defaults using Themes to avoid this:

// set default icons for legend items 
// for lines, splines and markers
anychart.theme({
      chart: {
          defaultSeriesSettings: {
              line: {legendItem: {iconType: "line"}},
              spline: {legendItem: {iconType: "spline"}},
              marker: {legendItem: {iconType: "marker"}}
  }}});

Here is a sample with defaults for legend set to show series icons with markers:

Mouse Cursor

Use the hoverCursor() method to set the type of cursor that is shown when mouse moves over the legend items. You can use string values or anychart.enums.Cursor.

var legend = chart.legend();
legend.hoverCursor(anychart.enums.Cursor.POINTER); // sets hover cursor using enum
legend.hoverCursor("pointer"); // sets hover cursor using a string

Tooltip

If you want to configure legend tooltips - you should do that using tooltip() methods. You can tune its visual appearance and format. In the following sample we will format tooltips of the legend to show detailed description information.

Series Management

You can easily control series of the chart using chart legend. You can hide and show any of the series by clicking on the legend items. Here is a sample of column chart with four series. One of the series is already disabled. Click on the last legend item to show hidden series.

Custom Item

When creating legend you can add your own items with any information you want to see on the legend, to do that use itemsFormatter() method.

var legend = chart.legend();
// adjust legend items
legend.itemsFormatter(function(items){
  // push into items array
  items.push({
    // set text of a new item
    text: "item text "
  });
  // return items array
  return items;
});

In the sample chart below we've used custom item that adds Total data to legend.

Custom Legend

AnyChart JavaScript Framework sets no limits to the amount of legends on one chart plot. Legend can be a part chart as well as a separate unit. Sample below demonstrates three custom legend at the bottom of the chart.

One Legend for Several Charts

As you can see, one legend can contain different information from one chart. Moreover, one legend can contain information from several charts. To add several chart into one legend use itemsSource() method and define charts for legend's content.

// define charts
var chart2005 = anychart.column();
var chart2006 = anychart.column();

// create custom legend
var legend = anychart.standalones.legend();
// set sources for legend items
legend.itemsSource([chart2005, chart2006]);

One Legend for Several Series

You can attache an event to a legend items. Use listen() method to set an event for a legend. List of possible event can be found in anychart.enums.EventType. For additional information on events in AnyChart you can find in Event Listeners tutorial

// create legend
var legend = anychart.standalones.legend();

// enable and disable series on legend item click
legend.listen("legendItemClick", function(event) {
  // get item's index
  var index = event["itemIndex"];
  // manage enabled/disabled state of the series
  chart2005.getSeries(index).enabled(! chart2005.getSeries(index).enabled());
  chart2006.getSeries(index).enabled(! chart2006.getSeries(index).enabled());
});

Sample below demonstrate managing several series with one legend item.