Wijmo

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.
HTML
<div id="gsLinearGauge"></div> <div id="gsRadialGauge"></div> <div class="app-input-group"> <label>Gauge Value</label> <input id="gsValue"/> </div>
JS
var gsLinearGauge = new wijmo.gauge.LinearGauge('#gsLinearGauge', { value: props.value, min: props.min, max: props.max, format: props.format, }); var gsRadialGauge = new wijmo.gauge.RadialGauge('#gsRadialGauge', { value: props.value, min: props.min, max: props.max, format: props.format, }); var gsValueInput = new wijmo.input.InputNumber('#gsValue', { value: props.value, min: props.min, max: props.max, format: props.format, step: props.step, valueChanged: function (s, e) { gsLinearGauge.value = s.value; gsRadialGauge.value = s.value; } });

Result (live):

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:

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

HTML
<div id="dvLinearGauge"></div> <div id="dvRadialGauge"></div> <div class="app-input-group"> <label>Gauge Value</label> <input id="dvValue" type="text" /> </div> <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>
JS
var dvLinearGauge = new wijmo.gauge.LinearGauge('#dvLinearGauge', { value: props.value, min: props.min, max: props.max, format: props.format, showText: props.showText }); var dvRadialGauge = new wijmo.gauge.RadialGauge('#dvRadialGauge', { value: props.value, min: props.min, max: props.max, format: props.format, showText: props.showText }); var dvValueInput = new wijmo.input.InputNumber('#dvValue', { value: props.value, min: props.min, max: props.max, format: props.format, step: props.step, valueChanged: function (s, e) { dvLinearGauge.value = s.value; dvRadialGauge.value = s.value; } }); var showTextMenu = new wijmo.input.Menu('#dvShowTextMenu', { selectedIndexChanged: function (s, e) { if (s.selectedValue) { dvLinearGauge.showText = s.selectedValue; dvRadialGauge.showText = s.selectedValue; s.header = '<b>Show Text</b>: ' + s.text; } }, selectedValue: props.showText });

Result (live):

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.

HTML
<div id="urLinearGauge"></div> <div id="urBulletGraph"></div> <div id="urRadialGauge"></div> <div class="app-input-group"> <label>Gauge Value</label> <input id="urValue" type="text" /> </div> <label> Show Ranges  <input id="urShowRanges" type="checkbox" /> </label>
JS
// create the ranges var lowerRange = new wijmo.gauge.Range(props.ranges.lower), middleRange = new wijmo.gauge.Range(props.ranges.middle), upperRange = new wijmo.gauge.Range(props.ranges.upper); // create the gauges var urLinearGauge = new wijmo.gauge.LinearGauge('#urLinearGauge', { value: props.value, min: props.min, max: props.max, format: props.format, pointer: { thickness: props.ranges.pointerThickness }, ranges: [ lowerRange, middleRange, upperRange ] }); var urBulletGraph = new wijmo.gauge.BulletGraph('#urBulletGraph', { value: props.value, min: props.min, max: props.max, format: props.format, good: props.ranges.middle.max, bad: props.ranges.middle.min, target: props.ranges.target }); var urRadialGauge = new wijmo.gauge.RadialGauge('#urRadialGauge', { value: props.value, min: props.min, max: props.max, format: props.format, pointer: { thickness: props.ranges.pointerThickness }, ranges: [ lowerRange, middleRange, upperRange ] }); // change value var urValueInput = new wijmo.input.InputNumber('#urValue', { value: props.value, min: props.min, max: props.max, format: props.format, step: props.step, valueChanged: function (s, e) { urLinearGauge.value = s.value; urBulletGraph.value = s.value; urRadialGauge.value = s.value; } }); // showRanges checkbox var showRanges = document.getElementById('urShowRanges'); showRanges.checked = props.showRanges; showRanges.addEventListener('click', function (e) { var show = e.target.checked; urLinearGauge.showRanges = show; urBulletGraph.showRanges = show; urRadialGauge.showRanges = show; });

Result (live):

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. All angles are measured clockwise, starting at 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.

HTML
<div id="asRadialGauge"></div> <div class="app-input-group"> <label>Gauge Value</label> <input id="asValue" type="text" /> </div> <div class="app-input-group"> <label>Start Angle</label> <input id="asStartAngle" type="text" /> </div> <div class="app-input-group"> <label>Sweep Angle</label> <input id="asSweepAngle" type="text" /> </div> <label> Auto-Scale  <input id="asAutoScale" type="checkbox" /> </label>
JS
var asRadialGauge = new wijmo.gauge.RadialGauge('#asRadialGauge', { value: props.value, min: props.min, max: props.max, format: props.format, startAngle: props.startAngle, sweepAngle: props.sweepAngle, autoScale: props.autoScale }); var asValueInput = new wijmo.input.InputNumber('#asValue', { value: props.value, min: props.min, max: props.max, format: props.format, step: props.step, valueChanged: function (s, e) { asRadialGauge.value = s.value; } }); var asStartAngleInput = new wijmo.input.InputNumber('#asStartAngle', { value: props.startAngle, min: -360, max: 360, step: 45, valueChanged: function (s, e) { asRadialGauge.startAngle = s.value; } }); var asSweepAngleInput = new wijmo.input.InputNumber('#asSweepAngle', { value: props.sweepAngle, min: 0, max: 360, step: 45, valueChanged: function (s, e) { asRadialGauge.sweepAngle = s.value; } }); // toggle autoScale property var asAutoScaleInput = document.getElementById('asAutoScale'); asAutoScaleInput.checked = props.autoScale; asAutoScaleInput.addEventListener('click', function (e) { asRadialGauge.autoScale = e.target.checked; });

Result (live):

Gauge 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:

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

HTML
<div class="row"> <div class="direction-col"> <div id="dLinearGauge"></div> </div> <div class="direction-col"> <div id="dBulletGraph"></div> </div> </div> <div class="app-input-group"> <label>Gauge Value</label> <input id="dValue" type="text" /> </div> <select id="dDirection"> <option value="Up">Up</option> <option value="Right">Right</option> <option value="Down">Down</option> <option value="Left">Left</option> </select>
JS
var dLinearGauge = new wijmo.gauge.LinearGauge('#dLinearGauge', { value: props.value, min: props.min, max: props.max, format: props.format, pointer: { thickness: props.ranges.pointerThickness }, ranges: [ lowerRange, middleRange, upperRange ] }); var dBulletGraph = new wijmo.gauge.BulletGraph('#dBulletGraph', { value: props.value, min: props.min, max: props.max, format: props.format, good: props.ranges.middle.max, bad: props.ranges.middle.min, target: props.ranges.target }); var dValueInput = new wijmo.input.InputNumber('#dValue', { value: props.value, min: props.min, max: props.max, format: props.format, step: props.step, valueChanged: function (s, e) { dLinearGauge.value = s.value; dBulletGraph.value = s.value; } }); var dDirection = new wijmo.input.Menu('#dDirection', { selectedIndexChanged: function (s, e) { if (s.selectedValue) { var direction = s.selectedValue, vertical = direction.match(/Up|Down/i) != null; // update gauge direction dLinearGauge.direction = direction; dBulletGraph.direction = direction; // update CSS wijmo.toggleClass(dLinearGauge.hostElement, 'vertical-gauge', vertical); wijmo.toggleClass(dBulletGraph.hostElement, 'vertical-gauge', vertical); var dirCols = document.querySelectorAll('.direction-col'); for (var i = 0; i < dirCols.length; i++) { wijmo.toggleClass(dirCols[i], 'col-md-6', vertical); } // update menu text s.header = '<b>Direction</b>: ' + s.text; } }, selectedValue: props.direction });
CSS
.vertical-gauge { height: 300px; width: 1.2em; margin-left: auto; margin-right: auto; }

Result (live):

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 and RadialGauge controls, and added a CSS rule to create an orange pointer for both.

HTML
<div id="sLinearGauge" class="custom-gauge"></div> <div id="sRadialGauge" class="custom-gauge"></div> <div class="app-input-group"> <label>Gauge Value</label> <input id="sValue" type="text" /> </div>
JS
var sLinearGauge = new wijmo.gauge.LinearGauge('#sLinearGauge', { value: props.value, min: props.min, max: props.max, format: props.format, showText: 'Value' }); var sRadialGauge = new wijmo.gauge.RadialGauge('#sRadialGauge', { value: props.value, min: props.min, max: props.max, format: props.format, showText: 'Value' }); var sValueInput = new wijmo.input.InputNumber('#sValue', { value: props.value, min: props.min, max: props.max, format: props.format, step: props.step, valueChanged: function (s, e) { sLinearGauge.value = s.value; sRadialGauge.value = s.value; } });
CSS
/* orange gauge pointer */ .wj-gauge.custom-gauge .wj-pointer { fill: #ffa500; stroke: #cd853f; }

Result (live):

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.

HTML
<div id="evLinearGauge"></div> <div id="evRadialGauge"></div> <label> isReadOnly  <input id="evReadOnly" type="checkbox" /> </label>
JS
var evLinearGauge = new wijmo.gauge.LinearGauge('#evLinearGauge', { value: props.value, min: props.min, max: props.max, format: props.format, isReadOnly: props.isReadOnly, step: props.step, valueChanged: function (s, e) { evRadialGauge.value = s.value; } }); var evRadialGauge = new wijmo.gauge.RadialGauge('#evRadialGauge', { value: props.value, min: props.min, max: props.max, format: props.format, isReadOnly: props.isReadOnly, step: props.step, valueChanged: function (s, e) { evLinearGauge.value = s.value; } }); // toggle isReadOnly property var isReadOnly = document.getElementById('evReadOnly'); isReadOnly.checked = props.isReadOnly; isReadOnly.addEventListener('click', function (e) { var isReadOnly = e.target.checked; evLinearGauge.isReadOnly = isReadOnly; evRadialGauge.isReadOnly = isReadOnly; });

Result (live):

Custom SVG Elements

By default, Wijmo's radial gauges use a colored sector and a text element to indicate the gauge's current value. This results in a clean and easy-to read look.

If you prefer a more traditional needle-style pointer, you can add an extra SVG shape to the control and apply a transform to move the needle.

HTML
<div id="csvgRadialGauge"></div>
JS
var csvgRadialGauge = new wijmo.gauge.RadialGauge('#csvgRadialGauge', { min: 0, max: 100, value: 25, startAngle: -45, sweepAngle: 270, showTicks: true, tickSpacing: 10, showText: 'Value', isReadOnly: false, refreshed: updateNeedle, valueChanged: updateNeedle }); // update needle element when gauge size or value change // rounded (drop-shaped) needle function updateNeedle(gauge) { // add needle element if necessary var needle = gauge.hostElement.querySelector('.needle'), cap = gauge.hostElement.querySelector('.cap'); if (!needle) { var svg = gauge.hostElement.querySelector('svg'); needle = document.createElementNS('http://www.w3.org/2000/svg', 'path'); wijmo.addClass(needle, 'needle'); svg.appendChild(needle); cap = document.createElementNS('http://www.w3.org/2000/svg', 'circle'); wijmo.addClass(cap, 'cap'); svg.appendChild(cap); } // update needle parameters var args = getArgs(gauge); needle.setAttribute('d', wijmo.format('M {lft} {y} A {wid} {wid} 0 0 0 {rgt} {y} L {x} {top} Z', args)); needle.setAttribute('transform', wijmo.format('rotate({angle} {x} {y})', args)); cap.setAttribute('cx', args.x); cap.setAttribute('cy', args.y); cap.setAttribute('r', args.capRadius); } // get arguments needed for the needle element function getArgs(gauge) { var rc = gauge.clientSize, cx = rc.width / 2, cy = rc.height / 2, r = Math.min(rc.width, rc.height) / 2, wid = r / 10, pct = (gauge.value - gauge.min) / (gauge.max - gauge.min), angle = gauge.startAngle + gauge.sweepAngle * wijmo.clamp(pct, 0, 1) - 90; return { angle: angle, x: cx.toFixed(4), y: cy.toFixed(4), wid: wid.toFixed(4), capRadius: (wid * 1.2).toFixed(4), lft: (cx - wid).toFixed(4), rgt: (cx + wid).toFixed(4), top: (cy - r).toFixed(4), bot: (cy + wid).toFixed(4) } }
CSS
.wj-radialgauge .needle { /* pointer needle */ fill: orange; stroke: black; stroke-width: 1px; transition: transform 400ms; } .wj-radialgauge .cap { /* needle cap */ fill: orange; stroke: black; stroke-width: 2px; } #csvgRadialGauge .wj-value { /* move value text down */ transform: translateY(1.75em) }

Result (live):