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 »

Segmented donut chart API reference

Example

A clickable Segmented Progress bar
<script>
    segmented = new RGraph.Segmented({
        id: 'cvs',
        min: 0,
        max: 100,
        value: 67,
        options: {
            width: '-20',
            labelsCenterUnitsPost: '%'
        }
    }).roundRobin({frames: 90});
    
    segmented.canvas.onclick = function (e)
    {
        var value = segmented.getValue(e);
        segmented.value = value;
    
        segmented.grow();
    }
</script>

Properties

You can use these properties to control how the chart appears. You can set them by including them in the options section of the configuration as shown above.

Chart configuration properties

Name: centerx
Description: 
If required, you can position the Segmented donut using this instead of the margins. As well as a number, that gives the exact coordinate of the center position of the chart, this can also be a string like this: centerx: '+25' or this: centerx: '-40' which is then used to adjust the calculated coordinate.
Default: null
Name: centery
Description: 
If required, you can position the Segmented donut using this instead of the margins. As well as a number, that gives the exact coordinate of the center position of the chart, this can also be a string like this: centery: '+25' or this: centery: '-40' which is then used to adjust the calculated coordinate.
Default: null
Name: radius
Description: 
If required, you can size the Segmented donut using this instead of the margins. As well as a number, that gives the exact size of the chart, this can also be a string like this: radius: '+25' or this: radius: '-40' which is then used to adjust the calculated coordinate.
Default: null
Name: width
Description: 
This is the width of the circular bar that makes up the chart.
Default: 10

Margin properties

Name: marginLeft
Description: 
The left margin of the chart.
Default: 15
Name: marginRight
Description: 
The right margin of the chart.
Default: 15
Name: marginTop
Description: 
The top margin of the chart.
Default: 15
Name: marginBottom
Description: 
The bottom margin of the chart.
Default: 15

Color properties

Name: colors
Description: 
The colors of the chart. This should be a two-element array consisting of the foreground color and the background color.
Default: [red, white]
Name: colors
Description: 
The colors of the chart. This should be a two-element array consisting of the foreground color and the background color.
Default: [red, white]
Name: backgroundColor
Description: 
The background color of the chart.
Default: black

Labels and text properties

Name: textAccessible
Description: 
A new feature in 2016 that allows you to use dom text in place of canvas text. It makes for much higher quality text that you can also select if desired (for copy/paste operations). It won't fit all situations and you can read more about the DOM text feature here. A good way to control borders/margins/padding etc is not to set them on the canvas but to wrap the canvas in a div and set them on that like this:
<div style="margin-left: 50px; display: inline-block">
    <canvas id="cvs" width="650" height="250"></canvas>
</div>
Default: false
Name: textAccessibleOverflow
Description: 
This can be visible or hidden and it controls whether the text is clipped to the edges of the canvas. It defaults to be visible and means you can set small margins if you wish.
Default: visible
Name: textAccessiblePointerevents
Description: 
This controls whether the dom text responds to mouse-based events or not (it sets the pointer-events css property to none).
Default: true
Name: textFont
Description: 
The font used to render the text.
Default: Arial, Verdana, sans-serif
Name: textColor
Description: 
The color of the label.
Default: black
Name: textSize
Description: 
The size of the text (in points).
Default: null (the text size is calculated)
Name: textBold
Description: 
Whether text on the chart is bold or not.
Default: false
Name: textItalic
Description: 
Whether text on the chart is italic or not.
Default: false
Name: labelsCenterSpecific
Description: 
If you want to specify your own label, which can be textual, you can use this property.
Default: null
Name: labelsCenterSpecificFormattedDecimals
Description: 
When using formatted labels this is the number of decimals that are applied to the %{value_formatted} macro.
Default:  0
Name: labelsCenterSpecificFormattedPoint
Description: 
When using formatted labels this is the decimal point character that's used with the %{value_formatted} macro.
Default: .
Name: labelsCenterSpecificFormattedThousand
Description: 
When using formatted labels this is the thousand separator character that's used with the %{value_formatted} macro.
Default: ,
Name: labelsCenterSpecificFormattedUnitsPre
Description: 
When using formatted labels these are the units that are prepended to the number with the %{value_formatted} macro.
Default: (an empty string)
Name: labelsCenterSpecificFormattedUnitsPost
Description: 
When using formatted labels these are the units that are appended to the number with the %{value_formatted} macro.
Default: (an empty string)
Name: labelsCenterFont
Description: 
The font used by the labelsCenter label.
Default: null
Name: labelsCenterSize
Description: 
The size of the labelsCenter label.
Default: null
Name: labelsCenterColor
Description: 
The color of the labelsCenter label.
Default: null
Name: labelsCenterBold
Description: 
Whether the labelsCenter label is bold or not.
Default: null
Name: labelsCenterItalic
Description: 
Whether the labelsCenter label is italic or not.
Default: null
Name: labelsCenterDecimals
Description: 
The number of decimals that are shown on the label.
Default:  0
Name: labelsCenterUnitsPre
Description: 
These units are prepended to the number.
Default: [an empty string]
Name: labelsCenterUnitsPost
Description: 
These units are appended to the number.
Default: [an empty string]
Name: labelsCenterPoint
Description: 
The character that's used as the decimal point.
Default: .
Name: labelsCenterThousand
Description: 
The character that's used as the thousand separator.
Default: ,
Name: labelsCenterOffsetx
Description: 
This allows you finer-grained control in the horizontal direction over the text positioning if you need it.
Default:  0
Name: labelsCenterOffsety
Description: 
This allows you finer-grained control in the vertical direction over the text positioning if you need it.
Default:  0
Name: text
Description: 
This allows you to add custom text to your chart if you want to. There's a dedicated page that describes this option here.
Default: null

Interactive features properties

Name: contextmenu
Description: 
An array of context menu items. More information about context menus is here.
Default: An empty array
Name: annotatable
Description: 
Whether annotations are enabled for the chart (ie you can draw on the chart interactively.
Default: false
Name: annotatableColor
Description: 
If you do not allow the use of the palette, then this will be the only color allowed for annotations.
Default: black
Name: annotatableLinewidth
Description: 
This is the linewidth of the annotations.
Default: 1
Name: adjustable
Description: 
Defaulting to false, this determines whether the chart will be adjustable (click the bar and drag it).
Default: false

Miscellaneous properties

Name: radialsCount
Description: 
How many segments are used when the chart is drawn. This is the total amount of segments on the chart - not just the colored portion.
Default: 36
Name: clearto
Description: 
This is used in animations and effects as the default color to use when clearing the canvas.
Default: null
Name: responsive
Description: 
This option is new to the July 2023 release (v6.13) and allows you to inline the responsive configuration instead of appending it on to the end of the object it as a function. The documentation and demo pages have been updated to use this new option. You can read more about the responsive feature by reading the responsive configuration page.
Default: null

Methods

obj.get(name)
An accessor that you can use to retrieve the values of properties.

obj.set(name, value)
An accessor that you can use to set the values of properties.

obj.getValue(event or angle)

This method can be used to get the value at a particular point when you click on the chart (or for a specific angle that you give, measured in radians). An example:

obj.canvas.onclick = function (e)
{
    var obj   = e.target.__object__;
    var value = obj.getValue(e);
    // var value = obj.getValue(angle); // Provide an angle to the function instead of an event object
    
    // ...
}

obj.getAngle(value or event)
This method will return you an appropriate angle for the given value (or event object).

obj.on(event, function)

This method can be used to set an event listener on an object. It operates similarly to the jquery on function. The first argument is the event that you wish to attach to and the second is the handler function. For example:

obj.on('draw', function (obj)
{
    // Put event code here
});

The function is useful if you use method chaining when creating your charts:

var obj = new RGraph.Segmented({
    id: 'cvs',
    min: 0,
    max: 100,
    value: 56,
    options: {
    }
}).on('draw', function (e, shape)
{
    // Put the draw event code here
})
.on('draw', function (e, shape)
{
    // Handle the draw event with another function
}).draw();
obj.exec(function)

The exec function is documented here.


obj.responsive(configuration)

The responsive function helps your charts respond to different browser window sizes and screen resolutions. For example, for smaller screens, you might want to have angled labels or show shorter versions of them completely.

Update: There is now the responsive configuration option available to you and this is now the preferred method of configuration.

The responsive function and configuration option are documented on their own page here.

The coordinates properties

There's only the coordinates of the text available to in regards to coordinates that are maintained for you because there are no selectable ares on the Segmented Meter chart

Events

RGraph supports custom events that allow you to easily add interactivity to your charts if required. The following events are available:

For example:
new RGraph.Segmented({
    id: 'cvs',
    min: 0,
    max: 100,
    valllue: 45,
    options: {
    }
}).on('draw', function (obj)
{
    console.log('The draw event has fired');
    
}).draw();

Effects

These effects are available and can be used instead of the draw function. There are also generic effects available which you can see here: Generic effects and transitions
<script>
    //
    // Optional callback function that's called when the effect is complete
    //
    function myCallback (obj)
    {
        // ...
    }

    segmented = new RGraph.Segmented({
        id: 'cvs',
        min: 0,
        max: 100,
        value: 56,
        options: {
            marginLeft: 35
        }
    }).roundRobin({frames: 60}, myCallback);
    
    setInterval(function ()
    {
        segmented.value = segmented.value + RGraph.random(-10,10);
        segmented.grow();
    }, 2500);
</script>