Indicators in JavaScript

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


Plotly is known for its graphing libraries, but it's also a broader ecosystem for building interactive data apps, AI data analysis tools, and deploying and hosting Dash apps. Explore the full set of tools and platforms designed to help turn data into action. Discover Plotly.

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);
</script>\n</head>\n\n<body>\n\t<div id='myDiv'><!-- Plotly chart will be drawn inside this DIV --></div>\n</body>","js":"var data = [\n {\n type: \"indicator\",\n value: 200,\n delta: { reference: 160 },\n gauge: { axis: { visible: false, range: [0, 250] } },\n domain: { row: 0, column: 0 }\n },\n {\n type: \"indicator\",\n value: 120,\n gauge: {\n shape: \"bullet\",\n axis: {\n visible: false,\n range: [-200, 200]\n }\n },\n domain: { x: [0.1, 0.5], y: [0.15, 0.35] }\n },\n {\n type: \"indicator\",\n mode: \"number+delta\",\n value: 300,\n domain: { row: 0, column: 1 }\n },\n { type: \"indicator\", mode: \"delta\", value: 40, domain: { row: 1, column: 1 } }\n];\n\nvar layout = {\n width: 600,\n height: 400,\n margin: { t: 25, b: 25, l: 25, r: 25 },\n grid: { rows: 2, columns: 2, pattern: \"independent\" },\n template: {\n data: {\n indicator: [\n {\n title: { text: \"Speed\" },\n mode: \"number+delta+gauge\",\n delta: { reference: 90 }\n }\n ]\n }\n }\n};\n\nPlotly.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);
</script>\n</head>\n\n<body>\n\t<div id='myDiv'><!-- Plotly chart will be drawn inside this DIV --></div>\n</body>","js":"var data = [\n {\n domain: { x: [0, 1], y: [0, 1] },\n value: 450,\n title: { text: \"Speed\" },\n type: \"indicator\",\n mode: \"gauge+number\",\n delta: { reference: 400 },\n gauge: { axis: { range: [null, 500] } }\n }\n];\n\nvar layout = { width: 600, height: 400 };\nPlotly.newPlot('myDiv', data, layout);\n"}">

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

</script>\n</head>\n\n<body>\n\t<div id='myDiv'><!-- Plotly chart will be drawn inside this DIV --></div>\n</body>","js":"var data = [\n {\n type: \"indicator\",\n mode: \"number+gauge+delta\",\n gauge: { shape: \"bullet\" },\n delta: { reference: 300 },\n value: 220,\n domain: { x: [0, 1], y: [0, 1] },\n title: { text: \"Profit\" }\n }\n];\n\nvar layout = { width: 600, height: 250 };\nPlotly.newPlot('myDiv', data, layout);\n\n"}">

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" },
    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);
</script>\n</head>\n\n<body>\n\t<div id='myDiv'><!-- Plotly chart will be drawn inside this DIV --></div>\n</body>","js":"var data = [\n {\n type: \"indicator\",\n mode: \"number+delta\",\n value: 492,\n delta: { reference: 512, valueformat: \".0f\" },\n domain: { y: [0, 1], x: [0.25, 0.75] },\n title: { text: \"Users online\" }\n },\n {\n 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]\n }\n];\n\nvar layout = { width: 600, height: 450, xaxis: { range: [0, 62] } };\nPlotly.newPlot('myDiv', data, layout);\n"}">

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

</script>\n</head>\n\n<body>\n\t<div id='myDiv'><!-- Plotly chart will be drawn inside this DIV --></div>\n</body>","js":"var data = [\n {\n type: \"indicator\",\n mode: \"number+delta\",\n value: 400,\n number: { prefix: \"$\" },\n delta: { position: \"top\", reference: 320 },\n domain: { x: [0, 1], y: [0, 1] }\n }\n];\n\nvar layout = {\n paper_bgcolor: \"lightgray\",\n width: 600,\n height: 200,\n margin: { t: 0, b: 0, l: 0, r: 0 }\n};\n\nPlotly.newPlot('myDiv', data, layout);\n\n"}">

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

</script>\n</head>\n\n<body>\n\t<div id='myDiv'><!-- Plotly chart will be drawn inside this DIV --></div>\n</body>","js":"var data = [\n {\n type: \"indicator\",\n mode: \"number+delta\",\n value: 200,\n domain: { x: [0, 0.5], y: [0, 0.5] },\n delta: { reference: 400, relative: true, position: \"top\" }\n },\n {\n type: \"indicator\",\n mode: \"number+delta\",\n value: 350,\n delta: { reference: 400, relative: true },\n domain: { x: [0, 0.5], y: [0.5, 1] }\n },\n {\n type: \"indicator\",\n mode: \"number+delta\",\n value: 450,\n title: {\n text:\n \"Accounts<br><span style='font-size:0.8em;color:gray'>Subtitle</span><br><span style='font-size:0.8em;color:gray'>Subsubtitle</span>\"\n },\n delta: { reference: 400, relative: true },\n domain: { x: [0.6, 1], y: [0, 1] }\n }\n];\n\nvar layout = {\n width: 600,\n height: 400,\n margin: { t: 25, r: 25, l: 25, b: 25 }\n};\n\nPlotly.newPlot('myDiv', data, layout);\n\n"}">