JavaScript ChartsRange Bar Series

Version 14.2.0

Enterprise

A Range Bar Series uses vertical or horizontal bars to show the range between high and low values in data. This series type is commonly used to assess data stability or variability.

Simple Range Bar Copy Link

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  RangeBarSeriesModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  RangeBarSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Salary Ranges By Department",
  },
  subtitle: {
    text: "Low and High Salary Brackets Across Various Departments (in thousands)",
  },
  series: [
    {
      type: "range-bar",
      xKey: "department",
      yLowKey: "low",
      yHighKey: "high",
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    { department: "Finance", low: 75, high: 110 },
    { department: "Engineering", low: 75, high: 125 },
    { department: "Marketing", low: 55, high: 75 },
    { department: "Sales", low: 60, high: 85 },
    { department: "Legal", low: 70, high: 100 },
    { department: "Operations", low: 55, high: 80 },
    { department: "Research", low: 60, high: 80 },
    { department: "Development", low: 70, high: 90 },
  ];
}

The Range Bar Series is created using the range-bar series type.

{
    series: [
        {
            type: 'range-bar',
            xKey: 'department',
            yLowKey: 'low',
            yHighKey: 'high',
        },
    ],
}

The yLowKey and yHighKey are used to retrieve the range of values for the y-axis.

Multiple Range Bar Series Copy Link

Multiple Range Bar Series can be combined into a single chart.

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  RangeBarSeriesModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  RangeBarSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: `Digital Subscriptions`,
  },
  subtitle: {
    text: `In Thousands`,
  },
  series: [
    {
      type: "range-bar",
      xKey: "date",
      yLowKey: "start",
      yHighKey: "gain",
      xName: "Month",
      yLowName: "Start",
      yHighName: "End",
      yName: "Gained",
    },
    {
      type: "range-bar",
      xKey: "date",
      yLowKey: "loss",
      yHighKey: "gain",
      xName: "Month",
      yLowName: "End",
      yHighName: "Start",
      yName: "Lost",
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    {
      date: "Jan",
      start: 0,
      gain: 210,
      loss: 200,
    },
    {
      date: "Feb",
      start: 200,
      gain: 440,
      loss: 305,
    },
    {
      date: "Mar",
      start: 305,
      gain: 589,
      loss: 488,
    },
    {
      date: "Apr",
      start: 488,
      gain: 809,
      loss: 721,
    },
    {
      date: "May",
      start: 721,
      gain: 1002,
      loss: 833,
    },
    {
      date: "Jun",
      start: 833,
      gain: 1035,
      loss: 852,
    },
    {
      date: "Jul",
      start: 852,
      gain: 1050,
      loss: 852,
    },
    {
      date: "Aug",
      start: 852,
      gain: 1059,
      loss: 924,
    },
    {
      date: "Sep",
      start: 924,
      gain: 1205,
      loss: 1115,
    },
    {
      date: "Oct",
      start: 1115,
      gain: 1390,
      loss: 1231,
    },
    {
      date: "Nov",
      start: 1231,
      gain: 1425,
      loss: 1306,
    },
    {
      date: "Dec",
      start: 1306,
      gain: 1498,
      loss: 1484,
    },
  ];
}

{
    series: [
        {
            type: 'range-bar',
            xKey: 'date',
            yLowKey: 'start',
            yHighKey: 'gain',
            xName: 'Month',
            yLowName: 'Start',
            yHighName: 'End',
            yName: 'Gained',
        },
        {
            type: 'range-bar',
            xKey: 'date',
            yLowKey: 'loss',
            yHighKey: 'gain',
            xName: 'Month',
            yLowName: 'End',
            yHighName: 'Start',
            yName: 'Lost',
        },
    ],
}

In this configuration:

yName is used to control the text displayed in the legend.
yLowName, yHighName and xName are used to control the text displayed in the tooltip.

Missing Data Copy Link

The series handles missing or invalid data based on the presence or validity of xKey, yLowKey and yHighKey values in the data object.

main.ts

import {
  AgCartesianChartOptions,
  AgCharts,
  AnimationModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  RangeBarSeriesModule,
  UnitTimeAxisModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  RangeBarSeriesModule,
  UnitTimeAxisModule,
  ContextMenuModule,
]);

const options: AgCartesianChartOptions = {
  data: getData(),
  title: {
    text: "Range Bar Missing Data",
  },
  series: [
    {
      type: "range-bar",
      xKey: "date",
      xName: "Date",
      yLowKey: "low",
      yHighKey: "high",
    },
  ],
  axes: {
    x: {
      type: "unit-time",
      crosshair: {
        enabled: false,
      },
    },
  },
};

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

const chart = AgCharts.create(options);

function missingYValues() {
  const data = getData();
  data[2].high = undefined;
  data[5].low = undefined;
  options.data = data;

  chart.update(options);
}

function missingXValue() {
  const data = getData();
  data[6].date = undefined;
  options.data = data;

  chart.update(options);
}

function reset() {
  options.data = getData();

  chart.update(options);
}

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

data.ts

export function getData(): any[] {
  return [
    {
      date: new Date(2022, 10, 1),
      high: 1900,
      low: 900,
    },
    {
      date: new Date(2022, 10, 2),
      high: 1345,
      low: 345,
    },
    {
      date: new Date(2022, 10, 3),
      high: 1393,
      low: 393,
    },
    {
      date: new Date(2022, 10, 4),
      high: 1108,
      low: -108,
    },
    {
      date: new Date(2022, 10, 5),
      high: 1154,
      low: -154,
    },
    {
      date: new Date(2022, 10, 6),
      high: 1135,
      low: 135,
    },
    {
      date: new Date(2022, 10, 7),
      high: 1178,
      low: 178,
    },
    {
      date: new Date(2022, 10, 8),
      high: 1286,
      low: 286,
    },
    {
      date: new Date(2022, 10, 9),
      high: 1119,
      low: -119,
    },
    {
      date: new Date(2022, 10, 10),
      high: 1361,
      low: -361,
    },
    {
      date: new Date(2022, 10, 11),
      high: 1203,
      low: -203,
    },
  ];
}

When the axes types are continuous ('number', 'time' or 'log'), the yLowKey, yHighKey and xKey values in the data object are considered invalid if they are:

+/-Infinity
null
undefined
NaN

Data entries with invalid yLowKey, yHighKey and xKey values will result in gaps in the series.

Customisation Copy Link

Labels Copy Link

Series labels can be enabled using the label options.

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  RangeBarSeriesModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  RangeBarSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Salary Ranges By Department",
  },
  subtitle: {
    text: "Low and High Salary Brackets Across Various Departments (in thousands)",
  },
  series: [
    {
      type: "range-bar",
      xKey: "department",
      yLowKey: "low",
      yHighKey: "high",
      label: {
        padding: 10,
        formatter: ({ itemType, value }) => {
          return `£${value.toFixed(0)}K ${itemType === "low" ? "↓" : "↑"}`;
        },
      },
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    { department: "Finance", low: 75, high: 110 },
    { department: "Engineering", low: 75, high: 125 },
    { department: "Marketing", low: 55, high: 75 },
    { department: "Sales", low: 60, high: 85 },
    { department: "Legal", low: 70, high: 100 },
    { department: "Operations", low: 55, high: 80 },
    { department: "Research", low: 60, high: 80 },
    { department: "Development", low: 70, high: 90 },
  ];
}

{
    series: [
        {
            // ...
            label: {
                padding: 10,
                formatter: ({ itemType, value }) => {
                    return `£${value.toFixed(0)}K ${itemType === 'low' ? '↓' : '↑'}`;
                },
            },
        },
    ],
}

In this configuration:

The yHighKey and yLowKey values for each data point are presented as labels via the label options.
The label.formatter function uses the itemType from the params object to distinguish whether the label is a low or high value.

Corner Radius Copy Link

The corner radius can be customised with the cornerRadius property.

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  RangeBarSeriesModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  RangeBarSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Salary Ranges By Department",
  },
  subtitle: {
    text: "Low and High Salary Brackets Across Various Departments (in thousands)",
  },
  series: [
    {
      type: "range-bar",
      xKey: "department",
      yLowKey: "low",
      yHighKey: "high",
      cornerRadius: 10,
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    { department: "Finance", low: 75, high: 110 },
    { department: "Engineering", low: 75, high: 125 },
    { department: "Marketing", low: 55, high: 75 },
    { department: "Sales", low: 60, high: 85 },
    { department: "Legal", low: 70, high: 100 },
    { department: "Operations", low: 55, high: 80 },
    { department: "Research", low: 60, high: 80 },
    { department: "Development", low: 70, high: 90 },
  ];
}

{
    series: [
        {
            // ...
            cornerRadius: 10,
        },
    ],
}

Horizontal Range Bar Copy Link

main.ts

import {
  AgChartOptions,
  AgCharts,
  AnimationModule,
  CategoryAxisModule,
  ContextMenuModule,
  CrosshairModule,
  LegendModule,
  ModuleRegistry,
  NumberAxisModule,
  RangeBarSeriesModule,
} from "ag-charts-enterprise";
import { getData } from "./data";

ModuleRegistry.registerModules([
  AnimationModule,
  CategoryAxisModule,
  CrosshairModule,
  LegendModule,
  NumberAxisModule,
  RangeBarSeriesModule,
  ContextMenuModule,
]);

const options: AgChartOptions = {
  data: getData(),
  title: {
    text: "Salary Ranges By Department",
  },
  subtitle: {
    text: "Low and High Salary Brackets Across Various Departments (in thousands)",
  },
  series: [
    {
      type: "range-bar",
      direction: "horizontal",
      xKey: "department",
      yLowKey: "low",
      yHighKey: "high",
    },
  ],
};

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

const chart = AgCharts.create(options);

data.ts

export function getData() {
  return [
    { department: "Finance", low: 75, high: 110 },
    { department: "Engineering", low: 75, high: 125 },
    { department: "Marketing", low: 55, high: 75 },
    { department: "Sales", low: 60, high: 85 },
    { department: "Legal", low: 70, high: 100 },
    { department: "Operations", low: 55, high: 80 },
    { department: "Research", low: 60, high: 80 },
    { department: "Development", low: 70, high: 90 },
  ];
}

To create a Horizontal Range Bar Series, set direction: 'horizontal'.

{
    series: [
        {
            type: 'range-bar',
            direction: 'horizontal',
            xKey: 'department',
            yLowKey: 'low',
            yHighKey: 'high',
        },
    ],
}

When the direction is 'horizontal' the xKey will determine categories on the y-axis, while the yLowKey and yHighKey will be used to provide numerical values along the x-axis.

Range Bar Chart Examples Copy Link

See more Range Bar Chart examples in the AG Charts Gallery.

Range Bar Chart Example

Range Bar Chart With Labels Example

Range Bar Chart with Multiple Series Example

Horizontal Range Bar Chart Example

Horizontal Range Bar Chart With Labels Example

Horizontal Range Bar Charts with Multiple Series Example

API Reference Copy Link

Properties available on the AgRangeBarSeriesOptions interface.

type required 'range-bar': Configuration for the Range Bar Series.
xKey required DatumKey: The key to use to retrieve x-values from the data.
yLowKey required DatumKey: The key to use to retrieve y-low-values from the data.
yHighKey required DatumKey: The key to use to retrieve y-high-values from the data.
xName string: A human-readable description of the x-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
yName string: A human-readable description of the y-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
yLowName string: A human-readable description of the y-low-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
yHighName string: A human-readable description of the y-high-values. If supplied, this will be shown in the default tooltip and passed to the tooltip renderer as one of the parameters.
legendItemName string: Human-readable description of the y-values. If supplied, matching items with the same value will be toggled together.
direction 'horizontal' | 'vertical': Bar rendering direction. __Note:__ This option affects the layout direction of X and Y data values.
tooltip AgSeriesTooltip: Series-specific tooltip configuration.
label AgRangeBarSeriesLabelOptions: Configuration for the labels shown on top of data points.
shadow AgDropShadowOptions: Configuration for the shadow used behind the series items.
styler Styler: Function used to return formatting for entire series, based on the given parameters.
itemStyler Styler: Function used to return formatting for individual RangeBar series item cells, based on the given parameters.
highlight AgMultiSeriesHighlightOptions: Configuration for highlighting when a series or legend item is hovered over.
grouped boolean: Whether to group together (adjacently) separate bars.
segmentation AgSeriesSegmentation: Configuration for styling series as separate segments.
width PixelSize: Fixed width of each bar in the series.
widthRatio Ratio: Ratio of the bandwidth (or specified width) to use for the width for each bar in the series.
showInMiniChart boolean: Whether to include the series in the Mini Chart.
cursor string: The cursor to use for hovered markers. This config is identical to the CSS `cursor` property.
context ContextDefault: Context object to use in callbacks.
selection AgSelectionOptions: Configuration for data selection.
nodeClickRange InteractionRange: Range from a node that a click triggers the listener.
showInLegend boolean: Whether to include the series in the legend.
listeners AgSeriesListeners: A map of event names to event listeners.
cornerRadius PixelSize: Apply rounded corners to each bar.
fill AgColorType: The colour for filling shapes. A colour string, or an object for a gradient, pattern, or image fill.
fillOpacity Opacity: The opacity of the fill colour.
stroke AgCssColorOrRef: The colour for the stroke.
strokeWidth PixelSize: The width of the stroke in pixels.
strokeOpacity Opacity: The opacity of the stroke colour.
lineDash PixelSize[]: An array specifying the length in pixels of alternating dashes and gaps.
lineDashOffset PixelSize: The initial offset of the dashed line in pixels.
id string default: auto-generated value: Primary identifier for the series. This is provided as `seriesId` in user callbacks to differentiate multiple series. Auto-generated ids are subject to future change without warning, if your callbacks need to vary behaviour by series please supply your own unique `id` value.
data DatumDefault[]: The data to use when rendering the series. If this is not supplied, data must be set on the chart instead.
visible boolean: Whether to display the series.
xKeyAxis string default: 'x': The key of the x-axis to which this series is bound.
yKeyAxis string default: 'y': The key of the y-axis to which this series is bound.

Getting started

AI Features

Core features

Specialised Charts

Series

Gauges

JavaScript ChartsRange Bar Series

Simple Range Bar Copy Link

Multiple Range Bar Series Copy Link

Missing Data Copy Link

Customisation Copy Link

Labels Copy Link

Corner Radius Copy Link

Horizontal Range Bar Copy Link

Range Bar Chart Examples Copy Link

API Reference Copy Link