Gauge chart

Example

View example on CodePen
<script>
    new RGraph.SVG.Gauge({
        id: 'chart-container',
        innerMin: 0,
        innerMax: 10,
        outerMin: 0,
        outerMax: 100,
        value: 7.8,
        options: {
            adjustable: true,
            centerpinRadius: 10,
            labelsIngraphUnitsPost: '%',
            labelsIngraphDecimals: 1,
            colors: ['red','blue'],
            marginTop: 15,
            marginBottom: 15,
            marginLeft: 15,
            marginRight: 15
        }
    }).draw();
</script>

The obj.nodes property

Instead of coordinates the Gauge chart maintains references to the nodes that are created - such as the axes, the labels and text nodes. For example:

For example, you could add your own event listeners like this:

<script>
    obj.nodes.needleGroup.onclick = function (e)
    {
        alert('The value is: ' + obj.value);
    }
</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

PropertyDescriptionDefault
centerxIf required, you can position the progress bar using this instead of the margins.null
centeryIf required, you can position the progress bar using this instead of the margins.null
radiusIf required, you can size the progress bar using this instead of the margins.null
centerx
If required, you can position the progress bar using this instead of the margins.
Default: null

centery
If required, you can position the progress bar using this instead of the margins.
Default: null

radius
If required, you can size the progress bar using this instead of the margins.
Default: null

Margin properties

PropertyDescriptionDefault
marginLeftThe left margin of the chart).35
marginRightThe right margin of the chart.35
marginTopThe top margin of the chart.35
marginBottomThe bottom margin of the chart.35
rmarginThis is the area that the outer scale sits in. By default, it is calculated at either 25 or 40 depending on whether the outer scale is enabled or not.null
marginLeft
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

rmargin
This is the area that the outer scale sits in. By default, it is calculated at either 25 or 40 depending on whether the outer scale is enabled or not.
Default: null

Background properties

PropertyDescriptionDefault
backgroundStrokeThe color of the background stroke color.#ddd
backgroundFillThe color of the background fill color.Gradient(white:#FEFEFE:#E6E6E6:#dedede)
backgroundGridWhether the background grid is enabled or not.true
backgroundGridColorThe color of the background grid.#ddd
backgroundStroke
The color of the background stroke color.
Default: #ddd

backgroundFill
The color of the background fill color.
Default: Gradient(white:#FEFEFE:#E6E6E6:#dedede)

backgroundGrid
Whether the background grid is enabled or not.
Default: true

backgroundGridColor
The color of the background grid.
Default: #ddd

Color properties

PropertyDescriptionDefault
colorsThe colors of the axes. This should be an array of two strings. Gradients cannot be used here.['black','black']
colors
The colors of the axes. This should be an array of two strings. Gradients cannot be used here.
Default: ['black','black']

Other text properties

PropertyDescriptionDefault
textFontThe font used to render the text.Arial, Verdana, sans-serif
textSizeThe size of the text.12
textColorThe color of the labels.black
textItalicWhether the labels are italic or not.false
textBoldWhether the labels are bold or not.false
textThis allows you to add custom text to your chart if you want to. There's a dedicated page that describes this option here.null
labelsIngraphWhether the ingraph label (in the center of the chart) is displayed.true
labelsIngraphFontThe font to use to render the text for the ingraph label.null
labelsIngraphSizeThe font size to use to render the text for the ingraph label.null
labelsIngraphBoldWhether the ingraph label should be bold or not.null
labelsIngraphItalicWhether the ingraph label should be italic or not.null
labelsIngraphColorThe color of the ingraph label.null
labelsIngraphUnitsPreUnits that are prepended to the ingraph label.none
labelsIngraphUnitsPostUnits that are appended to the ingraph label.none
labelsIngraphThousandThe character(s) used as the thousand separator.,
labelsIngraphPointThe character(s) used as the decimal point..
labelsIngraphFormatterThis can be a function that is used to handle all of the label formatting. It's passed the number as an argument.null
labelsIngraphDecimalsThis should be a number that dictates how many decimal places are displayed. 0
labelsIngraphPaddingPadding that is applied to the number.3
labelsIngraphBackgroundThe color of the background for the label.Gradient(#ddd:#eee)
labelsIngraphRoundedThe severity of the rounded corners effect of the label.2
textFont
The font used to render the text.
Default: Arial, Verdana, sans-serif

textSize
The size of the text.
Default: 12

textColor
The color of the labels.
Default: black

textItalic
Whether the labels are italic or not.
Default: false

textBold
Whether the labels are bold or not.
Default: false

text
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

labelsIngraph
Whether the ingraph label (in the center of the chart) is displayed.
Default: true

labelsIngraphFont
The font to use to render the text for the ingraph label.
Default: null

labelsIngraphSize
The font size to use to render the text for the ingraph label.
Default: null

labelsIngraphBold
Whether the ingraph label should be bold or not.
Default: null

labelsIngraphItalic
Whether the ingraph label should be italic or not.
Default: null

labelsIngraphColor
The color of the ingraph label.
Default: null

labelsIngraphUnitsPre
Units that are prepended to the ingraph label.
Default: none

labelsIngraphUnitsPost
Units that are appended to the ingraph label.
Default: none

labelsIngraphThousand
The character(s) used as the thousand separator.
Default: ,

labelsIngraphPoint
The character(s) used as the decimal point.
Default: .

labelsIngraphFormatter
This can be a function that is used to handle all of the label formatting. It's passed the number as an argument.
Default: null

labelsIngraphDecimals
This should be a number that dictates how many decimal places are displayed.
Default: 0

labelsIngraphPadding
Padding that is applied to the number.
Default: 3

labelsIngraphBackground
The color of the background for the label.
Default: Gradient(#ddd:#eee)

labelsIngraphRounded
The severity of the rounded corners effect of the label.
Default: 2

Scale properties

PropertyDescriptionDefault
scaleInnerFontThe font used to render the text.null
scaleInnerSizeThe size of the text.null
scaleInnerBoldWhether the text is bold or not.null
scaleInnerItalicWhether the text is italic or not.null
scaleInnerColorThe color of the text.null
scaleInnerDecimalsThe number of decimals used by the labels. 0
scaleInnerUnitsPreUnits for the label that are prepended to the number.(none)
scaleInnerUnitsPostUnits for the label that are prepended to the number.(none)
scaleInnerPointThe character(s) used for the decimal point..
scaleInnerThousandThe character(s) used as the thousand separator.,
scaleInnerFormatterThis can be a function that entirely handles the formatting of the number.null
scaleInnerLabelsCountThe number of labels that are displayed.10
scaleOuterWhether the outer scale is displayed or not.true
scaleOuterFontThe font used to render the text.null
scaleOuterSizeThe size of the text.null
scaleOuterBoldWhether the text is bold or not.null
scaleOuterItalicWhether the text is italic or not.null
scaleOuterColorThe color of the text.null
scaleOuterDecimalsThe number of decimals used by the labels. 0
scaleOuterUnitsPreUnits for the label that are prepended to the number.(none)
scaleOuterUnitsPostUnits for the label that are prepended to the number.(none)
scaleOuterPointThe character(s) used for the decimal point..
scaleOuterThousandThe character(s) used as the thousand separator.,
scaleOuterFormatterThis can be a function that entirely handles the formatting of the number.null
scaleOuterLabelsCountThe number of labels that are displayed.10
scaleInnerFont
The font used to render the text.
Default: null

scaleInnerSize
The size of the text.
Default: null

scaleInnerBold
Whether the text is bold or not.
Default: null

scaleInnerItalic
Whether the text is italic or not.
Default: null

scaleInnerColor
The color of the text.
Default: null

scaleInnerDecimals
The number of decimals used by the labels.
Default: 0

scaleInnerUnitsPre
Units for the label that are prepended to the number.
Default: (none)

scaleInnerUnitsPost
Units for the label that are prepended to the number.
Default: (none)

scaleInnerPoint
The character(s) used for the decimal point.
Default: .

scaleInnerThousand
The character(s) used as the thousand separator.
Default: ,

scaleInnerFormatter
This can be a function that entirely handles the formatting of the number.
Default: null

scaleInnerLabelsCount
The number of labels that are displayed.
Default: 10

scaleOuter
Whether the outer scale is displayed or not.
Default: true

scaleOuterFont
The font used to render the text.
Default: null

scaleOuterSize
The size of the text.
Default: null

scaleOuterBold
Whether the text is bold or not.
Default: null

scaleOuterItalic
Whether the text is italic or not.
Default: null

scaleOuterColor
The color of the text.
Default: null

scaleOuterDecimals
The number of decimals used by the labels.
Default: 0

scaleOuterUnitsPre
Units for the label that are prepended to the number.
Default: (none)

scaleOuterUnitsPost
Units for the label that are prepended to the number.
Default: (none)

scaleOuterPoint
The character(s) used for the decimal point.
Default: .

scaleOuterThousand
The character(s) used as the thousand separator.
Default: ,

scaleOuterFormatter
This can be a function that entirely handles the formatting of the number.
Default: null

scaleOuterLabelsCount
The number of labels that are displayed.
Default: 10

Title properties

PropertyDescriptionDefault
titleThe title of the chart.(An empty string)
titleXThe specific x-axis coordinate of the title. This can also be a string that looks like this: "+10" or "-10" in which case it's added to the calculated position.null
titleYThe specific y-axis coordinate of the title. This can also be a string that looks like this: "+10" or "-10" in which case it's added to the calculated position.+5 (a string)
titleOffsetxAn offset value that is added to the calculated x-axis coordinate. 0
titleOffsetyAn offset value that is added to the calculated y-axis coordinate. 0
titleHalignThe horizontal alignment of the title.center
titleColorThe color of the title.null
titleFontThe font used to render the title.null
titleSizeThe size of the font used to render the title.null
titleBoldWhether the title is bold or not.null
titleItalicWhether the title is italic or not.null
titleSubtitleThe 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.(An empty string)
titleSubtitleColorThe color of the subtitle.#aaa
titleSubtitleFontThe font used to render the subtitle.null
titleSubtitleSizeThe size of the font used to render the subtitle.null
titleSubtitleBoldWhether the subtitle is bold or not.null
titleSubtitleItalicWhether the subtitle is italic or not.null
title
The title of the chart.
Default: (An empty string)

titleX
The specific x-axis coordinate of the title. This can also be a string that looks like this: "+10" or "-10" in which case it's added to the calculated position.
Default: null

titleY
The specific y-axis coordinate of the title. This can also be a string that looks like this: "+10" or "-10" in which case it's added to the calculated position.
Default: +5 (a string)

titleOffsetx
An offset value that is added to the calculated x-axis coordinate.
Default: 0

titleOffsety
An offset value that is added to the calculated y-axis coordinate.
Default: 0

titleHalign
The horizontal alignment of the title.
Default: center

titleColor
The color of the title.
Default: null

titleFont
The font used to render the title.
Default: null

titleSize
The size of the font used to render the title.
Default: null

titleBold
Whether the title is bold or not.
Default: null

titleItalic
Whether the title is italic or not.
Default: null

titleSubtitle
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: (An empty string)

titleSubtitleColor
The color of the subtitle.
Default: #aaa

titleSubtitleFont
The font used to render the subtitle.
Default: null

titleSubtitleSize
The size of the font used to render the subtitle.
Default: null

titleSubtitleBold
Whether the subtitle is bold or not.
Default: null

titleSubtitleItalic
Whether the subtitle is italic or not.
Default: null

Tickmark properties

PropertyDescriptionDefault
tickmarksOuterSizeThe size of the outer axis tickmarks.3
tickmarksInnerSizeThe size of the inner axis tickmarks.3
tickmarksCountThe number of tickmarks that are displayed.10
tickmarksOuterSize
The size of the outer axis tickmarks.
Default: 3

tickmarksInnerSize
The size of the inner axis tickmarks.
Default: 3

tickmarksCount
The number of tickmarks that are displayed.
Default: 10

Other properties

PropertyDescriptionDefault
linewidthThe linewidth of the axes.1
innerGapThe size of the gap between the inner and outer circular axes.5
needleColorThis is the color of the needle.#666
centerpinRadiusThe radius of the circle that's at the center of the chart.5
adjustableIf true then the gauge will be adjustable by clicking on it to select the value.false
responsiveThis 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.null
linewidth
The linewidth of the axes.
Default: 1

innerGap
The size of the gap between the inner and outer circular axes.
Default: 5

needleColor
This is the color of the needle.
Default: #666

centerpinRadius
The radius of the circle that's at the center of the chart.
Default: 5

adjustable
If true then the gauge will be adjustable by clicking on it to select the value.
Default: false

responsive
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)

This can be used to get properties if necessary. It's normally used after the chart is drawn if you need to get parameters (if you're doing custom coding for example).

obj.set(name, value)

This can be used to set properties if necessary. It's normally used after the chart is drawn if you need to set additional parameters or change them.

obj.on(event, handler)

This function adds an event listener (such as beforedraw or draw) to the chart object. For example:

obj.on('draw', function (obj)
{
    // Put your code here
});
obj.exec(func)

This function can be used to execute a function (immediately). It's not event-based (ie it doesn't run when something happens) - it just runs immediately - and only once. You might use it when you need to get something from the chart when it's drawn and then call the redraw function. Because this function only runs once the RGraph.SVG.redraw function would not cause a loop - which would happen if you used the draw event.

obj.exec(function (obj)
{
    // Put your code 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.

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.SVG.Gauge({
    id: 'chart-container',
    innerMin: 0,
    innerMax: 100,
    outerMin: 0,
    outerMax: 10,
    value: 78,
    options: {
    }
}).on('draw', function (obj)
{
    console.log('The draw event has fired');
    
}).draw();