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


Layout style:     
  

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 gutter.graph
keyPositionGutterBoxedWhen the key is in gutter 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 an 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
keyTextFontThe font used for the key text.[same as the textFont setting]
keyTextSizeThe size of the text in the key.[same as the textSize setting]
keyTextColorThe color of the text in the key.black
keyTextBoldWhether the text in the key is bold or not.false
keyTextItalicWhether the text in the key is italic or not.false
keyInteractiveWhether the key is interactive or not. Not all chart types support this.false
keyInteractiveHighlightChartFillThe highlight fill color used to higlight the chart by the interactive key.rgba(255,255,255,0.7)
keyInteractiveHighlightChartStrokeThe highlight stroke color used to higlight 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 myLine 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);
    }
});

Interactive keys

Certain chart types (eg Bar, Line, Pie) can be made to have interactive keys. This can make identifying datasets or items illustrated by the key much simpler. There is an example page detailing interactive keys here.

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.