Legend
Overview
The legend helps users better understand a chart by identifying what each series (dataset) represents. ZingChart supports many interactive legend features, including: legend toggling, dragging, minimization, pagination, scrolling, highlighting, sharing, and more. Refer to the Legend JSON page for a full list of objects and attributes.
Setup
Basic chart legend setup includes creating the object, specifying the legend item text, and overall layout and positioning.
Default Legend
To add a legend, create a legend object. The default legend appears like so, with each legend item corresponding to a series from your chart.
{
type: 'line',
legend: {
},
scaleY: {
values: '0:300:50',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9,154.7,105.2,136.3,180.4,150.5,135.3,130.5,164.3,110.5,127.2,183.9,191.3]
},
{
values: [184.8,165.8,122.4,196.6,179.1,116.4,175.9,137.8,120.9,177.3,122.5,123.1,131.7,109.4,167.2,142.7,140.7,165.5,148.1,181.9]
},
{
values: [108.7,132.9,161.6,192.1,134.5,149.4,183.9,124.4,114.5,121.9,149.7,124.3,199.3,151.4,112.5,113.5,165.6,139.5,194.6,184.4]
},
{
values: [113.2,165.6,139.5,194.6,184.4,179.2,173.1,133.7,190.5,128.9,169.3,108.5,124.3,135.1,122.5,125.7,157.6,138.1,162.8,112.6]
},
{
values: [136.6,160.8,155.2,158.7,119.1,192.4,164.8,151.4,125.1,106.9,103.2,158.6,100.7,137.2,108.1,162.7,192.8,149.2,142.8,134.3]
}
]
}
Text
Specify the text you want to appear for each legend item by adding a text attribute to each series object. (Without the text attribute, the legend item displays the series number of each dataset by default, as seen in the above chart.)
{
type: 'line',
legend: {
},
plot: {
tooltip: {
text: '%t<br>%v'
}
},
scaleY: {
values: '0:300:50',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9,154.7,105.2,136.3,180.4,150.5,135.3,130.5,164.3,110.5,127.2,183.9,191.3],
text: 'Test 1-001A3'
},
{
values: [184.8,165.8,122.4,196.6,179.1,116.4,175.9,137.8,120.9,177.3,122.5,123.1,131.7,109.4,167.2,142.7,140.7,165.5,148.1,181.9],
text: 'Test 2-002B4'
},
{
values: [108.7,132.9,161.6,192.1,134.5,149.4,183.9,124.4,114.5,121.9,149.7,124.3,199.3,151.4,112.5,113.5,165.6,139.5,194.6,184.4],
text: 'Test 3-004C3'
},
{
values: [113.2,165.6,139.5,194.6,184.4,179.2,173.1,133.7,190.5,128.9,169.3,108.5,124.3,135.1,122.5,125.7,157.6,138.1,162.8,112.6],
text: 'Test 4-004D1'
},
{
values: [136.6,160.8,155.2,158.7,119.1,192.4,164.8,151.4,125.1,106.9,103.2,158.6,100.7,137.2,108.1,162.7,192.8,149.2,142.8,134.3],
text: 'Test 5-034CE'
}
]
}
Alternatively, you can use the legend-text attribute in each series object to specify the legend item text. This method is useful when you want to differentiate the node text from the legend item text, such as using shorthand or abbreviated names. See the following chart.
{
type: 'line',
legend: {
},
plot: {
tooltip: {
text: '%t<br>%v'
}
},
scaleY: {
values: '0:300:50',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9,154.7,105.2,136.3,180.4,150.5,135.3,130.5,164.3,110.5,127.2,183.9,191.3],
text: 'Test 1-001A3',
legendText: 'Test 1'
},
{
values: [184.8,165.8,122.4,196.6,179.1,116.4,175.9,137.8,120.9,177.3,122.5,123.1,131.7,109.4,167.2,142.7,140.7,165.5,148.1,181.9],
text: 'Test 2-002B4',
legendText: 'Test 2'
},
{
values: [108.7,132.9,161.6,192.1,134.5,149.4,183.9,124.4,114.5,121.9,149.7,124.3,199.3,151.4,112.5,113.5,165.6,139.5,194.6,184.4],
text: 'Test 3-004C3',
legendText: 'Test 3'
},
{
values: [113.2,165.6,139.5,194.6,184.4,179.2,173.1,133.7,190.5,128.9,169.3,108.5,124.3,135.1,122.5,125.7,157.6,138.1,162.8,112.6],
text: 'Test 4-004D1',
legendText: 'Test 4'
},
{
values: [136.6,160.8,155.2,158.7,119.1,192.4,164.8,151.4,125.1,106.9,103.2,158.6,100.7,137.2,108.1,162.7,192.8,149.2,142.8,134.3],
text: 'Test 5-034CE',
legendText: 'Test 5'
}
]
}
Layout and Positioning
You can customize the layout and positioning of the legend. For legend layout, use the layout attribute to specify how many columns and rows the legend items should be organized into (e.g., 1x5 would equal one row with five columns). For legend positioning, you can use the align (left, center, right) and vertical-align (top, middle, bottom) attributes for automatic legend alignment and adjustment of the plot area margins. Alternatively, you can use the x and/or yattributes (provide percentage or pixel values) to position the legend, and then use margin attributes (see the Plotarea JSON page) in the plotarea object to position the plot area.
{
type: 'line',
legend: {
layout: '1x5', //row x column
x: '20%',
y: '8%',
},
plotarea: {
marginBottom: '15%',
marginTop: '25%'
},
scaleY: {
values: '0:300:50',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9,154.7,105.2,136.3,180.4,150.5,135.3,130.5,164.3,110.5,127.2,183.9,191.3],
text: 'Test 1'
},
{
values: [184.8,165.8,122.4,196.6,179.1,116.4,175.9,137.8,120.9,177.3,122.5,123.1,131.7,109.4,167.2,142.7,140.7,165.5,148.1,181.9],
text: 'Test 2'
},
{
values: [108.7,132.9,161.6,192.1,134.5,149.4,183.9,124.4,114.5,121.9,149.7,124.3,199.3,151.4,112.5,113.5,165.6,139.5,194.6,184.4],
text: 'Test 3'
},
{
values: [113.2,165.6,139.5,194.6,184.4,179.2,173.1,133.7,190.5,128.9,169.3,108.5,124.3,135.1,122.5,125.7,157.6,138.1,162.8,112.6],
text: 'Test 4'
},
{
values: [136.6,160.8,155.2,158.7,119.1,192.4,164.8,151.4,125.1,106.9,103.2,158.6,100.7,137.2,108.1,162.7,192.8,149.2,142.8,134.3],
text: 'Test 5'
}
]
}
Top Layer
By default, when crosshair(s) and legend are both enabled the crosshairs are painted over the legend.
To have the crosshair lines appear behind the legend, set the topLayer attribute to 'legend'.
{
type: 'bar',
topLayer: 'legend',
...
}
Legend Elements
The legend consists of multiple elements (or parts) that can be customized to meet your charting needs. Refer to the Legend JSON page for a full list of objects and attributes.
Legend Object
Use the legend object to style and control the overall legend container. Refer to the Legend Object JSON page for a full attribute list.
{
type: 'area',
title: {
text: 'Legend Object'
},
legend: {
backgroundColor: '#ffe6e6',
borderWidth: '2px',
borderColor: 'red',
borderRadius: '5px',
padding: '10%',
layout: '5x1',
x: '82%',
y: '25%',
},
plot: {
aspect: 'spline',
stacked: true,
marker: {
visible: false
}
},
plotarea: {
marginRight: '25%',
},
scaleY: {
values: '0:1000:200',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9],
text: 'Test 1'
},
{
values: [84.8,65.8,122.4,96.6,279.1,56.4,275.9,237.8],
text: 'Test 2'
},
{
values: [108.7,132.9,61.6,192.1,134.5,349.4,183.9,224.4],
text: 'Test 3'
},
{
values: [213.2,65.6,139.5,194.6,184.4,79.2,73.1,33.7],
text: 'Test 4'
},
{
values: [236.6,260.8,155.2,58.7,119.1,192.4,164.8,51.4],
text: 'Test 5'
}
]
}
Legend Items
Use the item and item-off objects to style the legend text. You can customize the font, background, and borders. Refer to the Legend Item and Legend Item-Off JSON pages for a full list of attributes.
{
type: 'area',
title: {
text: 'Legend Items'
},
subtitle: {
text: 'item object in legend',
fontWeight: 'normal'
},
legend: {
item: {
backgroundColor: '#ffe6e6',
fontColor: 'red',
fontFamily: 'Georgia',
borderWidth: '1px',
borderColor: 'red',
borderRadius: '5px'
},
layout: '5x1',
x: '82%',
y: '25%',
},
plot: {
aspect: 'spline',
stacked: true,
marker: {
visible: false
}
},
plotarea: {
marginRight: '25%',
},
scaleY: {
values: '0:1000:200',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9],
text: 'Test 1'
},
{
values: [84.8,65.8,122.4,96.6,279.1,56.4,275.9,237.8],
text: 'Test 2'
},
{
values: [108.7,132.9,61.6,192.1,134.5,349.4,183.9,224.4],
text: 'Test 3'
},
{
values: [213.2,65.6,139.5,194.6,184.4,79.2,73.1,33.7],
text: 'Test 4'
},
{
values: [236.6,260.8,155.2,58.7,119.1,192.4,164.8,51.4],
text: 'Test 5'
}
]
}
Alternatively, you can use the legend-item object in the plot and/or series objects to set the styling. This option is especially useful when you want to apply series-specific styling. See the following chart, and refer to the Legend-Item JSON page for a full attribute list.
{
type: 'area',
title: {
text: 'Legend Items'
},
subtitle: {
text: 'legend-item object in plot/series',
fontWeight: 'normal'
},
legend: {
layout: '5x1',
x: '82%',
y: '25%',
},
plot: {
aspect: 'spline',
stacked: true,
marker: {
visible: false
},
legendItem: {
fontFamily: 'Georgia'
}
},
plotarea: {
marginRight: '25%',
},
scaleY: {
values: '0:1000:200',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9],
text: 'Test 1',
legendItem: {
fontColor: '#29A2CC',
backgroundColor: '#eaf7fb'
}
},
{
values: [84.8,65.8,122.4,96.6,279.1,56.4,275.9,237.8],
text: 'Test 2',
legendItem: {
fontColor: '#D31E1E',
backgroundColor: '#fce9e9'
}
},
{
values: [108.7,132.9,61.6,192.1,134.5,349.4,183.9,224.4],
text: 'Test 3',
legendItem: {
fontColor: '#7CA82B',
backgroundColor: '#f5faeb'
}
},
{
values: [213.2,65.6,139.5,194.6,184.4,79.2,73.1,33.7],
text: 'Test 4',
legendItem: {
fontColor: '#EF8535',
backgroundColor: '#fdf1e7'
}
},
{
values: [236.6,260.8,155.2,58.7,119.1,192.4,164.8,51.4],
text: 'Test 5',
legendItem: {
fontColor: '#A14BC9',
backgroundColor: '#f5ebf9'
}
}
]
}
Legend Markers
Use the marker object to style the legend markers. You can change the marker type, size, color, and more. Refer to the Legend Markers JSON page for a full attribute list.
{
type: 'area',
title: {
text: 'Legend Markers'
},
subtitle: {
text: 'marker object in legend',
fontWeight: 'normal'
},
legend: {
marker: {
backgroundColor: '#ffe6e6',
borderWidth: '1px',
borderColor: 'red',
type: 'circle',
showLine: true,
lineColor: 'red'
},
layout: '5x1',
x: '82%',
y: '25%',
},
plot: {
aspect: 'spline',
stacked: true,
marker: {
visible: false
}
},
plotarea: {
marginRight: '25%',
},
scaleY: {
values: '0:1000:200',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9],
text: 'Test 1'
},
{
values: [84.8,65.8,122.4,96.6,279.1,56.4,275.9,237.8],
text: 'Test 2'
},
{
values: [108.7,132.9,61.6,192.1,134.5,349.4,183.9,224.4],
text: 'Test 3'
},
{
values: [213.2,65.6,139.5,194.6,184.4,79.2,73.1,33.7],
text: 'Test 4'
},
{
values: [236.6,260.8,155.2,58.7,119.1,192.4,164.8,51.4],
text: 'Test 5'
}
]
}
Alternatively, you can use the legend-marker object in the plot and/or series objects to set the styling. This option is especially useful when you want to apply series-specific styling. See the following chart, and refer to the Legend-Marker JSON page for a full attribute list.
{
type: 'area',
title: {
text: 'Legend Markers'
},
subtitle: {
text: 'legend-marker object in plot/series',
fontWeight: 'normal'
},
legend: {
layout: '5x1',
x: '82%',
y: '25%',
},
plot: {
aspect: 'spline',
stacked: true,
marker: {
visible: false
},
legendMarker: {
showLine: true,
}
},
plotarea: {
marginRight: '25%',
},
scaleY: {
values: '0:1000:200',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9],
text: 'Test 1',
legendMarker: {
type: 'square',
backgroundColor: '#eaf7fb',
borderColor: '#29A2CC',
borderWidth: '2px'
}
},
{
values: [84.8,65.8,122.4,96.6,279.1,56.4,275.9,237.8],
text: 'Test 2',
legendMarker: {
type: 'circle',
backgroundColor: '#fce9e9',
borderColor: '#D31E1E',
borderWidth: '2px'
}
},
{
values: [108.7,132.9,61.6,192.1,134.5,349.4,183.9,224.4],
text: 'Test 3',
legendMarker: {
type: 'diamond',
backgroundColor: '#f5faeb',
borderColor: '#7CA82B',
borderWidth: '2px'
}
},
{
values: [213.2,65.6,139.5,194.6,184.4,79.2,73.1,33.7],
text: 'Test 4',
legendMarker: {
type: 'star5',
backgroundColor: '#fdf1e7',
borderColor: '#EF8535',
borderWidth: '2px'
}
},
{
values: [236.6,260.8,155.2,58.7,119.1,192.4,164.8,51.4],
text: 'Test 5',
legendMarker: {
type: 'rpoly5',
backgroundColor: '#f5ebf9',
borderColor: '#A14BC9',
borderWidth: '2px'
}
}
]
}
Header
Use the header object to add and style the legend header. Add a text attribute to specify the text you want displayed. Refer to the Legend Header JSON page for a full attribute list.
{
type: 'area',
title: {
text: 'Legend Header'
},
legend: {
header: {
text: 'Header',
backgroundColor: '#ffe6e6',
borderLeft: '2px solid red',
borderRight: '2px solid red',
borderTop: '2px solid red',
borderBottom: '2px solid red'
},
layout: '5x1',
x: '82%',
y: '25%',
},
plot: {
aspect: 'spline',
stacked: true,
marker: {
visible: false
}
},
plotarea: {
marginRight: '25%',
},
scaleY: {
values: '0:1000:200',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9],
text: 'Test 1'
},
{
values: [84.8,65.8,122.4,96.6,279.1,56.4,275.9,237.8],
text: 'Test 2'
},
{
values: [108.7,132.9,61.6,192.1,134.5,349.4,183.9,224.4],
text: 'Test 3'
},
{
values: [213.2,65.6,139.5,194.6,184.4,79.2,73.1,33.7],
text: 'Test 4'
},
{
values: [236.6,260.8,155.2,58.7,119.1,192.4,164.8,51.4],
text: 'Test 5'
}
]
}
Footer
Use the footer object to add and style the legend footer. Add a text attribute to specify the text you want displayed. Refer to the Legend Footer JSON page for a full attribute list.
{
type: 'area',
title: {
text: 'Legend Footer'
},
legend: {
footer: {
text: 'Footer',
backgroundColor: '#ffe6e6',
borderLeft: '2px solid red',
borderRight: '2px solid red',
borderTop: '2px solid red',
borderBottom: '2px solid red'
},
layout: '5x1',
x: '82%',
y: '25%',
},
plot: {
aspect: 'spline',
stacked: true,
marker: {
visible: false
}
},
plotarea: {
marginRight: '25%',
},
scaleY: {
values: '0:1000:200',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9],
text: 'Test 1'
},
{
values: [84.8,65.8,122.4,96.6,279.1,56.4,275.9,237.8],
text: 'Test 2'
},
{
values: [108.7,132.9,61.6,192.1,134.5,349.4,183.9,224.4],
text: 'Test 3'
},
{
values: [213.2,65.6,139.5,194.6,184.4,79.2,73.1,33.7],
text: 'Test 4'
},
{
values: [236.6,260.8,155.2,58.7,119.1,192.4,164.8,51.4],
text: 'Test 5'
}
]
}
Tooltips
Use the tooltip object to add and style the legend tooltips. These are labels that appear when the user hovers over the legend items. Refer to the Legend Tooltips JSON page for a full attribute list. The following tokens can be used with legend tooltips:
| Token | Description |
|---|---|
| %plot-description | The description of the current plot, pulled from the description attribute in the plot/series object. |
| %plot-text %t | The text of the current plot, pulled from the text attribute in the plot/series object. |
The following chart demonstrates how tokens can be used with the legend tooltips.
{
type: 'area',
title: {
text: 'Legend Tooltips'
},
subtitle: {
text: 'Hover over the legend items.',
fontWeight: 'normal'
},
legend: {
tooltip: {
text: '%t was performed by %plot-description.',
backgroundColor: '#ffe6e6',
fontColor: 'red',
fontFamily: 'Georgia',
borderWidth: '1px',
borderColor: 'red',
borderRadius: '5px'
},
layout: '5x1',
x: '82%',
y: '25%',
},
plot: {
aspect: 'spline',
stacked: true,
marker: {
visible: false
}
},
plotarea: {
marginRight: '25%',
},
scaleY: {
values: '0:1000:200',
guide: {
lineStyle: 'dotted'
}
},
series: [
{
values: [138.6,196.3,153.6,127.4,114.1,181.4,131.5,170.9],
text: 'Test 1',
description: 'Dr. Abel'
},
{
values: [84.8,65.8,122.4,96.6,279.1,56.4,275.9,237.8],
text: 'Test 2',
description: 'Dr. Bernard'
},
{
values: [108.7,132.9,61.6,192.1,134.5,349.4,183.9,224.4],
text: 'Test 3',
description: 'Dr. Chang'
},
{
values: [213.2,65.6,139.5,194.6,184.4,79.2,73.1,33.7],
text: 'Test 4',
description: 'Dr. Diaz'
},
{
values: [236.6,260.8,155.2,58.7,119.1,192.4,164.8,51.4],
text: 'Test 5',
description: 'Dr. Eugene'
}
]
}
Interactive Features
ZingChart supports many interactive legend features, including: legend toggling, dragging, minimization, pagination, scrolling, highlighting, sharing, and more.
Legend Toggling
You can set what happens when the user clicks a legend item/marker. Add a toggle-action attribute to the legend object, and provide one of the following values:
hide(default): hides the selected noderemove: repaints the chart without the selected series (can be used with animation)disabled: disables legend togglingnone: disables legend toggling but fires the event
Tip: To apply the toggling effect to all the _un_selected nodes, press the Shift key and click the legend item/marker. Note that this feature is currently available for desktop/laptop users only.
In the following chart, the toggle setting is set to remove, and so the chart is repainted without the selected node each time the user clicks on a legend item/marker. You can also incorporate animation with this setting. See the following chart.
{
type: 'pie',
title: {
text: 'Legend Toggling'
},
subtitle: {
text: 'Click the legend items or markers.',
fontWeight: 'normal'
},
legend: {
toggleAction: 'remove', //'hide' (default), 'remove', or 'disabled'
x: '75%',
y: '25%'
},
plotarea: {
marginRight: '30%',
marginTop: '15%'
},
plot: {
valueBox: {
fontSize: 11,
fontWeight: 'normal',
offsetR: '50%'
}
},
series: [
{ values: [234]},
{ values: [121]},
{ values: [77]},
{ values: [65]},
{ values: [59]},
{ values: [35]},
{ values: [34]},
{ values: [31]},
{ values: [16]},
{ values: [14]}
]
}
To incorporate legend toggling animation, first make sure the toggle-action attribute is set to remove in the legend object. Next, create an animation object in the plot object. Add the following attributes:
on-legend-toggleattribute, and set the value totrueeffectattributemethodattributesequenceattributespeedattribute
Refer to the Animation Tutorial and Animation JSON page for information and demos on the different animation effects, methods, sequences, and speeds.
{
type: 'pie',
title: {
text: 'Legend Toggling with Animation'
},
subtitle: {
text: 'Reload the chart to view animation.',
fontWeight: 'normal'
},
legend: {
toggleAction: 'remove', //to enable toggling animation
x: '75%',
y: '25%'
},
plotarea: {
marginRight: '30%',
marginTop: '15%'
},
plot: {
animation: {
onLegendToggle: true, //to enable toggling animation
effect: 2, //the animation effect
method: 0, //how the animation behaves
sequence: 1, //the order of the animation
speed: 1000 //the animation speed, in milliseconds
},
valueBox: {
fontSize: 11,
fontWeight: 'normal',
offsetR: '60%'
}
},
series: [
{ values: [234]},
{ values: [121]},
{ values: [77]},
{ values: [65]},
{ values: [59]},
{ values: [35]},
{ values: [34]},
{ values: [31]},
{ values: [16]},
{ values: [14]}
]
}
The toggle-action attribute can also be applied to the item and/or marker object(s). This option is useful when you want to restrict legend toggling to just the items or markers. See the following chart.
{
type: 'pie',
title: {
text: 'Legend Toggling'
},
subtitle: {
text: 'Click the legend markers (set to hide). (The legend items are set to disabled.)',
fontWeight: 'normal'
},
legend: {
marker: {
toggleAction: 'hide'
},
item: {
toggleAction: 'disabled'
},
x: '75%',
y: '25%'
},
plotarea: {
marginRight: '30%',
marginTop: '15%'
},
plot: {
valueBox: {
fontSize: 11,
fontWeight: 'normal',
offsetR: '50%'
}
},
series: [
{ values: [234]},
{ values: [121]},
{ values: [77]},
{ values: [65]},
{ values: [59]},
{ values: [35]},
{ values: [34]},
{ values: [31]},
{ values: [16]},
{ values: [14]}
]
}
Legend Dragging
The legend can be dragged by the header or with a dragging icon. To enable legend dragging, you need to:
- Add a
draggableattribute, and set the value totrue. - Add a
drag-handlerattribute, and set the value toheaderoricon.
Use the header object to style the legend header. Use the icon object to style the dragging icon. Refer to the Legend Header and Legend Icon JSON pages for a full attribute list.
{
type: 'pie',
title: {
text: 'Legend Dragging'
},
subtitle: {
text: 'Drag the legend around the chart area.',
fontWeight: 'normal'
},
legend: {
draggable: true, //automatically adds header
dragHandler: 'icon', //'header' (default) or 'icon'
icon: {
lineColor: 'red'
},
header: {
backgroundColor: '#ffe6e6',
borderLeft: '1px solid red',
borderRight: '1px solid red',
borderTop: '1px solid red',
borderBottom: '1px solid red'
},
x: '75%',
y: '25%'
},
plotarea: {
marginRight: '30%',
marginTop: '15%'
},
plot: {
valueBox: {
fontSize: 11,
fontWeight: 'normal',
offsetR: '50%'
}
},
series: [
{ values: [234]},
{ values: [121]},
{ values: [77]},
{ values: [65]},
{ values: [59]},
{ values: [35]},
{ values: [34]},
{ values: [31]},
{ values: [16]},
{ values: [14]}
]
}
Legend Minimization
To enable legend minimization, add a minimize attribute to the legend object, and set the value to true. Use the icon object to style the minimizing icon. Refer to the Legend Icon JSON page for a full attribute list.
{
type: 'pie',
title: {
text: 'Legend Minimization'
},
subtitle: {
text: 'Minimize the legend.',
fontWeight: 'normal'
},
legend: {
minimize: true, //automatically adds header
icon: {
lineColor: 'red'
},
header: {
backgroundColor: '#ffe6e6',
borderLeft: '1px solid red',
borderRight: '1px solid red',
borderTop: '1px solid red',
borderBottom: '1px solid red'
},
x: '75%',
y: '25%'
},
plotarea: {
marginRight: '30%',
marginTop: '15%'
},
plot: {
valueBox: {
fontSize: 11,
fontWeight: 'normal',
offsetR: '50%'
}
},
series: [
{ values: [234]},
{ values: [121]},
{ values: [77]},
{ values: [65]},
{ values: [59]},
{ values: [35]},
{ values: [34]},
{ values: [31]},
{ values: [16]},
{ values: [14]}
]
}
Legend Pagination
To enable legend pagination, you need to:
- Add a
max-itemsattribute, and specify the maximum number of legend items you want displayed. - Add an
overflowattribute, and set the value topage.
You can style the paging arrows and pagination status text with the page-on, page-off, and page-status objects. Refer to the Legend Page-On, Legend Page-Off, and/or Legend Page-Status JSON pages for a full list of attributes.
{
type: 'pie',
title: {
text: 'Legend Pagination'
},
legend: {
maxItems: 5,
overflow: 'page',
pageOn: {
backgroundColor: 'red',
borderWidth: '1px',
borderColor: 'red'
},
pageOff: {
backgroundColor: '#ffe6e6',
borderWidth: '1px',
borderColor: 'red'
},
pageStatus: {
fontColor: 'red',
fontSize: 11,
fontFamily: 'Georgia',
backgroundColor: '#ffe6e6',
},
x: '75%',
y: '25%'
},
plotarea: {
marginRight: '30%',
marginTop: '15%'
},
plot: {
valueBox: {
fontSize: 11,
fontWeight: 'normal',
offsetR: '50%'
}
},
series: [
{ values: [234]},
{ values: [121]},
{ values: [77]},
{ values: [65]},
{ values: [59]},
{ values: [35]},
{ values: [34]},
{ values: [31]},
{ values: [16]},
{ values: [14]},
{ values: [13]},
{ values: [12]},
{ values: [11]},
{ values: [10]},
{ values: [9]}
]
}
Legend Scrolling
To enable legend scrolling, you need to:
- Add a
max-itemsattribute, and specify the maximum number of legend items you want displayed. - Add an
overflowattribute, and set the value toscroll.
You can style the scroll bar and handle with the bar and handle objects. Refer to the Legend Scroll Bar and Legend Scroll Handle JSON pages for a full list of attributes.
{
type: 'pie',
title: {
text: 'Legend Scrolling'
},
legend: {
maxItems: 5,
overflow: 'scroll',
scroll: {
bar: {
backgroundColor: '#ffe6e6',
borderLeft: '1px solid red',
borderRight: '1px solid red',
borderTop: '1px solid red',
borderBottom: '1px solid red',
},
handle: {
backgroundColor: '#ffe6e6',
borderLeft: '2px solid red',
borderRight: '2px solid red',
borderTop: '2px solid red',
borderBottom: '2px solid red',
borderRadius: '15px'
}
},
x: '75%',
y: '25%'
},
plotarea: {
marginRight: '30%',
marginTop: '15%'
},
plot: {
valueBox: {
fontSize: 11,
fontWeight: 'normal',
offsetR: '50%'
}
},
series: [
{ values: [234]},
{ values: [121]},
{ values: [77]},
{ values: [65]},
{ values: [59]},
{ values: [35]},
{ values: [34]},
{ values: [31]},
{ values: [16]},
{ values: [14]},
{ values: [13]},
{ values: [12]},
{ values: [11]},
{ values: [10]},
{ values: [9]}
]
}
Legend Highlight
To enable legend highlighting, you need to:
- Add a
highlight-plotattribute, and set the value totrue. - Alternatively: add a
highlightattribute to theplotobject, and set the value totrue.
Use the highlight-state and/or highlight-marker objects in the plot object to style how the highlighted legend items appear. Refer to the Legend Highlight State and Legend Highlight Marker JSON pages for a full list of styling attributes.
{
type: 'ring',
title: {
text: 'Legend Highlight'
},
subtitle: {
text: 'Hover over the legend items to highlight the corresponding nodes.',
fontWeight: 'normal'
},
legend: {
highlightPlot: true,
x: '75%',
y: '25%'
},
plotarea: {
marginRight: '30%',
marginTop: '15%'
},
plot: {
highlightState: {
backgroundColor: 'red #ffe6e6',
borderWidth: '1px',
borderColor: 'red',
lineStyle: 'dotted'
},
slice: '50%',
valueBox: {
placement: 'out',
fontColor: 'black',
fontSize: 11,
fontWeight: 'normal'
}
},
series: [
{ values: [234]},
{ values: [121]},
{ values: [77]},
{ values: [65]},
{ values: [59]},
{ values: [35]},
{ values: [34]},
{ values: [31]},
{ values: [16]},
{ values: [14]}
]
}
Shared Legends
To enabled legend sharing between two or more charts, you need to:
- Add a
sharedattribute to each chart'slegendobject, and set the value totrue. - Style the last
legendobject (andlegend-itemand/orlegend-markerobject(s) in plot/series, if applicable), which will apply across all shared charts.
See the following chart, where a shared attribute was added to all three pie charts. The legend positioning and styling was set in the final chart object. For more information on using the graphset array and shared interactions between two or more charts, refer to our documentation on Adding Additional Charts and Shared Interactions.
{
graphset: [
{
labels: [
{
text: 'Shared Legend',
fontSize: 20,
fontWeight: 'bold',
height: '20%',
width: '100%',
x: '40%',
y: '20%'
}
]
},
{ //Chart 1
type: 'ring',
legend: {
shared: true
},
height: '90%',
width: '33%',
x: '0%',
y: '10%',
plot: {
valueBox: {
fontSize: 12
}
},
series: [
{
values: [35],
text: 'Blue Series'
},
{
values: [34],
text: 'Red Series'
},
{
values: [31],
text: 'Green Series'
}
]
},
{ //Chart 2
type: 'ring',
legend: {
shared: true
},
height: '90%',
width: '33%',
x: '33%',
y: '10%',
plot: {
valueBox: {
fontSize: 12
}
},
series: [
{
values: [65],
text: 'Blue Series'
},
{
values: [30],
text: 'Red Series'
},
{
values: [16],
text: 'Green Series'
}
]
},
{ //Chart 3
type: 'ring',
legend: {
shared: true,
x: '65%',
y: '10%',
backgroundColor: '#f2f2f2',
borderWidth: '1px',
borderColor: '#cccccc',
borderRadius: '3px',
item: {
fontFamily: 'Georgia',
borderRadius: '3px'
},
marker: {
type: 'circle',
size: 3
}
},
height: '90%',
width: '33%',
x: '66%',
y: '10%',
plot: {
valueBox: {
fontSize: 12
}
},
series: [
{
values: [59],
text: 'Blue Series',
legendItem: {
backgroundColor: '#29A2CC',
fontColor: '#eaf7fb'
},
legendMarker: {
borderColor: '#29A2CC',
backgroundColor: '#eaf7fb'
}
},
{
values: [49],
text: 'Red Series',
legendItem: {
backgroundColor: '#D31E1E',
fontColor: '#fce9e9'
},
legendMarker: {
borderColor: '#D31E1E',
backgroundColor: '#fce9e9'
}
},
{
values: [31],
text: 'Green Series',
legendItem: {
backgroundColor: '#7CA82B',
fontColor: '#f5faeb'
},
legendMarker: {
borderColor: '#7CA82B',
backgroundColor: '#f5faeb'
}
}
]
}
]
}
Bubble Legend Module
Use the bubble-legend module to display an appropriate legend for bubble charts. Refer to the Legend Object JSON page for a full attribute list.
Bubble Legend Usage
To use the bubble-legend module, you first need to load the module using zingchart.loadModules(). Refer to the ZingChart Modules documentation for more information on how to load a module for usage.
Once the module is loaded, add a bubbleLegend object to the root of your chart object.
Bubble Legend Options
There are multiple configuration options for the bubble legend object. Refer to the Legend Object JSON page for a full attribute list.
| Value | Description |
|---|---|
| connector | Formats the display of the line connectors between the bubbles on the legend |
| item | Formats the display of the numbers on the legend |
| layout | Sets the layout of the bubble legend to be horizontal ('h') or vertical ('v') |
| margin | Sets the margin of the bubble legend |
| marker | Formats the display of the bubble markers the legend |
| padding | Sets the padding between legend objects |
{
type: 'bubble',
title: {
text: 'Bubble Legend',
},
bubbleLegend: {
layout: 'v',
marker: {},
connector: {},
item: {}
},
plotarea: {
margin: '90px 100px 50px 50px',
alpha: 0.3,
backgroundColor: '#fff'
},
scaleY: {
values: '0:20:5'
},
tooltip: {
text: 'Y-Axis Value: %v0<br>X-Axis Value: %v1<br>Bubble Size: %v2',
textAlign: 'left'
},
series: chartData
}
Summary
ZingChart legends are completely customizable. Not only can you label the different series in your chart, showing your users the information they need to know in order to read your chart. You can style the legend as well as the individual legend item and add click-to-hide toggling, scrolling, or paging. For bubble charts, you can use the bubble legend module.
For a full list of legend attributes, see the JSON configuration page.