Examples of using keys or legends in your charts

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

Introduction

[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

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

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

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

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 used to highlight the chart by the interactive key.
Default: rgba(255,255,255,0.7)

keyInteractiveHighlightChartStroke
The highlight stroke color used to highlight the chart by the interactive key.
Default: 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
        $p(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.

[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 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: {
            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
        }
    }).draw();
</script>

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.