About
RGraph is a JavaScript charts library based on HTML5 SVG and canvas. RGraph is mature (over 15 years old) and has a wealth of features making it an ideal choice to use for showing charts on your website.

More »

 

Download
Get the latest version of RGraph (version 6.18, 1st June 2024) from the download page. You can read the changelog here. There's also older versions available, minified files and links to cdnjs.com hosted libraries.

More »

 

License
RGraph can be used for free under the GPL or if that doesn't suit your situation there's an inexpensive (£129) commercial license available.

More »

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


Name: key
Description: 
An array of key elements (this is the text that is displayed in the key.
Default: [] (An empty array)
Name: keyHalign
Description: 
The horizontal alignment of the key
Default: right
Name: keyValign
Description: 
[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
Name: keyPosition
Description: 
This determines the positioning/layout of the key. Possible values are graph and margin.
Default: graph
Name: keyPositionMarginBoxed
Description: 
When the key is in margin mode this determines if it sits in a box.
Default: false
Name: keyPositionMarginHSpace
Description: 
When the key is in margin mode this adds horizontal space to the key items (ie they're more spaced out).
Default:  0
Name: keyPositionGraphBoxed
Description: 
When the key is in graph mode this determines if it sits in a box.
Default: true
Name: keyPositionX
Description: 
This allows you to specify an X coordinate for the key.
Default: null
Name: keyPositionY
Description: 
This allows you to specify a Y coordinate for the key.
Default: null
Name: keyPositionOffsetx
Description: 
This allows you to offset the X coordinate for the key by a given amount.
Default: null
Name: keyPositionOffsety
Description: 
This allows you to offset the Y coordinate for the key by a given amount.
Default: null
Name: keyShadow
Description: 
This controls whether the key has a shadow or not.
Default: false
Name: keyShadowOffsetx
Description: 
This controls the X offset for the shadow.
Default: 2
Name: keyShadowOffsety
Description: 
This controls the Y offset for the shadow.
Default: 2
Name: keyShadowColor
Description: 
This controls the color of the shadow.
Default: #666
Name: keyShadowBlur
Description: 
This controls the blur that's applied to the shadow.
Default: 3
Name: keyColors
Description: 
If the calculated colors are not what you want to see - this allows you to specify your own colors.
Default: null
Name: keyColorShape
Description: 
This is the shape that the color blob takes on.
Default: square (can be an array of shapes)
Name: keyBackground
Description: 
The background of the key.
Default: white
Name: keyRounded
Description: 
Whether the corners of the key are square or rounded.
Default: true
Name: keyLinewidth
Description: 
The linewidth used for the key.
Default: 1
Name: keyLabelsFont
Description: 
The font used for the key text.
Default: [same as the textFont setting]
Name: keyLabelsSize
Description: 
The size of the text in the key.
Default: [same as the textSize setting]
Name: keyLabelsColor
Description: 
The color of the text in the key.
Default: black
Name: keyLabelsBold
Description: 
Whether the text in the key is bold or not.
Default: false
Name: keyLabelsItalic
Description: 
Whether the text in the key is italic or not.
Default: false
Name: keyLabelsOffsetx
Description: 
The offset that gets applied to the X coordinate to the key text.
Default:  0
Name: keyLabelsOffsety
Description: 
The offset that gets applied to the Y coordinate to the key text.
Default:  0
Name: keyTextAccessible
Description: 
By default the key text IS NOT accessible but by using this setting you can override this.
Default: null
Name: keyInteractive
Description: 
Whether the key is interactive or not. Not all chart types support this.
Default: false
Name: keyInteractive
Description: 
Whether the key is interactive or not. Not all chart types support this.
Default: false
Name: keyInteractiveHighlightChartLinewidth
Description: 
The linewidth of the stroke that goes around the highlight on the chart.
Default: rgba(255,255,255,0.7)
Name: keyInteractiveHighlightChartFill
Description: 
The highlight fill color that's used to highlight the chart by the interactive key.
Default: rgba(255,255,255,0.7)
Name: keyInteractiveHighlightChartStroke
Description: 
The highlight stroke color that's used to highlight the chart by the interactive key.
Default: black
Name: keyFormattedDecimals
Description: 
This stipulates how many decimals are used in the key labels. Formatted key labels are documented below.
Default:  0
Name: keyFormattedPoint
Description: 
The character(s) that's used as the decimal separator in the %{value_formatted} macro. Formatted key labels are documented below.
Default: .
Name: keyFormattedThousand
Description: 
The character(s) that's used as the thousand separator in the %{value_formatted} macro. Formatted key labels are documented below.
Default: ,
Name: keyFormattedUnitsPre
Description: 
The units to add to the value. These units are positioned before the number. Formatted key labels are documented below.
Default: [an empty string]
Name: keyFormattedUnitsPost
Description: 
The units to add to the value. These units are positioned after the number. Formatted key labels are documented below.
Default: [an empty string]
Name: keyFormattedValueSpecific
Description: 
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
Name: keyFormattedItemsCount
Description: 
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.