Legend
- Overview
- Auto Legend
- Title
- Positioning
- Layout
- Size
- Paging
- Visualization
- Series Management
- Custom Item
- Custom Legend
- Events
- 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.
Single Series
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 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 settings.
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 it is possible to position the 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 can define the side of the chart it should be bound to, and the alignment:
var legend = chart.legend();
legend.enabled(true);
// set position mode
legend.positionMode("outside");
// set position and alignment
legend.position("bottom");
legend.align("center");
legend.itemsLayout("horizontal-expandable");
Inside
"Inside" position mode is when the legend is placed within a data plot (inner area of a chart). In this mode you can define the side of a data plot it should be bound to, and the alignment:
var legend = chart.legend();
legend.enabled(true);
// set position mode
legend.positionMode("inside");
// set position and alignment
legend.position("top");
legend.align("right");
Drag and Drop
The "Drag and Drop" feature of a legend allows user to move the legend to any position on a chart. Use the drag() method 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 that if the legend's positionMode() is set to Inside - you cannot move it outside of a data plot, and if it is Outside - you cannot 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 the anychart.enums.LegendLayout and they are:
- "horizontal",
- "horizontal-expandable",
- "vertical",
- "vertical-expandable".
The legend layout mode works in conjunction with position and size settings.
Size
Legend size is controlled by the following methods:
Expandable
When the legend layout mode is set to "horizontal-expandable" or "vertical-expandable" it makes sense to use the maxHeight() and the maxWidth() methods, which control the extent to which legend can expand to. It can be set both in pixels and in percent. 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("vertical-expandable");
legend.position("right");
// paginator position
legend.paginator().orientation("bottom");
See how these settings work in the following interactive sample: click buttons to add or remove series and see how the legend and the chart change their sizes. Once the legend reached maximum allowed size, a paginator appears.
Fixed
The height() and width() methods are used to set the fixed size of a legend in pixels or in percent. They override maxHeight() and maxWidth() if both are set simultaneously.
A Pie Chart Sample 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);
Paging
If legend items can't fit into an area, the legend can occupy (this is controlled by size settings) the 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 adjusting 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 it is necessary to tune markers in legend icons, adjust the 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 from anychart.enums.Cursor.
var legend = chart.legend();
legend.hoverCursor("pointer"); // sets hover cursor using a string
Tooltip
If you want to configure legend tooltips - you should do that using the tooltip() method. You can tune its visual appearance and format. In the following sample we format the 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 the 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 the 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 legends at the bottom of the chart.
Events
As an interactive component of a Chart, Legend has some events which can be used for managing and adjusting the Chart and the Legend itself. Look through this section to know all about legend events.
Legend Items Events
Legend items are child elements of a legend, but they have some events which have nothing to do with the whole legend. The list below demonstrates the list of legend items events.
- legendItemClick - Event type for click on item of legend.
- legendItemDblclick - Event type for double click on item of legend.
- legendItemMouseDown - Event type for item of legend at mouse down.
- legendItemMouseMove - Event type for item of legend at mouse moving.
- legendItemMouseOut - Event type for item of legend at mouse leading off.
- legendItemMouseOver - Event type for item of legend at hover mouse.
- legendItemMouseUp - Event type for item of legend at up mouse.
// legend items events adjusting
legend.listen("legendItemMouseDown", function(e){
// stop reacting on this event
e.preventDefault();
});
// set the action to the click event
legend.listen("legendItemСlick", function(e){
var series = chart.getSeriesAt(e.itemIndex);
var selected = !series.meta("selected");
if(selected){
series.select();
} else {
series.unselect();
}
series.meta("selected", selected);
// prevent chart click from happenning
e.stopWrapperPropagation();
});
Legend Events
There are only three events the Legend has:
- drag - Event type for legend moving.
- dragEnd - Event type for legend at the end of moving.
- dragStart - Event type for legend at the start of moving.
// allow drag
legend.drag(true);
// chart title changes on dragging event
legend.listen("drag", function (){
chart.title("Legend is being dragged");
});
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
One legend can be used for several series on different charts. Look through and explore the following sample:
// 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.