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 »

Fuel gauge API reference

Example

A blue Fuel gauge
<script>
    // Create the Fuel chart. The arguments are: the minimum value, the maximum value, and the actual value.
    new RGraph.Fuel({
        id: 'cvs',
        min: 0,
        max: 100,
        value: 67,
        options: {
            needleColor: 'blue',
            colors: ['#ddf'],
            labelsEmpty: 'Empty!',
            labelsFull: 'Full',
            icon: '/images/water.jpg'
        }
    }).draw();
</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 Fuel gauge using this instead of the margins. As well as a number, that gives the exact coordinate of the center position of the gauge, 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 Fuel gauge using this instead of the margins. As well as a number, that gives the exact coordinate of the center position of the gauge, 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 Fuel gauge using this instead of the margins. As well as a number, that gives the exact size of the gauge, 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

Color properties

Name: colors
Description: 
The color of the Fuel Gauge. Note that despite there being only one color, this is still an array.
Default: ['red']

Margin properties

Name: marginLeft
Description: 
The left margin of the chart, (the margin is where the labels and title are)).
Default: 5
Name: marginRight
Description: 
The right margin of the chart, (the margin is where the labels and title are).
Default: 5
Name: marginTop
Description: 
The top margin of the chart, (the margin is where the labels and title are).
Default: 5
Name: marginBottom
Description: 
The bottom margin of the chart, (the margin is where the labels and title are).
Default: 5

Needle properties

Name: needleColor
Description: 
The color of the needle (not including the bulb at the bottom). Note that this is not an array - it's just a string.
Default: red
Name: needleRadiusOffset
Description: 
By increasing this you can shorten the needle and by decreasing it you can lengthen the needle.
Default: 45

Labels and text properties

Name: labelsEmpty
Description: 
The text that's used as the empty label.
Default: E
Name: labelsEmptyOffsetx
Description: 
This allows you finer-grained control in the horizontal direction over the text positioning if you need it.
Default:  0
Name: labelsEmptyOffsety
Description: 
This allows you finer-grained control in the vertical direction over the text positioning if you need it.
Default:  0
Name: labelsFull
Description: 
The text used as the full label.
Default: F
Name: labelsFullOffsetx
Description: 
This allows you finer-grained control in the horizontal direction over the text positioning if you need it.
Default:  0
Name: labelsFullOffsety
Description: 
This allows you finer-grained control in the vertical direction over the text positioning if you need it.
Default:  0
Name: labelsColor
Description: 
The color used for the text on the chart.
Default: null
Name: labelsFont
Description: 
The font used for the text.
Default: null
Name: labelsSize
Description: 
The size of the text.
Default: null
Name: labelsBold
Description: 
Whether the labels are bold or not.
Default: null
Name: labelsItalic
Description: 
Whether the labels are italic or not.
Default: null
Name: textColor
Description: 
The color used for the text on the chart.
Default: black
Name: textFont
Description: 
The font used for the text.
Default: Arial
Name: textSize
Description: 
The size of the text.
Default: 12
Name: textBold
Description: 
Whether the labels are bold or not.
Default: false
Name: textItalic
Description: 
Whether the labels are italic or not.
Default: false
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: 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

Scale properties

Name: scaleVisible
Description: 
Instead of the Full/Empty labels you can set this to true to show a scale instead.
Default: false
Name: scaleLabelsCount
Description: 
When you're showing a scale this controls how many labels are shown.
Default: 5
Name: scaleDecimals
Description: 
This determines how many decimal places are shown in the scale.
Default:  0
Name: scaleUnitsPre
Description: 
The units that the y-axis is measured in. This string is displayed before the actual number, allowing you to specify values such as $50.
Default: none
Name: scaleUnitsPost
Description: 
The units that the y-axis is measured in. This string is displayed after the actual number, allowing you to specify values such as 50ms.
Default: none
Name: scalePoint
Description: 
The character that's used as the decimal separator.
Default: .
Name: scaleThousand
Description: 
The character that's used as the thousand separator.
Default: ,

Interactive features properties

Name: contextmenu
Description: 
The context menu. For more details see the contextmenu documentation page.
Default: null
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: 
Whether the Fuel chart is adjustable or not.
Default: false

Miscellaneous properties

Name: icon
Description: 
This should be a URL that represents the image to use as the icon on the chart. The default fuel icon is a data: URL, though you can specify any valid image URL.
Default: [A data: URL of a fuel icon]
Name: iconRedraw
Description: 
If false then the chart is NOT redrawn when the image/icon loads. You may need to set this to false if you use the adjusting feature.
Default: true
Name: clearto
Description: 
This is used in animations and effects as the default color to use when 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.getAngle(value)

This method can be used to get an appropriate angle for a value when you're doing custom drawing on the chart. It returns null if the value is out of range.

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:

.on('draw', function (obj)
{
    // Put event code here
});
The exec option and method

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

As with the majority of the RGraph objects the coordinates of the various shapes are recorded and stored in various properties on the RGraph chart object. In the case of the Fuel chart the coordinates of text are recorded as usual in the obj.coordsText variable and the start angle, the end angle and the radius are recorded in the obj.angles property.

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.Fuel({
    id: 'cvs',
    min: 0,
    max: 50,
    value: 34,
    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)
    {
        // ...
    }

    new RGraph.Fuel({
        id: 'cvs',
        min: 0,
        max: 100,
        value: 56,
        options: {
        }
    }).grow({frames: 60}, myCallback);
</script>