AG Studio Launch Week 🚀🚀🚀 28 Sep - 2 Oct 2026 🚀🚀🚀 Join now
AG Grid
Best JavaScript Grid in the World
AG Charts
Best JavaScript Charts in the World
AG Studio
Best JavaScript Dashboard in the World
Bryntum Gantt
Speed-tuned Gantt chart for project planning
Bryntum Scheduler
Resource scheduling timeline component
PROPRO
Bryntum Scheduler Pro
Scheduler with auto-scheduling and constraints
Bryntum Calendar
Flexible JavaScript event calendar
Bryntum Task Board
Kanban-style task board component
Search⌘ KCtrl K
What's New
Getting started
Quick StartKey FeaturesCommunity vs. Enterprise
AI Features
Skills
Core features
Specialised Charts
Org ChartQuadrant Chart
Series
BarLineAreaScatterBubblePieDonutCombinationBox PlotCandlestickOHLCHeatmapHistogramNightingaleRadar AreaRadar LineRadial BarRadial ColumnRange AreaRange BarWaterfallSunburstTreemapSankeyChordFunnelCone FunnelPyramid
Gauges
Radial GaugeLinear Gauge

JavaScript ChartsRange Area Series

Version 14.2.0
Enterprise

A Range Area Series represents data ranges using a shaded area between high and low data values. This series type is often used to show variations or trends in data over a specified time.

Simple Range Area Copy Link

The Range Area Series is created using the range-area series type.

{
    series: [
        {
            type: 'range-area',
            xKey: 'date',
            yLowKey: 'flatsAndMaisonettes',
            yHighKey: 'detachedHouses',
        },
    ],
}

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

Multiple Range Area Series Copy Link

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

 
{
    series: [
        {
            type: 'range-area',
            xKey: 'date',
            yLowKey: 'flatsAndMaisonettes',
            yHighKey: 'terracedHouses',
            xName: 'Date',
            yName: 'Flats & Terraced',
            yLowName: 'Flats & Maisonettes',
            yHighName: 'Terraced',
        },
        {
            type: 'range-area',
            xKey: 'date',
            yLowKey: 'semiDetachedHouses',
            yHighKey: 'detachedHouses',
            xName: 'Date',
            yName: 'Semi-detached & Detached',
            yLowName: 'Semi-detached',
            yHighName: 'Detached',
        },
    ],
}

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.
  • Data points with a yLowKey or yHighKey value of positive or negative Infinity, null, undefined or NaN will be rendered as a gap in the range.
  • Set connectMissingData: true to draw a connecting area between points either side of a missing section.
  • Data points with invalid xKey values will be ignored.

Customisation Copy Link

Series markers and labels can be enabled using the marker and label options.

 
{
    series: [
        {
            // ...
            marker: {
                size: 7,
            },
            label: {
                spacing: 17,
                formatter: ({ itemType, value }) => {
                    return `${itemType === 'low' ? 'L' : 'H'}: ${value.toFixed(0)}`;
                },
            },
        },
    ],
}

In this configuration:

  • Markers have been enabled using the marker options object.
  • 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.

Inverted Style Copy Link

The invertedStyle property allows specifying a fill for areas where the yHighKey line is below the yLowKey line.

 
{
    series: [
        {
            type: 'range-area',
            xKey: 'quarter',
            yLowKey: 'projected',
            yHighKey: 'actual',
            invertedStyle: {
                fill: 'red',
            },
        },
    ],
}

In this configuration:

  • The series fill of blue is used where high > low.
  • The invertedStyle.fill of red is used where high < low.
  • The invertedStyle object supports fill and fillOpacity.

High and Low Styling Copy Link

By default, the Line and Marker styling options are applied to both the high and low values of the data.

Use the item.high and item.low properties to apply specific overrides.

 
{
    series: [
        {
            // ...

            // Shared high/low styling options:
            strokeWidth: 2,
            marker: {
                size: 12,
                fill: '#cccccc',
                itemStyler: (params) => {
                    // Highlight datum styling options:
                    if (params.highlightState === 'highlighted-item') {
                        if (params.itemType === 'high') {
                            return { fill: '#53c653' };
                        }
                        if (params.itemType === 'low') {
                            return { fill: '#ff3333' };
                        }
                    }
                    return {};
                },
            },

            // Differentiated high/low styling options
            item: {
                high: {
                    stroke: '#39ac39',
                    marker: {
                        stroke: '#39ac39',
                    },
                },
                low: {
                    stroke: '#e60000',
                    marker: {
                        stroke: '#e60000',
                    },
                },
            },
        },
    ],
}

In this configuration:

  • The strokeWidth is set to 2 on all lines.
  • All Markers are set a size of 12 with a gray fill.
  • The stroke for high line is set to a greenish colour.
  • The stroke for low Line is set to a reddish colour.
  • An itemStyler is used to override the fill of highlighted Markers, using different fill values for the high and low Markers.

Range Area Chart Examples Copy Link

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

Range Area Chart Example
Range Area Difference Chart With Inverted Style Example
Range Area Chart With Labels Example

API Reference Copy Link

Properties available on the AgRangeAreaSeriesOptions interface.

type required 'range-area'
Configuration for the Range Area 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.
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.
context ContextDefault
Context object to use in callbacks.
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.
cursor string
The cursor to use for hovered markers. This config is identical to the CSS `cursor` property.
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.
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.
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.
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.
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.
legendItemName string
Human-readable description of the y-values. If supplied, matching items with the same value will be toggled together.
marker AgRangeAreaMarker
Configuration for the markers used in the series.
stroke AgCssColorOrRef
The colour for the stroke. A colour string, or a theme-colour reference object.
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 for the stroke.
lineDashOffset PixelSize
The initial offset of the dashed line in pixels.
item AgRangeAreaSeriesItemThemeableOptions
Configuration used for distinct styling of the low and high lines.
interpolation AgInterpolationType
Configuration for the line used in the series.
label AgRangeAreaSeriesLabelOptions
Configuration for the labels shown on top of data points.
shadow AgDropShadowOptions
Configuration for the shadow used behind the series items.
tooltip AgSeriesTooltip
Series-specific tooltip configuration.
connectMissingData boolean
Set to `true` to connect across missing data points.
styler Styler
Function used to return formatting for entire series, based on the given parameters.
highlight AgMultiSeriesHighlightOptions
Configuration for highlighting when a series or legend item is hovered over.
segmentation AgSeriesSegmentation
Configuration for styling series as separate segments.
invertedStyle AgRangeAreaSeriesInvertedStyle
Style options for the fill of areas where the `yHigh` line is below the `yLow` line.
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.
showInMiniChart boolean
Whether to include the series in the Mini Chart.