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.
Get the latest version of RGraph (version 6.19, 28th September 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.
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.
If required, you can position the Gauge chart 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 Gauge chart 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 Gauge chart 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
Name: anglesStart
Description:
You can specify the angle that the Gauge should start at with this property. Remember that there are three "constants" available for you to use: RGraph.HALFPI, RGraph.PI, RGraph.TWOPI
Default: null
Name: anglesEnd
Description:
You can specify the angle that the Gauge should end at with this property. Remember that there are three "constants" available for you to use: RGraph.HALFPI, RGraph.PI, RGraph.TWOPI
Default: null
Background properties
Name: backgroundColor
Description:
The background color of the Gauge chart.
Default: white
Name: backgroundGradient
Description:
If true then a subtle gradient is drawn over the background. Alternatively, you can leave this as false and set the background color to your own gradient.
Default: false
Margin properties
Name: marginLeft
Description:
The left margin of the chart.
Default: 35
Name: marginRight
Description:
The right margin of the chart.
Default: 35
Name: marginTop
Description:
The top margin of the chart.
Default: 35
Name: marginBottom
Description:
The bottom margin of the chart.
Default: 35
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:
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-eventscss property to none).
Default: false
Name: textFont
Description:
The font that is used for the text on the chart.
Default: Arial, Verdana, sans-serif
Name: textColor
Description:
The color of the text on the chart.
Default: #666
Name: textSize
Description:
The size of the text on the chart.
Default: 12
Name: textBold
Description:
Whether the text on the chart is bold or not.
Default: false
Name: textItalic
Description:
Whether the text on the chart is italic or not.
Default: false
Name: labelsCount
Description:
This controls the number of labels shown on the Gauge. This option is also used when you're using formatted labels (ie when the labelsSpecific option is a string).
Default: 5
Name: labelsOffsetAngle
Description:
This is the angular offset that the labels are positioned at (measured in radians).
Default: 0
Name: labelsOffsetRadius
Description:
This is the radial offset the labels are positioned at.
Default: 0
Name: labelsOffsetx
Description:
This is the horizontal offset the labels are positioned at.
Default: 0
Name: labelsOffsety
Description:
This is the vertical offset the labels are positioned at.
Default: 0
Name: labelsSpecific
Description:
If you don't want a scale and want specific labels instead, you can give an array of labels using this property instead. You can also give this option a string if you prefer and use formatted labels
Default: null
Name: labelsSpecificFormattedDecimals
Description:
When using formatted labels this is the number of decimals that are applied to the %{value_formatted} macro.
Default: 0
Name: labelsSpecificFormattedPoint
Description:
When using formatted labels this is the decimal point character that's used with the %{value_formatted} macro.
Default: .
Name: labelsSpecificFormattedThousand
Description:
When using formatted labels this is the thousand separator character that's used with the %{value_formatted} macro.
Default: ,
Name: labelsSpecificFormattedUnitsPre
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: labelsSpecificFormattedUnitsPost
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: labelsCentered
Description:
This controls whether the labels are centered horizontally and vertically.
Default: false
Name: labelsFont
Description:
The font that the labels are rendered in.
Default: null
Name: labelsSize
Description:
The size of the font used by the labels.
Default: null
Name: labelsColor
Description:
The color of the labels.
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: labelsValue
Description:
This allows you to show a text label under the pointer (by default) that tells you what the value is.
Default: false
Name: labelsValueDecimals
Description:
With this you can specify how many decimals that you want to be displayed.
Default: 0 (defaults to scaleDecimals)
Name: labelsValuePoint
Description:
This can be set to one or more characters to be used as the decimal point for the labelsValue value.
Default: null (defaults to scalePoint)
Name: labelsValueThousand
Description:
This can be set to one or more characters to be used as the thousand separator for the labelsValue value.
Default: null (defaults to scaleThousand)
Name: labelsValueBounding
Description:
This allows you to completely turn off the bounding box.
Default: true
Name: labelsValueBoundingStroke
Description:
This allows you to set the fill color of the label. If you don't want a border you can set it to transparent: rgba(0,0,0,0)
Default: black
Name: labelsValueBoundingFill
Description:
This allows you to set the fill color of the label. If you don't want the label filled you can set it to transparent: rgba(0,0,0,0)
Default: white
Name: labelsValueUnitsPre
Description:
Units that are added to the center label (before the number).
Default: (an empty string)
Name: labelsValueUnitsPost
Description:
Units that are added to the center label (after the number).
The font that the top title is rendered in. If not specified the textFont setting is used (usually Arial).
Default: null
Name: titleTopSize
Description:
The size of the top title.
Default: null
Name: titleTopBold
Description:
Whether the top title is bold or not.
Default: null
Name: titleTopColor
Description:
The color that the top title is rendered in.
Default: null
Name: titleTopItalic
Description:
Whether the top title is italic or not.
Default: null
Name: titleTopPos
Description:
If set, this number is multiplied with the radius to give the Y coordinate of the title. This allows you to override the Y coordinate of the title.
Default: null
Name: titleTopOffsetx
Description:
You can use this property to adjust the positioning of the title in the horizontal direction (positive values adjust the title to the right and negative values adjust it to the left).
Default: 0
Name: titleTopOffsety
Description:
You can use this property to adjust the positioning of the title in the vertical direction (positive values adjust the title downwards and negative values adjust it upwards).
Default: 0
Name: titleTopSubtitle
Description:
The subtitle of the chart, if any.
Default: null
Name: titleTopSubtitleFont
Description:
The font that's used to render the subtitle.
Default: null
Name: titleTopSubtitleSize
Description:
The size of the font that's used to render the subtitle.
Default: null
Name: titleTopSubtitleColor
Description:
The color of the subtitle. By default this is a gray color.
Default: #666
Name: titleTopSubtitleBold
Description:
Whether the subtitle is bold or not.
Default: null
Name: titleTopSubtitleItalic
Description:
Whether the subtitle is italic or not.
Default: null
Name: titleTopSubtitleOffsetx
Description:
A horizontal offset that's added to the X coordinate of the subtitle.
Default: 0
Name: titleTopSubtitleOffsety
Description:
A vertical offset that's added to the Y coordinate of the subtitle.
Default: 0
Name: titleBottom
Description:
The bottom title of the chart, if any.
Default: (An empty string)
Name: titleBottomFont
Description:
The font that the bottom title is rendered in. If not specified the textFont setting is used (usually Arial).
Default: null
Name: titleBottomSize
Description:
The size of the bottom title.
Default: null
Name: titleBottomBold
Description:
Whether the bottom title is bold or not.
Default: null
Name: titleBottomColor
Description:
The color that the bottom title is rendered in.
Default: null
Name: titleBottomItalic
Description:
Whether the bottom title is italic or not.
Default: null
Name: titleBottomPos
Description:
If set, this number is multiplied with the radius to give the Y position of the title. This allows you to override the Y position of the title.
Default: null
Name: titleBottomOffsetx
Description:
You can use this property to adjust the positioning of the title in the horizontal direction (positive values adjust the title to the right and negative values adjust it to the left).
Default: 0
Name: titleBottomOffsety
Description:
You can use this property to adjust the positioning of the title in the vertical direction (positive values adjust the title downwards and negative values adjust it upwards).
Default: 0
Scale properties
Name: scaleDecimals
Description:
The number of decimal places to display for the Y scale.
Default: 0
Name: scalePoint
Description:
The character that's used as the decimal point.
Default: .
Name: scaleThousand
Description:
The character that's used as the thousand separator.
Default: ,
Name: scaleUnitsPre
Description:
The units that the scale is measured in. This string is displayed before the actual number, allowing you to specify values such as $50.
Default: (An empty string)
Name: scaleUnitsPost
Description:
The units that the scale is measured in. This string is displayed after the actual number, allowing you to specify values such as 50ms.
Default: (An empty string)
Color properties
Name: colorsRedStart
Description:
The point at which the red area starts.
Default: 90% of the max
Name: colorsRedColor
Description:
The red color.
Default: #DC3912
Name: colorsRedWidth
Description:
The width of the red area.
Default: 10
Name: colorsYellowColor
Description:
The yellow color.
Default: #FF9900
Name: colorsYellowWidth
Description:
The width of the yellow area.
Default: 10
Name: colorsGreenEnd
Description:
The point at which the green area ends.
Default: 70% of the max
Name: colorsGreenColor
Description:
The green color.
Default: rgba(0,0,0,0)
Name: colorsGreenWidth
Description:
The width of the red area.
Default: 10
Name: colorsRanges
Description:
With this you can totally control the colors used on the chart - eg
As of the June 2018 beta you can now give a fourth number to the array which is used as the width of the segment.
Default: null
Name: borderOuter
Description:
This is the color of the outer border.
Default: #ccc
Name: borderInner
Description:
This is the color of the inner border.
Default: #f1f1f1
Name: borderOutline
Description:
This is the color of the border around the Gauge.
Default: black
Name: borderGradient
Description:
This determines whether the Gauge chart has a graduated border. Note: This can cause effects to run slowly in some browsers.
Default: false
Shadow properties
Name: shadow
Description:
Whether a drop shadow is applied.
Default: true
Name: shadowColor
Description:
The color of the shadow.
Default: gray
Name: shadowOffsetx
Description:
The horizontal offset of the shadow.
Default: 0
Name: shadowOffsety
Description:
The vertical offset of the shadow.
Default: 0
Name: shadowBlur
Description:
The severity of the shadow blurring effect.
Default: 15
Needle properties
Name: needleTail
Description:
Whether the tail for the needle is shown.
Default: false
Name: needleSize
Description:
This is the size of the needle(s). This can be an array of numbers or just a single number.
Default: null
Name: needleColors
Description:
This is the color(s) of the needle(s).
Default: ['#D5604D', 'red', 'green', 'yellow']
Name: needleType
Description:
This controls the appearance of the needles. It can be triangle or line.
Default: triangle
Name: needleWidth
Description:
This is the linewidth that's used as the width of the line style of pointer.
Default: 7
Name: centerpinColor
Description:
This is the color used in the centerpin gradient color.
Default: blue
Name: centerpinRadius
Description:
This is the radius of the centerpin.
Default: null
Interactive Features properties
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:
You can make the Gauge interactively adjustable by setting this to true.
Default: false
Miscellaneous properties
Name: borderWidth
Description:
The width of the border that goes around the Gauge.
Default: 10
Name: tickmarksSmall
Description:
The number of small tickmarks on the chart.
Default: 25
Name: tickmarksSmallColor
Description:
The color of the small tickmarks on the chart.
Default: black
Name: tickmarksLarge
Description:
The number of big tickmarks on the chart. If you specify this you will get one more than the number of tickmarks than you specify. So if you specify 5, you'll get 6 tickmarks because of the end tickmarks.
Default: 5
Name: tickmarksLargeColor
Description:
The color of the big tickmarks on the chart.
Default: black
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.getValue(event)
This method can be used to get the value at a particular point
(eg in a click or other event listener). That value could
then be used to set the value of the Gauge. Like this:
myGauge.canvas.onmousedown = function (e)
{
var obj = e.target.__object__;
var value = obj.getValue(e);
obj.value = value;
obj.grow();
}
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 jqueryon function -
the first argument is the event that you wish to attach the function to
and the second is the handler function. For example:
.on('draw', function (obj)
{
// Put event code here
});
The function is useful if you use method chaining when creating your charts:
obj = new RGraph.Gauge({
id: 'cvs',
min: 0,
max: 100,
value:52,
options: {
}
}).on('mousemove', function (e, shape)
{
// Handle the mousemove event
})
.on('click', function (e, shape)
{
// Handle the click event
}).draw();
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.
There's only one coordinates property on the
Gauge chart and that's the
obj.coordsText property.
obj.coordsText This holds the
coordinates of all of the text that has been added
to the chart. Even if the text is blank (ie no text)
then the coordinates will be added to this variable.
Events
RGraph supports custom events that allow you to easily add interactivity to your charts if
required. The following events are available:
adjustbegin This event fires at the start of adjusting - like the standard mousedown event.
adjust This event fires (repeatedly) during adjusting - like the standard mousemove event.
adjustend This event fires at the end of adjusting - like the standard mouseup event.
annotatebegin This event fires at the start of annotating - like the standard mousedown event.
annotate This event fires (repeatedly) during annotating - like the standard mousemove event.
annotateend This event fires at the end of annotating - like the standard mouseup event.
annotateclear This event fires at the end of the RGraph.clearAnnotations function.
beforeclear This event fires at the start of the RGraph.clear function.
clear This event fires at the end of the RGraph.clear function.
beforecontextmenu This event fires when you have the contextmenu enabled and it is about to appear.
contextmenu This event fires when you have the contextmenu enabled and it has been displayed.
beforedraw This event fires at the start of the draw method before anything has been done.
firstdraw This event fires at the end of the draw function - but only the first time that the draw function is called.
draw This event fires at the end of the draw function.
For example:
new RGraph.Gauge({
id: 'cvs',
min: 0,
max: 100,
value: 57,
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