Canvas Gauges User Guide

Gauges As HTML Components

How to use canvas gauges as HTML components

Canvas gauges provides a declarative way to injection gauges into HTML-page. Each gauge is a simply HTML canvas element. When the custom element obtains attribute “data-type” with one of “linear-gauge” or “radial-gauge” values, it automatically becomes treated as gauge component and is rendered correspondingly.

Gauges support injection/modification of config options via adding/changing/removing configuration attributes at runtime. All configuration attributes should start with “data-“ prefix to produce valid HTML output. All attribute names correspondingly mapped into gauge configuration options.

Declaring Gauges

Zero-configuration gauge:

<script src="gauge.min.js"></script>
<canvas data-type="linear-gauge"></canvas>

With some configuration options:

<script src="gauge.min.js"></script>
<canvas data-type="linear-gauge"
        data-width="160"
        data-height="600"
        data-border-radius="0"
        data-borders="0"
        data-bar-begin-circle="25"
        data-minor-ticks="10"
        data-value="36.6"
        data-min-value="35"
        data-max-value="42"
        data-title="°C"
        data-major-ticks="35,36,37,38,39,40,41,42"
        data-ticks-width="18"
        data-ticks-width-minor="7.5"
        data-bar-width="5"
        data-highlights="false"
        data-color-value-box-shadow="false"
        data-value-box-stroke="0"
        data-color-value-box-background="false"
        data-value-int="2"
        data-value-dec="1"
></canvas>

Mutating Gauges

Canvas gauges support mutations at runtime, so you can easily re-configure gauge by simply changing attributes values. Even gauge type can be changed.

There are some configuration options which are defined for a certain type of gauge only. By the way even if you will declare attributes which gauge does not support it won’t break anything - them will just won’t be parsed and took into account during rendering. So switching gauge type in-runtime always safe.

For example:

<script src="gauge.min.js"></script>
<canvas data-type="linear-gauge"
        data-width="200"
        data-height="600"
></canvas>

<script>
var gaugeElement = document.getElementsByTagName('canvas')[0];

gaugeElement.setAttribute('data-border-radius', 20);
gaugeElement.setAttribute('data-color-numbers', 'red');
gaugeElement.setAttribute('data-type', 'radial-gauge');
gaugeElement.setAttribute('data-type', 'linear-gauge');
</script>

Configuration Attributes Mapping

When using HTML declarative configuration via attributes, mandatory “renderTo” configuration option is not required as far as gauge will be rendered to a proper canvas element directly.

OptionsAttributeGauge TypeValue Type
renderTo-anystring or HTMLCanvasElement
widthdata-widthanynumber
heightdata-heightanynumber
minValuedata-min-valueanynumber
maxValuedata-max-valueanynumber
valuedata-valueanynumber
titledata-titleanystring
unitsdata-unitsanystring
majorTicksdata-major-ticksanyarray of string or number
minorTicksdata-minor-ticksanyinteger
strokeTicksdata-stroke-ticksanyboolean
animatedValuedata-animated-valueanyboolean
bordersdata-bordersanyboolean
valueIntdata-value-intanyinteger
valueDecdata-value-decanyinteger
majorTicksIntdata-major-ticks-intanyinteger
majorTicksDecdata-major-ticks-decanyinteger
animationdata-animationanyboolean
animationDurationdata-animation-durationanynumber
animationRuledata-animation-ruleanystring or function
colorPlatedata-color-plateanystring
colorMajorTicksdata-color-major-ticksanystring
colorMinorTicksdata-color-minor-ticksanystring
colorTitledata-color-titleanystring
colorUnitsdata-color-unitsanystring
colorNumbersdata-color-numbersanystring
colorNeedledata-color-needleanystring
colorNeedleEnddata-color-needle-endanystring
colorValueTextdata-color-value-textanystring
colorValueTextShadowdata-color-value-text-shadowanystring
colorBorderShadowdata-color-border-shadowanystring
colorBorderOuterdata-color-border-outeranystring
colorBorderOuterEnddata-color-border-outer-endanystring
colorBorderMiddledata-color-border-middleanystring
colorBorderMiddleEnddata-color-border-middle-endanystring
colorBorderInnerdata-color-border-inneranystring
colorBorderInnerEnddata-color-border-inner-endanystring
colorValueBoxRectdata-color-value-box-rectanystring
colorValueBoxRectEnddata-color-value-box-rect-endanystring
colorValueBoxBackgrounddata-color-value-box-backgroundanystring
colorValueBoxShadowdata-color-value-box-shadowanystring
colorNeedleShadowUpdata-color-needle-shadow-upanystring
colorNeedleShadowDowndata-color-needle-shadow-downanystring
fontNumbersdata-font-numbersanystring
fontTitledata-font-titleanystring
fontUnitsdata-font-unitsanystring
fontValuedata-font-valueanystring
needledata-needleanyboolean
needleShadowdata-needle-shadowanyboolean
needleTypedata-needle-typeanystring
needleStartdata-needle-startanynumber
needleEnddata-needle-endanynumber
needleWidthdata-needle-widthanynumber
borderOuterWidthdata-border-outer-widthanynumber
borderMiddleWidthdata-border-middle-widthanynumber
borderInnerWidthdata-border-inner-widthanynumber
borderShadowWidthdata-border-shadow-widthanynumber
valueBoxdata-value-boxanyboolean
valueBoxStrokedata-value-box-strokeanynumber
valueTextdata-value-textanystring
valueTextShadowdata-value-text-shadowanyboolean
valueBoxBorderRadiusdata-value-box-border-radiusanynumber
highlightsdata-highlightsanyarray of { from: number, to: number, color: string }
borderRadiusdata-border-radiuslinearnumber
barBeginCircledata-bar-begin-circlelinearnumber
barWidthdata-bar-widthlinearnumber
barStrokeWidthdata-bar-stroke-widthlinearnumber
barProgressdata-bar-progresslinearboolean
colorBarStrokedata-color-bar-strokelinear 
colorBardata-color-barlinearstring
colorBarEnddata-color-bar-endlinearstring
colorBarProgressdata-color-bar-progresslinearstring
colorBarProgressEnddata-color-bar-progress-endlinearstring
tickSidedata-tick-sidelinearstring
needleSidedata-needle-sidelinearstring
numberSidedata-number-sidelinearstring
ticksWidthdata-ticks-widthlinearnumber
ticksWidthMinordata-ticks-width-minorlinearnumber
ticksPaddingdata-ticks-paddinglinearnumber
barLengthdata-bar-lengthlinearnumber
fontNumbersSizedata- font-numbers-sizelinearnumber
fontTitleSizedata-font-title-sizelinearnumber
fontUnitsSizedata-font-units-sizelinearnumber
ticksAngledata-ticks-angleradialnumber
startAngledata-start-angleradialnumber
colorNeedleCircleOuterdata-color-needle-circle-outerradialstring
colorNeedleCircleOuterEnddata-color-needle-circle-outer-endradialstring
colorNeedleCircleInnerdata-color-needle-circle-innerradialstring
colorNeedleCircleInnerEnddata-color-needle-circle-inner-endradialstring
needleCircleSizedata-needle-circle-sizeradialnumber
needleCircleInnerdata-needle-circle-innerradialboolean
needleCircleOuterdata-needle-circle-outerradialboolean
animationTargetdata-animation-targetradialstring

Read more: all configuration options