Examples of using keys or legends in your charts

Documentation about using keys in your charts. Keys can be used when you have (for example) multiple sets of data that need to be identified. Interactive keys can enhance this further


[No canvas support]
[No canvas support]
[No canvas support]

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):

Key properties

keyAn array of key elements (this is the text that is displayed in the key.[] (An empty array)
keyHalignThe horizontal alignment of the keyright
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
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
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 used to highlight the chart by the interactive key.rgba(255,255,255,0.7)
keyInteractiveHighlightChartStrokeThe highlight stroke color used to highlight the chart by the interactive key.black

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:

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

And you could use it like this:

// Assume that the myLine variable is your line chart object
$(myLine.canvas).on('mousemove', function (e)
    var key = RGraph.Registry.get('key-element');

    if (key) {
        // alert() the details of the object

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.

[No canvas support]

Formerly the interactive key was only implemented for the Line and Pie charts. As of mid-2013, however, it was rewritten and it's now available with the following chart types. The types are linked to demo pages each of which are included in the download archive.

You can view demos of each by looking through the demo area. 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>

    line = new RGraph.Line({
        id: 'cvs',
        data: [
        options: {
            xaxisLabels: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'],
            tickmarksStyle: 'endcircle',
            linewidth: 3,
            xaxisTickmarksCount: 12,
            spline: true,
            key: ['Rob','Julie','Jack'],
            keyPosition: 'margin',
            keyInteractive: true,
            textSize: 14

HTML keys

In December 2013 a function was added to RGraph that allows you to use a HTML based 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.