RGraph is a JavaScript charts library based on
HTML5 SVG and canvas. RGraph is mature (over 16 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.20, 1st December 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.
<script>
new RGraph.Meter({
id: 'cvs',
min: 0,
max: 100,
value: 6.4,
options: {
marginTop: 25,
marginBottom: 25,
marginLeft: 25,
marginRight: 25,
anglesStart: RGraph.PI + 0.5,
anglesEnd: RGraph.TWOPI - 0.5,
linewidthSegments: 15,
textSize: 16,
colorsStroke: 'white',
segmentsRadiusStart: 210,
border: 0,
tickmarksSmallCount: 0,
tickmarksLargeCount: 0,
adjustable: true,
needleRadius: 190,
needleHeadWidth: 0.10
}
}).on('draw', function (obj)
{
// Determine the color
if (obj.value < 10) {
var color = 'red';
} else if (obj.value < 35) {
var color = '#cc0';
} else {
var color = 'green';
}
RGraph.text({
object: obj,
x: obj.centerx,
y: obj.centery - 25,
text: obj.value.toFixed(0) + '%',
size: 75,
halign: 'center',
color: color
});
}).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.
If required, you can position the Meter chart using this instead of the margins. As well as a number, that gives the exact coordinate of the center position of the meter, 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 Meter chart using this instead of the margins. As well as a number, that gives the exact coordinate of the center position of the meter, 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 Meter chart using this instead of the margins. As well as a number, that gives the exact size of the meter, 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 Meter chart should start at with this property. Keep in mind though - that by default the Meter is positioned at the bottom of the canvas. Remember that there are three "constants" available for you to use: RGraph.HALFPIRGraph.PIRGraph.TWOPI
Default: Pi (3.14...)
Name: anglesEnd
Description:
You can specify the angle that the Meter chart should end at with this property. Keep in mind though - that by default the Meter is positioned at the bottom of the canvas. Remember that there are three "constants" available for you to use: RGraph.HALFPIRGraph.PIRGraph.TWOPI
Default: 2 * Pi (6.28...)
Background properties
Name: backgroundImageUrl
Description:
The URL of an image that is used as the background for the Meter. If you use a background image you can create some significantly different-looking Meters. You can see examples in the download archive.
Default: null
Name: backgroundImageOffsetx
Description:
By default the image is positioned at [0,0] (the top left of the canvas) - you can use this to move the image left (negative) or right (positive).
Default: 0
Name: backgroundImageOffsety
Description:
By default the image is positioned at [0,0] (the top left of the canvas) - you can use this to move the image up (negative) or down (positive).
Default: 0
Name: backgroundImageStretch
Description:
If true (the default) then the image will be stretched to fit the canvas width and height (the width and height are the same as the canvaswidth and height).
Default: true
Name: backgroundColor
Description:
The background color for the Meter. If you have a non-white background you may want to change this.
Default: white
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
Color properties
Name: colorsStroke
Description:
The color of the bits separating the segments. By setting this to white you can get a separation effect.
Default: null
Name: colorsGreenStart
Description:
The value that the green area should begin at.
Default: 35% of the maximum value
Name: colorsGreenEnd
Description:
The value that the green area should end at.
Default: The maximum value
Name: colorsGreenColor
Description:
The color of the green area.
Default: #207A20
Name: colorsYellowStart
Description:
The value that the yellow area should begin at.
Default: 10% of the maximum value
Name: colorsYellowEnd
Description:
The value that the yellow area should end at.
Default: 35% of the maximum value
Name: colorsYellowColor
Description:
The color of the yellow area (can be any color).
Default: #D0AC41
Name: colorsRedStart
Description:
The value that the red area should begin at.
Default: The minimum value
Name: colorsRedEnd
Description:
The value that the red area should end at.
Default: 10% of the maximum value
Name: colorsRedColor
Description:
The color of the red area (can be any color).
Default: #9E1E1E
Name: colorsRanges
Description:
If the green/yellow/red colors don't suit your desired Meter you can use this to completely control the color ranges on your chart. An example for a chart with a range of 0-100 would be:
A new feature in 2016 that allows you to use dom text in place of canvas text. It makes for a 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: true
Name: textColor
Description:
The color of the labels.
Default: black
Name: textSize
Description:
The size (in points) of the labels.
Default: 12
Name: textFont
Description:
The font used to render the text.
Default: Arial, Verdana, sans-serif
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: textValign
Description:
The vertical alignment of the text. In some cases, you may want to change this to bottom.
Default: center
Name: labelsValue
Description:
This option controls whether the value of the Meter is shown in text.
Default: false
Name: labelsValueDecimals
Description:
The number of decimals shown in the text label.
Default: 0
Name: labelsValueUnitsPre
Description:
The units (before the value) shown in the text label.
Default: An empty string
Name: labelsValueUnitsPost
Description:
The units (after the value) shown in the text label.
Default: An empty string
Name: labelsValuePoint
Description:
The character(s) used as the decimal point.
Default: .
Name: labelsValueThousand
Description:
The character(s) used as the thousand separator.
Default: ,
Name: labelsValueFont
Description:
The font that the text is rendered in.
Default: null
Name: labelsValueSize
Description:
The size (in points) of the text.
Default: null
Name: labelsValueBold
Description:
Whether the text is bold or not.
Default: null
Name: labelsValueItalic
Description:
Whether the text is italic or not.
Default: null
Name: labelsValueColor
Description:
The color of the text.
Default: null
Name: labelsValueBackground
Description:
Whether the text has a background or not.
Default: true
Name: labelsValueBackgroundFill
Description:
The color of the background of the text.
Default: rgba(255,255,255,0.75)
Name: labelsValueBackgroundStroke
Description:
The stroke color of the background.
Default: rgba(0,0,0,0)
Name: labelsValueSpecific
Description:
If you want to specify the label to display on the Meter you can specify it with this property.
Default: null
Name: labelsValueOffsetx
Description:
This allows you finer-grained control in the horizontal direction over the text positioning if you need it.
Default: 0
Name: labelsValueOffsety
Description:
This allows you finer-grained control in the vertical direction over the text positioning if you need it.
Default: 0
Name: labels
Description:
Whether the labels are shown or not.
Default: true
Name: labelsCount
Description:
This is used to stipulate how many labels are drawn on the Meter.
Default: 10
Name: labelsSpecific
Description:
If you want to show specific labels on your Meter chart then you can use this property. The format of this array is an array of arrays, which contain the label and the value that that label should be positioned at. For example: [['Low', 10],['Medium', 30],['High',50]] As of version 4.68, this can now also be an array of either strings or numbers (instead of an array of arrays). If this is the case then the labels are simply spaced equally around the Meter. For example: ['Low','Medium','High']
Default: null
Name: labelsOffsetRadius
Description:
The radius offset that the labels are positioned at. Using this property you can easily make a dual scale Meter chart there's an example of such a chart in the download archive. There's also an SVG Gauge chart that can provide two scales.).
The font that the title is rendered in. If not specified the textFont setting is used (usually Arial).
Default: null
Name: titleSize
Description:
The size of the title. If not specified the size is usually 4pt bigger than the textSize setting.
Default: null
Name: titleBold
Description:
Whether the title is bold or not.
Default: null
Name: titleItalic
Description:
Whether the title is italic or not.
Default: null
Name: titleColor
Description:
The color of the title.
Default: null
Name: titleX
Description:
To give the exact X coordinate for the title - use this. This can also be a string like this: "-5" - in which case it's converted to a number and added to the calculated coordinate - allowing you to adjust the calculated coordinate.
Default: null
Name: titleY
Description:
To give the exact Y coordinate for the title - use this. This can also be a string like this: "-5" - in which case it's converted to a number and added to the calculated coordinate - allowing you to adjust the calculated coordinate.
Default: null
Name: titleHalign
Description:
The horizontal alignment of the title.
Default: center (can change depending on other options)
Name: titleValign
Description:
The vertical alignment of the title.
Default: center (can change depending on other options)
Name: titleOffsetx
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: titleOffsety
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: titleSubtitle
Description:
The subtitle of the chart. If a subtitle is specified the title is moved up to accommodate it. As such you might need to give a larger marginTop value.
Default: null
Name: titleSubtitleSize
Description:
The size of the font used to render the subtitle.
Default: null
Name: titleSubtitleColor
Description:
The color of the subtitle.
Default: #aaa
Name: titleSubtitleFont
Description:
The font used to render the subtitle.
Default: null
Name: titleSubtitleBold
Description:
Whether the subtitle is bold or not.
Default: null
Name: titleSubtitleItalic
Description:
Whether the subtitle is italic or not.
Default: null
Name: titleSubtitleOffsetx
Description:
Use this property to adjust the horizontal position of the subtitle.
Default: 0
Name: titleSubtitleOffsety
Description:
Use this property to adjust the vertical position of the subtitle.
Default: 0
Scale properties
Name: scaleUnitsPre
Description:
The units that the labels are 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 labels are measured in. This string is displayed after the actual number, allowing you to specify values such as 50ms.
Default: none
Name: scaleDecimals
Description:
The number of decimal places to display for the values.
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: ,
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 your Meter chart will be adjustable.
Default: false
Shadow properties
Name: shadow
Description:
Whether a drop shadow is applied.
Default: false
Name: shadowColor
Description:
The color of the shadow.
Default: rgba(0,0,0,0.5)
Name: shadowOffsetx
Description:
The horizontal offset of the shadow.
Default: 3
Name: shadowOffsety
Description:
The vertical offset of the shadow.
Default: 3
Name: shadowBlur
Description:
The severity of the shadow blurring effect.
Default: 3
Miscellaneous properties
Name: linewidth
Description:
The width of the outline of the Meter.
Default: 2
Name: linewidthSegments
Description:
The linewidth of the lines separating the segments.
Default: 1
Name: tickmarksSmallCount
Description:
This controls the number of small tickmarks.
Default: 100
Name: tickmarksLargeCount
Description:
This controls the number of large tickmarks.
Default: 10
Name: tickmarksSmallColor
Description:
This sets the color of the small tickmarks.
Default: #bbb
Name: tickmarksLargeColor
Description:
This sets the color of the large tickmarks.
Default: black
Name: border
Description:
Whether the outline is drawn.
Default: true
Name: segmentsRadiusStart
Description:
Instead of the segments going from the center point outwards, you can use this to specify a start point of the colored segments.
Default: null
Name: needleType
Description:
This can be set to normal or pointer. You can see an example of the pointer type in the demos.
Default: normal
Name: needleRadius
Description:
This can be used to stipulate the radius of the pointer.
Default: null
Name: needleLinewidth
Description:
This can be used to specify the linewidth used when drawing the needle.
Default: null
Name: needleTail
Description:
If true the needle will have a small tail.
Default: false
Name: needleHead
Description:
This can be used to disable the drawing of the arrowhead on the pointer.
Default: true
Name: needleHeadWidth
Description:
The width of the needle head. Keep in mind that this is measured in radians and not pixels.
Default: 0.088
Name: needleHeadLength
Description:
The length of the needle head. Keep in mind that if you set this too high the line beneath the pointer may show through.
Default: 30
Name: needleColor
Description:
The color of the needle. You'll probably also want the centerpin properties too.
Default: black
Name: needleImageUrl
Description:
If you want to use an image for the needle then you can do so using this property. Combined with the background image this can make some significantly different looking Meters. The needle should be pointing right (like this, or like this) Two examples of using the image properties are in the download archive.
Default: null
Name: needleImageOffsetx
Description:
Needle images are drawn so that the top left of the needle image is the centerx/centery of the Meter chart (when the needle is horizontal and pointing to the right). You'll probably want to center your needle image and you can do so with these properties. Centering is best done when the needle is pointing right. So if you haven't changed the angles this will be when the Meters value is the maximum value. If you have changed the angles then you'll have to pick a suitable value so the needle is pointing right.
Default: 0
Name: needleImageOffsety
Description:
As above but for the needles Y positioning.
Default: 0
Name: centerpinStroke
Description:
The color of the stroke around the centerpin of the needle.
Default: black
Name: centerpinFill
Description:
The color of the stroke around the centerpin of the needle.
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.getAngle(value)
This method will return you an appropriate angle for the given
value.
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 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.Meter({
id: 'cvs',
min: 0,
max: 100,
value: 56,
options: {
}
}).on('draw', function (e, shape)
{
// Put draw event code here
})
.on('click', function (e, shape)
{
// Handle 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
Meter 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.Meter({
id: 'cvs',
min: 0,
max: 100,
value: 56,
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
There's a stopAnimation() function that you can
use to stop an animation immediately if you need to.
There's a line chart demo called
demos/line-effects-stop-animation.html in
the download archive
that demonstrates the use of this function.