Show Sidebar Hide Sidebar
Plotly.js

Indicators in JavaScript

How to make a D3.js-based gauge chart in javascript.

In this tutorial we introduce a new trace named "Indicator". The purpose of "indicator" is to visualize a single value specified by the "value" attribute. Three distinct visual elements are available to represent that value: number, delta and gauge. Any combination of them can be specified via the "mode" attribute. Top-level attributes are:

  1. value: the value to visualize
  2. mode: which visual elements to draw
  3. align: how to align number and delta (left, center, right)
  4. domain: the extent of the figure

Then we can configure the 3 different visual elements via their respective container:

  1. number is simply a representation of the number in text. It has attributes:
  2. valueformat: to format the number
  3. prefix: a string before the number
  4. suffix: a string after the number
  5. font.(family|size): to control the font
"delta" simply displays the difference between the value with respect to a reference. It has attributes:
  1. reference: the number to compare the value with
  2. relative: whether that difference is absolute or relative
  3. valueformat: to format the delta
  4. (increasing|decreasing).color: color to be used for positive or decreasing delta
  5. (increasing|decreasing).symbol: symbol displayed on the left of the delta
  6. font.(family|size): to control the font
  7. position: position relative to number (either top, left, bottom, right)
Finally, we can have a simple title for the indicator via title with 'text' attribute which is a string, and 'align' which can be set to left, center, and right. There are two gauge types: angular and bullet. Here is a combination of both shapes (angular, bullet), and different modes (guage, delta, and value):

var data = [
  {
    type: "indicator",
    value: 200,
    delta: { reference: 160 },
    gauge: { axis: { visible: false, range: [0, 250] } },
    domain: { row: 0, column: 0 }
  },
  {
    type: "indicator",
    value: 120,
    gauge: {
      shape: "bullet",
      axis: {
        visible: false,
        range: [-200, 200]
      }
    },
    domain: { x: [0.1, 0.5], y: [0.15, 0.35] }
  },
  {
    type: "indicator",
    mode: "number+delta",
    value: 300,
    domain: { row: 0, column: 1 }
  },
  { type: "indicator", mode: "delta", value: 40, domain: { row: 1, column: 1 } }
];

var layout = {
  width: 600,
  height: 400,
  margin: { t: 25, b: 25, l: 25, r: 25 },
  grid: { rows: 2, columns: 2, pattern: "independent" },
  template: {
    data: {
      indicator: [
        {
          title: { text: "Speed" },
          mode: "number+delta+gauge",
          delta: { reference: 90 }
        }
      ]
    }
  }
};

Plotly.newPlot('myDiv', data, layout);
var data = [
  {
    domain: { x: [0, 1], y: [0, 1] },
    value: 450,
    title: { text: "Speed" },
    type: "indicator",
    mode: "gauge+number",
    delta: { reference: 400 },
    gauge: { axis: { range: [null, 500] } }
  }
];

var layout = { width: 600, height: 400 };
Plotly.newPlot('myDiv', data, layout);

The equivalent of above "angular gauge":

var data = [
  {
    type: "indicator",
    mode: "number+gauge+delta",
    gauge: { shape: "bullet" },
    delta: { reference: 300 },
    value: 220,
    domain: { x: [0, 1], y: [0, 1] },
    title: { text: "Profit" }
  }
];

var layout = { width: 600, height: 250 };
Plotly.newPlot('myDiv', data, layout);

Another interesting feature is that indicator trace sits above the other traces (even the 3d ones). This way, it can be easily used as an overlay as demonstrated below:

var data = [
  {
    type: "indicator",
    mode: "number+delta",
    value: 492,
    delta: { reference: 512, valueformat: ".0f" },
    ticker: { showticker: true },
    vmax: 500,
    domain: { y: [0, 1], x: [0.25, 0.75] },
    title: { text: "Users online" }
  },
  {
    y: [325, 324, 405, 400, 424, 404, 417, 432, 419, 394, 410, 426, 413, 419, 404, 408, 401, 377, 368, 361, 356, 359, 375, 397, 394, 418, 437, 450, 430, 442, 424, 443, 420, 418, 423, 423, 426, 440, 437, 436, 447, 460, 478, 472, 450, 456, 436, 418, 429, 412, 429, 442, 464, 447, 434, 457, 474, 480, 499, 497, 480, 502, 512, 492]
  }
];

var layout = { width: 600, height: 450, xaxis: { range: [0, 62] } };
Plotly.newPlot('myDiv', data, layout);

Data card helps to display more contextual information about the data. Sometimes one number is all you want to see in a report, such as total sales, annual revenue, etc. This example shows how to visualize these big numbers:

var data = [
  {
    type: "indicator",
    mode: "number+delta",
    value: 400,
    number: { prefix: "$" },
    delta: { position: "top", reference: 320 },
    domain: { x: [0, 1], y: [0, 1] }
  }
];

var layout = {
  paper_bgcolor: "lightgray",
  width: 600,
  height: 200,
  margin: { t: 0, b: 0, l: 0, r: 0 }
};

Plotly.newPlot('myDiv', data, layout);

It's possible to display several numbers

var data = [
  {
    type: "indicator",
    mode: "number+delta",
    value: 200,
    domain: { x: [0, 0.5], y: [0, 0.5] },
    delta: { reference: 400, relative: true, position: "top" }
  },
  {
    type: "indicator",
    mode: "number+delta",
    value: 350,
    delta: { reference: 400, relative: true },
    domain: { x: [0, 0.5], y: [0.5, 1] }
  },
  {
    type: "indicator",
    mode: "number+delta",
    value: 450,
    title: {
      text:
        "Accounts<br><span style='font-size:0.8em;color:gray'>Subtitle</span><br><span style='font-size:0.8em;color:gray'>Subsubtitle</span>"
    },
    delta: { reference: 400, relative: true },
    domain: { x: [0.6, 1], y: [0, 1] }
  }
];

var layout = {
  width: 600,
  height: 400,
  margin: { t: 25, r: 25, l: 25, b: 25 }
};

Plotly.newPlot('myDiv', data, layout);

plotly.js runs on all SVG-compatible browsers