JavaScript ChartsLinear Gauge

Version 14.2.0

A Linear Gauge presents a single data point within a predefined range along a scale. The data is represented by a bar indicating the value.

Simple Linear Gauge Copy Link

main.ts

import {
  AgCharts,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",

  value: 80,
  scale: {
    min: 0,
    max: 100,
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

To create a Linear Gauge, use the createGauge API with the type linear-gauge.

const options = {
    type: 'linear-gauge',
    container: document.getElementById('myChart'),
    value: 80,
    scale: {
        min: 0,
        max: 100,
    },
};

AgCharts.createGauge(options);

In this configuration:

value is the value displayed by the gauge.
scale.min defines the minimum value of the scale.
scale.max defines the maximum value of the scale.
The data is represented by a coloured bar displayed over a grey scale.

Horizontal Linear Gauge Copy Link

main.ts

import {
  AgCharts,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",
  direction: "horizontal",

  value: 80,
  scale: {
    min: 0,
    max: 100,
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

To create a Horizontal Linear Gauge, set direction: 'horizontal'.

{
    direction: 'horizontal',
}

Customisation Copy Link

Thickness Copy Link

main.ts

import {
  AgCharts,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",
  direction: "horizontal",

  value: 80,
  thickness: 100,
  bar: {
    thickness: 50,
  },
  scale: {
    min: 0,
    max: 100,
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

{
    thickness: 100,
    bar: {
        thickness: 50,
    },
}

In the above configuration:

The thickness of the scale is specified as 100 pixels.
The thickness of the bar is specified as 50 pixels.
It is also possible to use thicknessRatio to specify the width of the bar as a proportion of the scale.

Labels Copy Link

A label can be configured with the label property.

main.ts

import {
  AgCharts,
  AgLinearGaugeLabelPlacement,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",

  direction: "horizontal",
  value: 50,
  scale: {
    min: 0,
    max: 100,
    label: {
      enabled: false,
    },
  },
  label: {
    enabled: true,
    placement: "inside-start",
    avoidCollisions: true,
    color: { ref: "textColor" },
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

function setLabelPlacement(placement: AgLinearGaugeLabelPlacement) {
  options.label!.placement = placement;

  chart.update(options);
}

function setAvoidCollisions(avoidCollisions: boolean) {
  options.label!.avoidCollisions = avoidCollisions;

  chart.update(options);
}

function setValue(value: string) {
  document.getElementById("gaugeValueLabel")!.innerHTML = value;
  options.value = Number(value);

  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).setLabelPlacement = setLabelPlacement;
  (<any>window).setAvoidCollisions = setAvoidCollisions;
  (<any>window).setValue = setValue;
}

{
    label: {
        enabled: true,
        placement: 'inside-start',
        avoidCollisions: true,
    },
    scale: {
        label: {
            enabled: false,
        },
    },
}

In this configuration:

The label placement in relation to the gauge is configured by the placement property.
The label is configured to avoid simultaneously overlapping the bar and scale with the avoidCollisions property.
The scale labels are hidden using the scale.label.enabled option. See the API Reference for more details about customising the scale label style and interval.

Segmentation Copy Link

To split the gauge into segments, set segmentation.enabled to true.

main.ts

import {
  AgCharts,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",

  direction: "horizontal",
  value: 85,
  scale: {
    min: 0,
    max: 100,
  },
  segmentation: {
    enabled: true,
    interval: {
      count: 4,
    },
    spacing: 2,
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

function setSegmentationInterval(event: Event) {
  switch ((event.target as HTMLInputElement).value) {
    case "step":
      options.segmentation!.interval = { step: 10 };
      break;
    case "count":
      options.segmentation!.interval = { count: 4 };
      break;
    case "values":
      options.segmentation!.interval = { values: [40, 50, 60] };
      break;
  }

  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).setSegmentationInterval = setSegmentationInterval;
}

{
    segmentation: {
        enabled: true,
        interval: {
            count: 4,
        },
        spacing: 2,
    },
}

In this configuration:

segmentation.interval specifies how the gauge is segmented. Available options are:
- step - segments the gauge at a fixed interval.
- count - segments the gauge a fixed number of times.
- values - segments the gauge at specific scale values.
spacing defines the spacing between each segment.

Corner Radius Copy Link

main.ts

import {
  AgCharts,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",
  direction: "horizontal",

  padding: {
    left: 30,
    right: 30,
  },
  value: 85,
  scale: {
    min: 0,
    max: 100,
  },
  cornerRadius: 99,
  cornerMode: "container",
  segmentation: {
    enabled: false,
    interval: {
      count: 10,
    },
    spacing: 2,
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

function setCornerMode(event: Event) {
  options.cornerMode = (event.target as HTMLInputElement).value as
    | "container"
    | "item";

  chart.update(options);
}

function setSegmentation(event: Event) {
  options.segmentation!.enabled =
    (event.target as HTMLInputElement).value === "true";

  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).setCornerMode = setCornerMode;
  (<any>window).setSegmentation = setSegmentation;
}

{
    cornerRadius: 99,
    cornerMode: 'container',
}

In this configuration:

cornerRadius specifies the amount of curvature applied to each corner.
cornerMode can be set to container to apply rounded corners only to the start and end of the gauge, or item for all visual items within the gauge.

Colour Options Copy Link

Single Colour Copy Link

Both the bar and scale can be displayed using a solid fill.

main.ts

import {
  AgCharts,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",

  direction: "horizontal",
  value: 80,
  scale: {
    min: 0,
    max: 100,
    fill: "#f5f6fa",
  },
  bar: {
    fill: "#4cd137",
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

{
    scale: {
        fill: '#f5f6fa',
    },
    bar: {
        fill: '#4cd137',
    },
}

Multiple Colours Copy Link

Multiple colours can be specified using the fills property.

main.ts

import {
  AgCharts,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",

  direction: "horizontal",
  value: 85,
  scale: {
    min: 0,
    max: 100,
  },
  bar: {
    fills: [{ color: "#00a8ff" }, { color: "#9c88ff" }, { color: "#e84118" }],
    fillMode: "discrete",
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

function setFillMode(event: Event) {
  options.bar!.fillMode = (event.target as HTMLInputElement).value as
    | "continuous"
    | "discrete";

  chart.update(options);
}

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).setFillMode = setFillMode;
}

{
    bar: {
        fills: [{ color: '#00a8ff' }, { color: '#9c88ff' }, { color: '#e84118' }],
        fillMode: 'discrete',
    },
}

In this configuration:

fills specifies an array of colours to use to fill the bar.
fillMode can be set to continuous for a gradient, or discrete to use blocks of solid colours.

The default behaviour is to space out the colours evenly. This can be customised by using colour stops.

Colour Stops Copy Link

main.ts

import {
  AgCharts,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",
  direction: "horizontal",

  value: 80,
  scale: {
    min: 0,
    max: 100,
  },
  bar: {
    fills: [
      { color: "#E84118", stop: 35 },
      { color: "#FBC531", stop: 45 },
      { color: "#4CD137", stop: 55 },
      { color: "#FBC531", stop: 65 },
      { color: "#E84118" },
    ],
    fillMode: "discrete",
  },
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

{
    bar: {
        fills: [
            { color: '#E84118', stop: 35 },
            { color: '#FBC531', stop: 45 },
            { color: '#4CD137', stop: 55 },
            { color: '#FBC531', stop: 65 },
            { color: '#E84118' },
        ],
        fillMode: 'discrete',
    },
}

In this configuration:

Each colour stops at the stop value, and the next colour begins at that point.
If no stop is provided, the fills will be distributed equally.
The last colour is used until the end of the scale or bar.
Both discrete and continuous modes can be used with colour stops.

Targets Copy Link

Gauges often display targets or thresholds to provide context to the displayed data value. These can be added using the targets configuration array.

main.ts

import {
  AgCharts,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",

  direction: "horizontal",
  value: 50,
  scale: {
    min: 0,
    max: 100,
  },
  targets: [
    {
      value: 70,
      text: "Average",
    },
  ],
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

{
    targets: [
        {
            value: 70,
            text: 'Average',
        },
    ],
}

In this configuration:

value is the position for the target marker.
text is an optional string for the target label.

Customisation Copy Link

main.ts

import {
  AgCharts,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",
  direction: "horizontal",

  value: 50,
  scale: {
    min: 0,
    max: 100,
  },
  targets: [
    {
      value: 30,
      shape: "triangle",
      placement: "before",
      fill: "white",
      strokeWidth: 2,
      spacing: 8,
    },
    {
      value: 75,
      placement: "after",
      shape: "triangle",
      fill: "white",
      strokeWidth: 2,
      spacing: 8,
    },
    {
      value: 90,
      placement: "middle",
      shape: "circle",
      fill: "white",
      strokeWidth: 2,
      spacing: 8,
    },
  ],
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

{
    targets: [
        {
            value: 30,
            shape: 'triangle',
            placement: 'before',
            fill: 'white',
            strokeWidth: 2,
            spacing: 8,
        },
        {
            value: 75,
            placement: 'after',
            shape: 'triangle',
            fill: 'white',
            strokeWidth: 2,
            spacing: 8,
        },
        {
            value: 90,
            placement: 'middle',
            shape: 'circle',
            fill: 'white',
            strokeWidth: 2,
            spacing: 8,
        },
    ],
}

In this configuration:

shape is a marker shape.
placement indicates the relative placement to the gauge - either before, after, or middle.
size is the size of the marker, in pixels.
spacing is spacing from the edge of the gauge to the marker. Ignored when placement is middle.

Bullet Series Copy Link

The Linear Gauge is used to create a Bullet Series.

main.ts

import {
  AgCharts,
  AgLinearGaugeOptions,
  AllGaugeModule,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
} from "ag-charts-enterprise";

ModuleRegistry.registerModules([
  AllGaugeModule,
  AnimationModule,
  CrosshairModule,
  LegendModule,
  ContextMenuModule,
]);

const options: AgLinearGaugeOptions = {
  type: "linear-gauge",

  direction: "horizontal",
  thickness: 50,
  value: 50,
  scale: {
    min: 0,
    max: 100,
    fills: [{ color: "#A6A6A5" }, { color: "#BFBFBF" }, { color: "#D9D9D9" }],
    fillMode: "discrete",
  },
  bar: {
    thickness: 25,
    fill: "black",
  },
  targets: [
    {
      value: 60,
      shape: "line",
      size: 20,
      placement: "middle",
      strokeWidth: 2,
    },
  ],
};

options.container = document.getElementById("myChart");

const chart = AgCharts.createGauge(options);

{
    type: 'linear-gauge',
    thickness: 50,
    value: 50,
    scale: {
        min: 0,
        max: 100,
        fills: [{ color: '#A6A6A5' }, { color: '#BFBFBF' }, { color: '#D9D9D9' }],
        fillMode: 'discrete',
    },
    bar: {
        thickness: 25,
        fill: 'black',
    },
    targets: [
        {
            value: 60,
            shape: 'line',
            size: 20,
            placement: 'middle',
            strokeWidth: 2,
        },
    ],
}

In the above configuration:

The bar thickness is set to less that the gauge thickness.
The scale has a number of fills and a fillMode of discrete.
The target has line shape with a strokeWidth of 2 and is placed in the middle.

Linear Gauge Chart Examples Copy Link

See more Linear Gauge Chart examples in the AG Charts Gallery.

Linear Gauge Chart Example

Horizontal Linear Gauge Chart Example

Bullet Chart Example

API Reference Copy Link

Properties available on the AgLinearGaugeOptions interface.

type required 'linear-gauge': Configuration for the Linear Gauge.
value required AgNumericValue: Value of the Linear Gauge.
theme AgChartTheme | AgChartThemeName
container HTMLElement | null: The element to place the rendered chart into.
width PixelSize: The width of the chart in pixels.
height PixelSize: The height of the chart in pixels.
minHeight PixelSize default: 300: Sets the minimum height of the chart. Ignored if `height` is specified.
minWidth PixelSize default: 300: Sets the minimum width of the chart. Ignored if `width` is specified.
padding Padding: Configuration for the padding of the chart. A number applies uniform padding; an object sets each side.
background AgChartBackground: Configuration for the background shown behind the chart.
title AgChartCaptionOptions: Configuration for the title shown at the top of the chart.
subtitle AgChartSubtitleOptions: Configuration for the subtitle shown beneath the chart title.
footnote AgChartFooterOptions: Configuration for the footnote shown at the bottom of the chart.
tooltip AgChartTooltipOptions: Global configuration that applies to all tooltips in the chart.
animation AgAnimationOptions: Configuration for chart animations.
contextMenu AgContextMenuOptions: Configuration for the context menu.
context ContextDefault: Context object to use in callbacks.
locale AgLocaleOptions: Configuration for localisation.
listeners AgBaseChartListeners: A map of event names to event listeners.
targets AgLinearGaugeTarget[]: Configuration for the targets.
direction Direction: Direction to display the gauge in.
thickness number: Width of the gauge, or the height if `direction` is `horizontal`.
segmentation AgGaugeSegmentation: Configuration for a segmented appearance.
cornerRadius number: Apply rounded corners to the gauge.
cornerMode AgGaugeCornerMode default: container: Configuration on whether to apply `cornerRadius` only to the ends of the gauge, or each individual item within the gauge.
bar AgLinearGaugeBarStyle: Configuration for the bar.
scale AgLinearGaugeScale: Configuration for the scale.
label AgLinearGaugeLabelOptions: Configuration for the labels shown inside the shape.
cursor string: The cursor to use for the gauge. This config is identical to the CSS `cursor` property.
highlight AgHighlightOptions: Configuration for highlighting when a series or legend item is hovered over.
selection AgSelectionOptions: Configuration for data selection.
nodeClickRange InteractionRange: Range from a node that a click triggers the listener.

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

JavaScript ChartsLinear Gauge

Simple Linear Gauge Copy Link

Horizontal Linear Gauge Copy Link

Customisation Copy Link

Thickness Copy Link

Labels Copy Link

Segmentation Copy Link

Corner Radius Copy Link

Colour Options Copy Link

Single Colour Copy Link

Multiple Colours Copy Link

Colour Stops Copy Link

Targets Copy Link

Customisation Copy Link

Bullet Series Copy Link

Linear Gauge Chart Examples Copy Link

API Reference Copy Link