# Gauge 101

This page shows how to get started with Wijmo's Gauge controls.

## Getting Started

Steps for getting started with the Gauge control in JavaScript applications:

1. Add references to Wijmo.
2. Add markup to serve as the Wijmo control's host.
3. Initialize the Wijmo control(s) via JavaScript.
4. (Optional) Add some CSS to customize the gauge control's appearance.

<!DOCTYPE html> <html> <head> <link rel="stylesheet" type="text/css" href="css/bootstrap.css"/> <link rel="stylesheet" type="text/css" href="css/wijmo.css" /> <link href="css/app.css" rel="stylesheet" type="text/css" /> <script src="scripts/wijmo.js" type="text/javascript"></script> <script src="scripts/wijmo.input.js" type="text/javascript"></script> <script src="scripts/wijmo.gauge.js" type="text/javascript"></script> <script src="scripts/app.js" type="text/javascript"></script> </head> <body> <!-- LinearGauge --> <div id="gsLinearGauge"></div> <!-- RadialGauge --> <div id="gsRadialGauge"></div> <!-- InputNumber --> <div> <label>Gauge Value</label> <input id="gsValue" type="text" /> </div> </body> </html>
// init Wijmo controls var linearGauge = new wijmo.gauge.LinearGauge('#gsLinearGauge'), radialGauge = new wijmo.gauge.RadialGauge('#gsRadialGauge'), valueInput = new wijmo.input.InputNumber('#gsValue'); // LinearGauge - set properties linearGauge.value = props.value; linearGauge.min = props.min; linearGauge.max = props.max; linearGauge.format = props.format; // Radial Gauge - set properties radialGauge.value = props.value; radialGauge.min = props.min; radialGauge.max = props.max; radialGauge.format = props.format; // InputNumber - set properties valueInput.value = props.value; valueInput.min = props.min; valueInput.max = props.max; valueInput.format = props.format; valueInput.step = props.step; // InputNumber valueChanged event valueInput.valueChanged.addHandler(function (sender) { // update Gauge.value when InputNumber.value changes linearGauge.value = sender.value; radialGauge.value = sender.value; });

#### Result (live):

Gauge Value

## Displaying Values

The gauge controls offer a showText property that determines which values should should be displayed as text by the gauge. There are four valid values for the showText property:

- Value: Display the Gauge's current value.
- MinMax: Display the Gauge's current min and max values.
- All: Display the Gauge's current min, max, and values. This option is a combination of the Value and MinMax options.
- None: Do not display any text in the Gauge control.

The example below allows you to see what happens when the showText property is changed.

<div id="dvLinearGauge"></div> <div id="dvRadialGauge"></div> <!-- "Gauge Value" input omitted --> <select id="dvShowTextMenu"> <option value="Value">Value</option> <option value="MinMax">Min/Max</option> <option value="All">All</option> <option value="None">None</option> </select>
// init Wijmo controls var linearGauge = new wijmo.gauge.LinearGauge('#dvLinearGauge'), radialGauge = new wijmo.gauge.RadialGauge('#dvRadialGauge'), valueInput = new wijmo.input.InputNumber('#dvValue'), showTextMenu = new wijmo.input.Menu('#dvShowTextMenu'); // LinearGauge - set properties // format, min, max, and value omitted for brevity - identical to "Getting Started" linearGauge.showText = props.showText; // Radial Gauge - set properties // format, min, max, and value omitted for brevity - identical to "Getting Started" radialGauge.showText = props.showText; // InputNumber - set properties // omitted for brevity - identical to "Getting Started" // set Menu properties showTextMenu.selectedValue = props.showText; showTextMenu.selectedIndexChanged.addHandler(function (sender) { // make sure a value is selected if (!sender.selectedValue) return; // update Gauges' showText property linearGauge.showText = sender.selectedValue; radialGauge.showText = sender.selectedValue; });

#### Result (live):

Gauge Value

## Using Ranges

All Wijmo gauges have a ranges property that contains an array of Range objects. By default, the ranges are displayed on the face of gauge to indicate zones of interest; however, the showRanges property can be used to to hide the ranges. Instead, the gauge will determine which range contains the current gauge value and will apply that range's color to the gauge pointer.

The Range object itself offers properties such as min, max, and color to customize each zone.

The following example demonstrates how to use ranges with the LinearGauge, RadialGauge, and BulletGraph.

<div id="urLinearGauge"></div> <div id="urBulletGraph"></div> <div id="urRadialGauge"></div> <!-- "Gauge Value" input omitted --> <label> Show Ranges&nbsp; <input id="urShowRanges" type="checkbox" /> </label>
// init Wijmo controls var linearGauge = new wijmo.gauge.LinearGauge('#urLinearGauge'), bulletGraph = new wijmo.gauge.BulletGraph('#urBulletGraph'), radialGauge = new wijmo.gauge.RadialGauge('#urRadialGauge'), valueInput = new wijmo.input.InputNumber('#urValue'), showRanges = document.getElementById('urShowRanges'),, lowerRange = new wijmo.gauge.Range(), middleRange = new wijmo.gauge.Range(), upperRange = new wijmo.gauge.Range(); // set Range propeties lowerRange.min = props.ranges.lower.min; lowerRange.max = props.ranges.lower.max; lowerRange.color = props.ranges.lower.color; middleRange.min = props.ranges.middle.min; middleRange.max = props.ranges.middle.max; middleRange.color = props.ranges.middle.color; upperRange.min = props.ranges.upper.min; upperRange.max = props.ranges.upper.max; upperRange.color = props.ranges.upper.color; // LinearGauge - set properties // format, min, max, and value omitted for brevity - identical to "Getting Started" linearGauge.pointer.thickness = props.ranges.pointerThickness; linearGauge.ranges.push(lowerRange); linearGauge.ranges.push(middleRange); linearGauge.ranges.push(upperRange); // set BulletGraph properties and add Range objects // format, min, max, and value omitted for brevity - identical to "Getting Started" bulletGraph.showRanges = props.showRanges; bulletGraph.pointer.thickness = props.ranges.pointerThickness; bulletGraph.good = props.ranges.middle.max; bulletGraph.bad = props.ranges.middle.min; bulletGraph.target = props.ranges.target; // Radial Gauge - set properties // format, min, max, and value omitted for brevity - identical to "Getting Started" radialGauge.showRanges = props.showRanges; radialGauge.pointer.thickness = props.ranges.pointerThickness; radialGauge.ranges.push(lowerRange); radialGauge.ranges.push(middleRange); radialGauge.ranges.push(upperRange); // InputNumber - set properties // omitted for brevity - identical to "Getting Started" // showRanges checkbox showRanges.checked = props.showRanges; showRanges.addEventListener('change', function() { // determine showRanges by checkbox's checked state var showRanges = this.checked; linearGauge.showRanges = showRanges; bulletGraph.showRanges = showRanges; radialGauge.showRanges = showRanges; linearGauge.pointer.thickness = showRanges ? 0.5 : 1; bulletGraph.pointer.thickness = showRanges ? 0.5 : 1; radialGauge.pointer.thickness = showRanges ? 0.5 : 1; });

#### Result (live):

Gauge Value
Show Ranges

## Automatic Scaling

The RadialGauge offers two properties to configure its layout, startAngle and sweepAngle. The startAngle property specifies the RadialGauge's starting angle, or rotation. The sweepAngle property specifies an angle representing the length of the RadialGauge's arc. The angle for both properties are measured clockwise, starting a the 9 o'clock position.

The RadialGauge also offers the autoScale property. When autoScale is set to true, the RadialGauge will be automatically scaled to fill its containing element.

The following example allows you to adjust the startAngle, sweepAngle, and autoScale properties in real-time.

<div id="asRadialGauge"></div> <!-- "Gauge Value" input omitted --> <div> <label>Start Angle</label> <input id="asStartAngle" type="text" /> </div> <div> <label>Sweep Angle</label> <input id="asSweepAngle" type="text" /> </div> <label> Auto-Scale&nbsp; <input id="asAutoScale" type="checkbox" /> </label>
// init Wijmo controls var radialGauge = new wijmo.gauge.RadialGauge('#asRadialGauge'), valueInput = new wijmo.input.InputNumber('#asValue'), startAngleInput = new wijmo.input.InputNumber('#asStartAngle'), sweepAngleInput = new wijmo.input.InputNumber('#asSweepAngle'), autoScaleInput = document.getElementById('asAutoScale'); // Radial Gauge - set properties // format, min, max, and value omitted for brevity - identical to "Getting Started" radialGauge.autoScale = props.autoScale; // InputNumber - set properties // omitted for brevity - identical to "Getting Started" // StartAngle - set InputNumber properties startAngleInput.value = props.startAngle; startAngleInput.min = -360; startAngleInput.max = 360; startAngleInput.step = 45; startAngleInput.valueChanged.addHandler(function (sender) { // update gauge's startAngle property radialGauge.startAngle = sender.value; }); // SweepAngle - set InputNumber properties sweepAngleInput.value = props.sweepAngle; sweepAngleInput.min = 0; sweepAngleInput.max = 360; sweepAngleInput.step = 45; sweepAngleInput.valueChanged.addHandler(function (sender) { // update gauge's sweepAngle property radialGauge.sweepAngle = sender.value; }); // AutoScale - set CheckBox properties autoScaleInput.checked = props.autoScale; autoScaleInput.addEventListener('change', function () { // update gauge's autoScale property based on // checkbox's checked state radialGauge.autoScale = this.checked; });

#### Result (live):

Gauge Value
Start Angle
Sweep Angle
Auto-Scale

## Direction

The RadialGauge's startAngle and sweepAngle properties do not apply to the LinearGauge or BulletGraph. Instead, the LinearGauge and BulletGraph offer the direction property to determine how the should be displayed. There are four options for the direction property:

- Up: The gauge is rendered vertically and its value increases from bottom to top.
- Right: The gauge is rendered horizontally and its value increases from right to left. This is the default value.
- Down: The gauge is rendered vertically and its value increases from top to bottom.
- Left: The gauge is rendered horizontally and its value increases from left to right.

The example below allows you to see what happens when the direction property is changed.

<div class="row"> <div class="direction-col"> <div id="dLinearGauge"></div> </div> <div class="direction-col"> <div id="dBulletGraph"></div> </div> </div> <!-- "Gauge Value" input omitted --> <select id="dDirection"> <option value="Up">Up</option> <option value="Right">Right</option> <option value="Down">Down</option> <option value="Left">Left</option> </select>
// init Wijmo controls var linearGauge = new wijmo.gauge.LinearGauge('#dLinearGauge'), bulletGraph = new wijmo.gauge.BulletGraph('#dBulletGraph'), valueInput = new wijmo.input.InputNumber('#dValue'), menu = new wijmo.input.Menu('#dDirection'), lowerRange = new wijmo.gauge.Range(), middleRange = new wijmo.gauge.Range(), upperRange = new wijmo.gauge.Range(); // set Range propeties lowerRange.min = props.ranges.lower.min; lowerRange.max = props.ranges.lower.max; lowerRange.color = props.ranges.lower.color; middleRange.min = props.ranges.middle.min; middleRange.max = props.ranges.middle.max; middleRange.color = props.ranges.middle.color; upperRange.min = props.ranges.upper.min; upperRange.max = props.ranges.upper.max; upperRange.color = props.ranges.upper.color; // LinearGauge - set properties // format, min, max, and value omitted for brevity - identical to "Getting Started" linearGauge.direction = props.direction; linearGauge.showRanges = props.showRanges; linearGauge.pointer.thickness = props.ranges.pointerThickness; linearGauge.ranges.push(lowerRange); linearGauge.ranges.push(middleRange); linearGauge.ranges.push(upperRange); // set BulletGraph properties and add Range objects // format, min, max, and value omitted for brevity - identical to "Getting Started" bulletGraph.direction = props.direction; bulletGraph.showRanges = props.showRanges; bulletGraph.pointer.thickness = props.ranges.pointerThickness; bulletGraph.good = props.ranges.middle.max; bulletGraph.bad = props.ranges.middle.min; bulletGraph.target = props.ranges.target; // InputNumber - set properties // omitted for brevity - identical to "Getting Started" // Direction - set Menu properties menu.selectedValue = props.direction; menu.selectedIndexChanged.addHandler(function (sender) { // make sure there is a selectedValue if (!sender.selectedValue) return; // get the data we need var direction = sender.selectedValue, vertical = direction.match(/Up|Down/i), dirCols = Array.prototype.slice.call(document.querySelectorAll('.direction-col')); // split or stack columns dirCols.forEach(function (el) { wijmo.toggleClass(el, 'col-md-6', vertical); }); // set Gauge.direction linearGauge.direction = direction; bulletGraph.direction = direction; // update gauge's CSS class wijmo.toggleClass(linearGauge.hostElement, 'vertical-gauge', vertical); wijmo.toggleClass(bulletGraph.hostElement, 'vertical-gauge', vertical); });
.vertical-gauge { height: 300px; width: 1.2em; }

#### Result (live):

Gauge Value

## Styling

The appearance of the gauge controls is largely defined in CSS. In addition to the default theme, we include several professionally designed themes that customize the appearance of all Wijmo controls to achieve a consistent, attractive look.

You can customize the appearance of the gauges using CSS. To do this, copy the CSS rules from the default theme to a new CSS file and modify the properties as needed.

In this example, we added the "custom-gauge" CSS class to the LinearGauge & RadialGauge, and define some CSS rules to create an orange pointer for both.

<div id="sLinearGauge" class="custom-gauge"></div> <div id="sRadialGauge" class="custom-gauge"></div> <!-- "Gauge Value" omitted for brevity -->
// init Wijmo controls var linearGauge = new wijmo.gauge.LinearGauge('#sLinearGauge'), radialGauge = new wijmo.gauge.RadialGauge('#sRadialGauge'), valueInput = new wijmo.input.InputNumber('#sValue'); // LinearGauge - set properties // format, min, max, and value omitted for brevity - identical to "Getting Started" linearGauge.showText = wijmo.gauge.ShowText.Value; // Radial Gauge - set properties // format, min, max, and value omitted for brevity - identical to "Getting Started" radialGauge.showText = wijmo.gauge.ShowText.Value; // InputNumber - set properties // omitted for brevity - identical to "Getting Started"
.custom-gauge .wj-pointer { fill: #ffa500; stroke: #cd853f; }

#### Result (live):

Gauge Value

## Editing Values

The gauge controls can be used as a simple indicator or as an input control when the isReadOnly property is set to false. The gauges also offer a step property that determines how much to add or subtract from its current value when being used as an input control.

The example below demonstrates how to use the isReadOnly and step properties with the LinearGauge and RadialGauge controls.

<div id="evLinearGauge"></div> <div id="evRadialGauge"></div> <label> Read-Only&nbsp; <input id="evReadOnly" type="checkbox" /> </label>
// init Wijmo controls var linearGauge = new wijmo.gauge.LinearGauge('#evLinearGauge'), radialGauge = new wijmo.gauge.RadialGauge('#evRadialGauge'), isReadOnly = document.getElementById('evReadOnly'); // LinearGauge - set properties // format, min, max, and value omitted for brevity - identical to "Getting Started" linearGauge.step = props.step; linearGauge.isReadOnly = props.isReadOnly; // Radial Gauge - set properties // format, min, max, and value omitted for brevity - identical to "Getting Started" radialGauge.step = props.step; radialGauge.isReadOnly = props.isReadOnly; // isReadonly - set CheckBox properties isReadOnly.checked = props.isReadOnly; isReadOnly.addEventListener('change', function () { // determine isReadOnly checkbox's checked state var isReadOnly = this.checked; // update gauges linearGauge.isReadOnly = isReadOnly; radialGauge.isReadOnly = isReadOnly; });

#### Result (live):

Read-Only