Gauge chart API reference
Summary: Documentation about the Gauge chart including information about all of the options that are available to you. The Gauge chart is a meter type chart that can show a value. It can also show multiple values at once.
Example
<script> new RGraph.Gauge({ id: 'cvs', min: 0, max: 100, value: 46, options: { title: 'Bandwidth' } }).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 in the example code above.
- Chart configuration properties
- Background properties
- Margin properties
- Labels and text properties
- Scale properties
- Color properties
- Needle properties
- Title properties
- Shadow properties
- Interactive features properties
- Miscellaneous properties
Chart configuration properties
If you want to totally override the positioning of the chart (eg you may have multiple charts on one canvas) you can do it with this.
Default: null
centery
If you want to totally override the positioning of the chart (eg you may have multiple charts on one canvas) you can do it with this.
Default: null
radius
If you want to totally override the size of the chart (eg you may have multiple charts on one canvas) you can do it with this. Remember that this is the radius and not the diameter.
Default: null
anglesStart
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
anglesEnd
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
Margin properties
Property | Description | Default |
---|---|---|
marginLeft | The left margin of the chart. | 35 |
marginRight | The right margin of the chart. | 35 |
marginTop | The top margin of the chart. | 35 |
marginBottom | The bottom margin of the chart. | 35 |
The left margin of the chart.
Default: 35
marginRight
The right margin of the chart.
Default: 35
marginTop
The top margin of the chart.
Default: 35
marginBottom
The bottom margin of the chart.
Default: 35
Background properties
The background color of the Gauge chart.
Default: white
backgroundGradient
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
Labels and text properties
Property | Description | Default |
---|---|---|
textAccessible | 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"> | true |
textAccessibleOverflow | 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. | visible |
textAccessiblePointerevents | This controls whether the DOM text responds to mouse based events or not (it sets the pointer-events CSS property to none). | false |
textFont | The font that is used for the text on the chart. | Arial, Verdana, sans-serif |
textColor | The color of the text on the chart. | #666 |
textSize | The size of the text on the chart. | 12 |
textBold | Whether the text on the chart is bold or not. | false |
textItalic | Whether the text on the chart is italic or not. | false |
labelsCount | This controls the number of labels shown on the Gauge. | 5 |
labelsOffsetAngle | This is the angular offset that the labels are positioned at (measured in radians). | 0 |
labelsOffsetRadius | This is the radial offset the labels are positioned at. | 0 |
labelsOffsetx | This is the X offset the labels are positioned at. | 0 |
labelsOffsety | This is the Y offset the labels are positioned at. | 0 |
labelsSpecific | If you don't want a scale and want specific labels instead, you pass an array of labels using this property instead. | null |
labelsCentered | This controls whether the labels are centered horizontally and vertically. | false |
labelsFont | The font that the labels are rendered in. | null |
labelsSize | The size of the font used by the labels. | null |
labelsColor | The color of the labels text. | null |
labelsBold | Whether the labels are bold or not. | null |
labelsItalic | Whether the labels are italic or not. | null |
labelsValue | This allows you to show a text label under the pointer (by default) that tells you what the value is. | false |
labelsValueDecimals | With this you can specify how many decimals that you want displayed. | 0 (defaults to scaleDecimals) |
labelsValuePoint | This can be set to one or more characters to be used as the decimal point for the labelsValue value. | null (defaults to scalePoint) |
labelsValueThousand | This can be set to one or more characters to be used as the thousand separator for the labelsValue value. | null (defaults to scaleThousand) |
labelsValueBounding | This allows you to turn completely off the bounding box. | true |
labelsValueBoundingStroke | 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) | black |
labelsValueBoundingFill | 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) | white |
labelsValueUnitsPre | Units that are added to the center label (before the number). | (an empty string) |
labelsValueUnitsPost | Units that are added to the center label (after the number). | (an empty string) |
labelsValueFont | The font to use for the value text label. | null |
labelsValueSize | The size to use for the value text label. | null |
labelsValueItalic | Whether the value text label is italic or not. | null |
labelsValueBold | Whether the value text label is bold or not. | null |
labelsValueColor | The color to use for the value text label. | null |
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: true
textAccessibleOverflow
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
textAccessiblePointerevents
This controls whether the DOM text responds to mouse based events or not (it sets the
pointer-events
CSS property to none).Default: false
textFont
The font that is used for the text on the chart.
Default: Arial, Verdana, sans-serif
textColor
The color of the text on the chart.
Default: #666
textSize
The size of the text on the chart.
Default: 12
textBold
Whether the text on the chart is bold or not.
Default: false
textItalic
Whether the text on the chart is italic or not.
Default: false
labelsCount
This controls the number of labels shown on the Gauge.
Default: 5
labelsOffsetAngle
This is the angular offset that the labels are positioned at (measured in radians).
Default: 0
labelsOffsetRadius
This is the radial offset the labels are positioned at.
Default: 0
labelsOffsetx
This is the X offset the labels are positioned at.
Default: 0
labelsOffsety
This is the Y offset the labels are positioned at.
Default: 0
labelsSpecific
If you don't want a scale and want specific labels instead, you pass an array of labels using this property instead.
Default: null
labelsCentered
This controls whether the labels are centered horizontally and vertically.
Default: false
labelsFont
The font that the labels are rendered in.
Default: null
labelsSize
The size of the font used by the labels.
Default: null
labelsColor
The color of the labels text.
Default: null
labelsBold
Whether the labels are bold or not.
Default: null
labelsItalic
Whether the labels are italic or not.
Default: null
labelsValue
This allows you to show a text label under the pointer (by default) that tells you what the value is.
Default: false
labelsValueDecimals
With this you can specify how many decimals that you want displayed.
Default: 0 (defaults to scaleDecimals)
labelsValuePoint
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)
labelsValueThousand
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)
labelsValueBounding
This allows you to turn completely off the bounding box.
Default: true
labelsValueBoundingStroke
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
labelsValueBoundingFill
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
labelsValueUnitsPre
Units that are added to the center label (before the number).
Default: (an empty string)
labelsValueUnitsPost
Units that are added to the center label (after the number).
Default: (an empty string)
labelsValueFont
The font to use for the value text label.
Default: null
labelsValueSize
The size to use for the value text label.
Default: null
labelsValueItalic
Whether the value text label is italic or not.
Default: null
labelsValueBold
Whether the value text label is bold or not.
Default: null
labelsValueColor
The color to use for the value text label.
Default: null
Title properties
The top title of the chart, if any.
Default: none
titleTopFont
The font that the top title is rendered in. If not specified the
textFont
setting is used (usually Arial).Default: null
titleTopSize
The size of the top title.
Default: null
titleTopBold
Whether the top title is bold or not.
Default: null
titleTopColor
The color that the top title is rendered in.
Default: null
titleTopItalic
Whether the top title is italic or not.
Default: null
titleTopPos
If set this number is multiplied with the radius to give the Y position of the title. This allows to totally override the Y position of the title.
Default: null
titleTopOffsetx
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
titleTopOffsety
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
titleBottom
The bottom title of the chart, if any.
Default: (An empty string)
titleBottomFont
The font that the bottom title is rendered in. If not specified the
textFont
setting is used (usually Arial).Default: null
titleBottomSize
The size of the bottom title.
Default: null
titleBottomBold
Whether the bottom title is bold or not.
Default: null
titleBottomColor
The color that the bottom title is rendered in.
Default: null
titleBottomItalic
Whether the bottom title is italic or not.
Default: null
titleBottomPos
If set this number is multiplied with the radius to give the Y position of the title. This allows to totally override the Y position of the title.
Default: null
titleBottomOffsetx
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
titleBottomOffsety
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
The number of decimal places to display for the Y scale.
Default: 0
scalePoint
The character used as the decimal point.
Default: .
scaleThousand
The character used as the thousand separator.
Default: ,
scaleUnitsPre
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: (An empty string)
scaleUnitsPost
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: (An empty string)
Color properties
The point at which the red area starts.
Default: 90% of the max
colorsRedColor
The red color.
Default: #DC3912
colorsRedWidth
The width of the red area.
Default: 10
colorsYellowColor
The yellow color.
Default: #FF9900
colorsYellowWidth
The width of the yellow area.
Default: 10
colorsGreenEnd
The point at which the green area ends.
Default: 70% of the max
colorsGreenColor
The green color.
Default: rgba(0,0,0,0)
colorsGreenWidth
The width of the red area.
Default: 10
colorsRanges
With this you can totally control the colors used on the chart - eg
[[-100,-90, 'red'], [-90, -70,'yellow'], [-70, 70, '#0f0'], [70, 90, 'yellow'], [90,100,'red']]
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
borderOuter
This is the color of the outer border.
Default: #ccc
borderInner
This is the color of the inner border.
Default: #f1f1f1
borderOutline
This is the color of the border around the Gauge.
Default: black
borderGradient
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
Whether a drop shadow is applied.
Default: true
shadowColor
The color of the shadow.
Default: gray
shadowOffsetx
The X offset of the shadow.
Default: 0
shadowOffsety
The Y offset of the shadow.
Default: 0
shadowBlur
The severity of the shadow blurring effect.
Default: 15
Needle properties
Whether the tail for the needle is shown.
Default: false
needleSize
This is the size of the needle(s). This can be an array of numbers or just a single number.
Default: null
needleColors
This is the color(s) of the needle(s).
Default: ['#D5604D', 'red', 'green', 'yellow']
needleType
This controls the appearance of the needles. It can be
triangle
or line
.Default: triangle
needleWidth
This is the linewidth that's used as the width of the line style of pointer.
Default: 7
centerpinColor
This is the color used in the centerpin gradient color.
Default: blue
centerpinRadius
This is the radius of the centerpin.
Default: null
Interactive Features properties
Property | Description | Default |
---|---|---|
adjustable | You can make the Gauge interactively adjustable by setting this to true . | false |
You can make the Gauge interactively adjustable by setting this to
true
.Default: false
Miscellaneous properties
The width of the border that goes around the Gauge.
Default: 10
tickmarksSmall
The number of small tickmarks on the chart.
Default: 25
tickmarksSmallColor
The color of the small tickmarks on the chart.
Default: black
tickmarksLarge
The number of big tickmarks on the chart. If you specify this you will actually 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
tickmarksLargeColor
The color of the big tickmarks on the chart.
Default: black
clearto
This is used in animations and effects as the default color to use when the canvas.
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 in a similar way to the jQuery on()
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
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.
The responsive()
function is documented on its own page here.
Animation Effects
These effects are available and can be used instead of thedraw()
function. There are also generic effects available which
you can see here:
Generic effects and transitions
- The Grow effect (effects-gauge-grow.html in the download archive
<script> /** * Optional callback function that's called when the effect is complete */ function myCallback (obj) { // ... } obj = new RGraph.Gauge({ id: 'cvs', min: 0, max: 100, value: 56 options: { } }).grow({frames: 60}, myCallback); </script>