Share RGraph on Facebook Share RGraph on Twitter

Gauge chart API reference

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

PropertyDescriptionDefault
centerxIf 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.null
centeryIf 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.null
radiusIf 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.null
anglesStartYou 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.TWOPInull
anglesEndYou 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.TWOPInull
centerx
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

PropertyDescriptionDefault
marginLeftThe left margin of the chart.15
marginRightThe right margin of the chart.15
marginTopThe top margin of the chart.15
marginBottomThe bottom margin of the chart.15
marginLeft
The left margin of the chart.
Default: 15

marginRight
The right margin of the chart.
Default: 15

marginTop
The top margin of the chart.
Default: 15

marginBottom
The bottom margin of the chart.
Default: 15

Background properties

PropertyDescriptionDefault
backgroundColorThe background color of the Gauge chart.white
backgroundGradientIf 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.false
backgroundColor
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

PropertyDescriptionDefault
textAccessibleA 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>
true
textAccessibleOverflowThis 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
textAccessiblePointereventsThis controls whether the DOM text responds to mouse based events or not (it sets the pointer-events CSS property to none).false
textFontThe font that is used for the text on the chart.Arial, Verdana, sans-serif
textColorThe color of the text on the chart.#666
textSizeThe size of the text on the chart.12
textBoldWhether the text on the chart is bold or not.false
textItalicWhether the text on the chart is italic or not.false
labelsCountThis controls the number of labels shown on the Gauge.5
labelsOffsetAngleThis is the angular offset that the labels are positioned at (measured in radians).0
labelsOffsetRadiusThis is the radial offset the labels are positioned at.0
labelsOffsetxThis is the X offset the labels are positioned at.0
labelsOffsetyThis is the Y offset the labels are positioned at.0
labelsSpecificIf you don't want a scale and want specific labels instead, you pass an array of labels using this property instead.null
labelsCenteredThis controls whether the labels are centered horizontally and vertically.false
labelsFontThe font that the labels are rendered in.null
labelsSizeThe size of the font used by the labels.null
labelsColorThe color of the labels text.null
labelsBoldWhether the labels are bold or not.null
labelsItalicWhether the labels are italic or not.null
labelsValueThis allows you to show a text label under the pointer (by default) that tells you what the value is.false
labelsValueDecimalsWith this you can specify how many decimals that you want displayed.0 (defaults to scaleDecimals)
labelsValueBoundingThis allows you to turn completely off the bounding box.true
labelsValueBoundingStrokeThis 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
labelsValueBoundingFillThis 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
labelsValueUnitsPreUnits that are added to the center label (before the number).(an empty string)
labelsValueUnitsPostUnits that are added to the center label (after the number).(an empty string)
labelsValueFontThe font to use for the value text label.null
labelsValueSizeThe size to use for the value text label.null
labelsValueItalicWhether the value text label is italic or not.null
labelsValueBoldWhether the value text label is bold or not.null
labelsValueColorThe color to use for the value text label.null
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">
<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)

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

PropertyDescriptionDefault
titleTopThe top title of the chart, if any.(An empty string)
titleTopFontThe font that the top title is rendered in. If not specified the textFont setting is used (usually Arial).null
titleTopSizeThe size of the top title.null
titleTopBoldWhether the top title is bold or not.null
titleTopColorThe color that the top title is rendered in.null
titleTopItalicWhether the top title is italic or not.null
titleTopPosIf 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.null
titleBottomThe bottom title of the chart, if any.(An empty string)
titleBottomFontThe font that the bottom title is rendered in. If not specified the textFont setting is used (usually Arial).null
titleBottomSizeThe size of the bottom title.null
titleBottomBoldWhether the bottom title is bold or not.null
titleBottomColorThe color that the bottom title is rendered in.null
titleBottomItalicWhether the bottom title is italic or not.null
titleBottomPosIf 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.null
titleTop
The top title of the chart, if any.
Default: (An empty string)

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

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

Scale properties

PropertyDescriptionDefault
scaleDecimalsThe number of decimal places to display for the Y scale.0
scalePointThe character used as the decimal point..
scaleThousandThe character used as the thousand separator.,
scaleUnitsPreThe units that the Y axis is measured in. This string is displayed before the actual number, allowing you to specify values such as "$50".(An empty string)
scaleUnitsPostThe units that the Y axis is measured in. This string is displayed after the actual number, allowing you to specify values such as "50ms".(An empty string)
scaleDecimals
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

PropertyDescriptionDefault
colorsRedStartThe point at which the red area starts.90% of the max
colorsRedColorThe red color.#DC3912
colorsRedWidthThe width of the red area.10
colorsYellowColorThe yellow color.#FF9900
colorsYellowWidthThe width of the yellow area.10
colorsGreenEndThe point at which the green area ends.70% of the max
colorsGreenColorThe green color.rgba(0,0,0,0)
colorsGreenWidthThe width of the red area.10
colorsRangesWith 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.null
borderOuterThis is the color of the outer border.#ccc
borderInnerThis is the color of the inner border.#f1f1f1
borderOutlineThis is the color of the border around the Gauge.black
borderGradientThis determines whether the Gauge chart has a graduated border. Note: This can cause effects to run slowly in some browsers.false
colorsRedStart
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

PropertyDescriptionDefault
shadowWhether a drop shadow is applied.true
shadowColorThe color of the shadow.gray
shadowOffsetxThe X offset of the shadow.0
shadowOffsetyThe Y offset of the shadow.0
shadowBlurThe severity of the shadow blurring effect.15
shadow
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

PropertyDescriptionDefault
needleTailWhether the tail for the needle is shown.false
needleSizeThis is the size of the needle(s). This can be an array of numbers or just a single number.null
needleColorsThis is the color(s) of the needle(s).['#D5604D', 'red', 'green', 'yellow']
needleTypeThis controls the appearance of the needles. It can be triangle or line.triangle
needleWidthThis is the linewidth that's used as the width of the line style of pointer.7
centerpinColorThis is the color used in the centerpin gradient coloring.blue
centerpinRadiusThis is the radius of the centerpin.null
needleTail
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 coloring.
Default: blue

centerpinRadius
This is the radius of the centerpin.
Default: null

Interactive Features properties

PropertyDescriptionDefault
adjustableYou can make the Gauge interactively adjustable by setting this to true.false
adjustable
You can make the Gauge interactively adjustable by setting this to true.
Default: false

Miscellaneous properties

PropertyDescriptionDefault
borderWidthThe width of the border that goes around the Gauge.10
tickmarksSmallThe number of small tickmarks on the chart.25
tickmarksSmallColorThe color of the small tickmarks on the chart.black
tickmarksLargeThe 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.5
tickmarksLargeColorThe color of the big tickmarks on the chart.black
cleartoThis is used in animations and effects as the default color to use when the canvas.null
borderWidth
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:

var 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.

Animation 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)
    {
        // ...
    }

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