Using keys or legends

Introduction

Using a key on your chart allows you to provide information about what the datasets that are displayed on the chart represent.

Keys can be used in two different modes - a horizontal one designed to sit in the margins of the chart, and a vertical one that is designed to sit over the chart.

Key configuration properties

The available key properties and their defaults are listed below (some chart types have slightly different defaults to suit):


PropertyDescriptionDefault
keyAn array of key elements (this is the text that is displayed in the key.[] (An empty array)
keyHalignThe horizontal alignment of the keyright
keyValign[Pie chart only] The vertical alignment of the key. By default this is null but you can set this to center in order to vertically center the key. There's a demo in the download archive that shows this called pie-vertically-centered-key.html This property takes precedence over the keyPositionY property.null
keyPositionThis determines the positioning/layout of the key. Possible values are graph and margin.graph
keyPositionMarginBoxedWhen the key is in margin mode this determines if it sits in a box.false
keyPositionMarginHSpaceWhen the key is in margin mode this adds horizontal space to the key items (ie they're more spaced out). 0
keyPositionGraphBoxedWhen the key is in graph mode this determines if it sits in a box.true
keyPositionXThis allows you to specify an X coordinate for the key.null
keyPositionYThis allows you to specify a Y coordinate for the key.null
keyPositionOffsetxThis allows you to offset the X coordinate for the key by a given amount.null
keyPositionOffsetyThis allows you to offset the Y coordinate for the key by a given amount.null
keyShadowThis controls whether the key has a shadow or not.false
keyShadowOffsetxThis controls the X offset for the shadow.2
keyShadowOffsetyThis controls the Y offset for the shadow.2
keyShadowColorThis controls the color of the shadow.#666
keyShadowBlurThis controls the blur that's applied to the shadow.3
keyColorsIf the calculated colors are not what you want to see - this allows you to specify your own colors.null
keyColorShapeThis is the shape that the color blob takes on.square (can be an array of shapes)
keyBackgroundThe background of the key.white
keyRoundedWhether the corners of the key are square or rounded.true
keyLinewidthThe linewidth used for the key.1
keyLabelsFontThe font used for the key text.[same as the textFont setting]
keyLabelsSizeThe size of the text in the key.[same as the textSize setting]
keyLabelsColorThe color of the text in the key.black
keyLabelsBoldWhether the text in the key is bold or not.false
keyLabelsItalicWhether the text in the key is italic or not.false
keyLabelsOffsetxThe offset that gets applied to the X coordinate to the key text. 0
keyLabelsOffsetyThe offset that gets applied to the Y coordinate to the key text. 0
keyTextAccessibleBy default the key text IS NOT accessible but by using this setting you can override this.null
keyInteractiveWhether the key is interactive or not. Not all chart types support this.false
keyInteractiveHighlightChartFillThe highlight fill color that's used to highlight the chart by the interactive key.rgba(255,255,255,0.7)
keyInteractiveHighlightChartStrokeThe highlight stroke color that's used to highlight the chart by the interactive key.black
keyFormattedDecimalsThis stipulates how many decimals are used in the key labels. Formatted key labels are documented below. 0
keyFormattedPointThe character(s) that's used as the decimal separator in the %{value_formatted} macro. Formatted key labels are documented below..
keyFormattedThousandThe character(s) that's used as the thousand separator in the %{value_formatted} macro. Formatted key labels are documented below.,
keyFormattedUnitsPreThe units to add to the value. These units are positioned before the number. Formatted key labels are documented below.[an empty string]
keyFormattedUnitsPostThe units to add to the value. These units are positioned after the number. Formatted key labels are documented below.[an empty string]
keyFormattedValueSpecificInstead of the key code calculating the value - which might not be what you want in some cases - you can use this property to specify the exact values that you want to be used in the key (this specifies just the values - not the whole string).null
keyFormattedItemsCountYou can use this property to specify the number of key items that should be shown. Normally this is calculated automatically for you.null
key
An array of key elements (this is the text that is displayed in the key.
Default: [] (An empty array)

keyHalign
The horizontal alignment of the key
Default: right

keyValign
[Pie chart only] The vertical alignment of the key. By default this is null but you can set this to center in order to vertically center the key. There's a demo in the download archive that shows this called pie-vertically-centered-key.html This property takes precedence over the keyPositionY property.
Default: null

keyPosition
This determines the positioning/layout of the key. Possible values are graph and margin.
Default: graph

keyPositionMarginBoxed
When the key is in margin mode this determines if it sits in a box.
Default: false

keyPositionMarginHSpace
When the key is in margin mode this adds horizontal space to the key items (ie they're more spaced out).
Default: 0

keyPositionGraphBoxed
When the key is in graph mode this determines if it sits in a box.
Default: true

keyPositionX
This allows you to specify an X coordinate for the key.
Default: null

keyPositionY
This allows you to specify a Y coordinate for the key.
Default: null

keyPositionOffsetx
This allows you to offset the X coordinate for the key by a given amount.
Default: null

keyPositionOffsety
This allows you to offset the Y coordinate for the key by a given amount.
Default: null

keyShadow
This controls whether the key has a shadow or not.
Default: false

keyShadowOffsetx
This controls the X offset for the shadow.
Default: 2

keyShadowOffsety
This controls the Y offset for the shadow.
Default: 2

keyShadowColor
This controls the color of the shadow.
Default: #666

keyShadowBlur
This controls the blur that's applied to the shadow.
Default: 3

keyColors
If the calculated colors are not what you want to see - this allows you to specify your own colors.
Default: null

keyColorShape
This is the shape that the color blob takes on.
Default: square (can be an array of shapes)

keyBackground
The background of the key.
Default: white

keyRounded
Whether the corners of the key are square or rounded.
Default: true

keyLinewidth
The linewidth used for the key.
Default: 1

keyLabelsFont
The font used for the key text.
Default: [same as the textFont setting]

keyLabelsSize
The size of the text in the key.
Default: [same as the textSize setting]

keyLabelsColor
The color of the text in the key.
Default: black

keyLabelsBold
Whether the text in the key is bold or not.
Default: false

keyLabelsItalic
Whether the text in the key is italic or not.
Default: false

keyLabelsOffsetx
The offset that gets applied to the X coordinate to the key text.
Default: 0

keyLabelsOffsety
The offset that gets applied to the Y coordinate to the key text.
Default: 0

keyTextAccessible
By default the key text IS NOT accessible but by using this setting you can override this.
Default: null

keyInteractive
Whether the key is interactive or not. Not all chart types support this.
Default: false

keyInteractiveHighlightChartFill
The highlight fill color that's used to highlight the chart by the interactive key.
Default: rgba(255,255,255,0.7)

keyInteractiveHighlightChartStroke
The highlight stroke color that's used to highlight the chart by the interactive key.
Default: black

keyFormattedDecimals
This stipulates how many decimals are used in the key labels. Formatted key labels are documented below.
Default: 0

keyFormattedPoint
The character(s) that's used as the decimal separator in the %{value_formatted} macro. Formatted key labels are documented below.
Default: .

keyFormattedThousand
The character(s) that's used as the thousand separator in the %{value_formatted} macro. Formatted key labels are documented below.
Default: ,

keyFormattedUnitsPre
The units to add to the value. These units are positioned before the number. Formatted key labels are documented below.
Default: [an empty string]

keyFormattedUnitsPost
The units to add to the value. These units are positioned after the number. Formatted key labels are documented below.
Default: [an empty string]

keyFormattedValueSpecific
Instead of the key code calculating the value - which might not be what you want in some cases - you can use this property to specify the exact values that you want to be used in the key (this specifies just the values - not the whole string).
Default: null

keyFormattedItemsCount
You can use this property to specify the number of key items that should be shown. Normally this is calculated automatically for you.
Default: null

Active key elements

When you hover over or click on a key element/entry then the RGraph registry will hold details of the relevant key entry. So in your event listener, you will be able to determine the key entry like this:

key = RGraph.Registry.get('key-element');

And you could use it like this:

// Assume that the line variable is your line chart object
line.canvas.onmousemove = function (e)
{
    var key = RGraph.Registry.get('key-element');

    if (key) {
        // Log the details of the object to the console
        console.log(key);
    }
};

Using interactive keys on your charts

Note: The interactive key will use standard canvas text for the key - not dom text. You can enable textAccessible if you want but the interactive key will ignore it.

Formerly the interactive key was only implemented for the Line chart and Pie chart. As of mid-2013, however, it was rewritten and is now available with a lot more chart types. The demo pages for the interactive key are available in the download archive.

Having been rewritten the interactive key now uses the drawing api Rect object and the dynamic library:

<script src="RGraph.common.core.js"></script>
<script src="RGraph.common.dynamic.js"></script>
<script src="RGraph.common.key.js"></script>
<script src="RGraph.drawing.rect.js"></script>

<script>
    line = new RGraph.Line({
        id: 'cvs',
        data: [
            [458,435,466,148,396,485,456],
            [153,245,256,33,216,248,344],
            [55,56,43,374,76,78,85]
        ],
        options: {
            textSize: 12,
            marginTop: 45,
            marginLeft: 35,
            marginRight: 35,
            marginBottom: 35,
            marginInner: 15,
            xaxisLabels: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'],
            tickmarksStyle: 'endcircle',
            linewidth: 3,
            xaxisTickmarksStyle: 12,
            spline: true,
            key: ['Rob','Julie','Jack'],
            keyPosition: 'margin',
            keyInteractive: true,
            title: 'A Line chart with interactive key',
            titleSize: 16
        }
    }).draw();
</script>

Formatted key labels

Since version 6.12 you've been able to use formatting macros in your key labels. For example you might want the value as a part of your key labels and this is an easy way to do it. To use the macros you can change your array of key labels to a single string like this:

key: '%{property:labels[%{index}]}: %{value_formatted}'
keyFormattedDecimals: 2
keyFormattedUnitsPre: '£',
// keyFormattedUnitsPost: 'p',
// keyFormattedpoint: '.',
// keyFormattedThousand: ',',
// keyFormattedValueSpecific: null,

What macros are available to use?

HTML keys

In December 2013 a function was added to RGraph that allows you to use an html key next to your chart. This key is made up of div and span tags so you may find it easier to interact with. You can read more about HTML keys on this page.