Stacked area series

A custom series that stacks several values per time point into cumulative bands. Each value is drawn as an area on top of the previous one, with a line along its upper edge. The top edge of the stack shows the total.

Use it to show composition over time, when the parts and the whole matter at the same time. Typical examples: portfolio allocation, revenue by segment, traffic by source, or volume by venue.

Usage​

Add the series with createStackedAreaSeries, then set data with a values array per point. The array order is the stacking order: values[0] is the bottom band.

import { createChart } from 'lightweight-charts';
import { createStackedAreaSeries } from '@tradingview/lwc-plugin-stacked-area-series';

const chart = createChart(document.getElementById('container'), {
    rightPriceScale: { scaleMargins: { top: 0.05, bottom: 0.05 } },
});
const series = createStackedAreaSeries(chart, {
    colors: [
        { line: '#2962FF', area: 'rgba(41, 98, 255, 0.2)' },
        { line: '#F23645', area: 'rgba(242, 54, 69, 0.2)' },
        { line: '#FF9800', area: 'rgba(255, 152, 0, 0.2)' },
    ],
    lineWidth: 2,
});

series.setData([
    { time: '2024-04-22', values: [12, 8, 5] },
    { time: '2024-04-23', values: [14, 7, 6] },
    { time: '2024-04-24', values: [11, 9, 4] },
]);

Each data point is { time, values: number[] }. Points do not have to carry the same number of values: a point with fewer values is padded with zeroes, so its missing bands collapse onto the one below them. Points with an empty or missing values array are treated as whitespace. The series' price line and last-value label follow the stack total.

Values are stacked from base (0 by default): a positive value continues away from the base, a negative one comes back towards it and past it, so each band is a single ribbon between two lines and never folds over itself.

A point may override the colours of its own bands:

series.setData([
    { time: '2024-04-22', values: [12, 8, 5] },
    {
        time: '2024-04-23',
        values: [14, 7, 6],
        colors: [{ line: '#000000', area: 'rgba(0, 0, 0, 0.2)' }],
    },
]);

An override applies to the piece of the band which starts at that point.

Options can be changed at runtime with series.applyOptions({ ... }).

Options​

In addition to the standard series options (priceLineVisible, lastValueVisible, priceFormat, autoscaleInfoProvider, …):

Each entry of colors is a StackedAreaColor, which may also override the series-wide line options for that band:

Per-point overrides, on the data item:

Notes​

• The price scale autoscales over the whole run of the stack, not just its total, so a point containing negative values stays fully in view. The outermost line sits exactly on the edge of the range; add a small scaleMargins on the price scale (as in the example above) if you want breathing room around it.
• Autoscaling follows percent and base, so a 100% stack scales to base…base + 100 and not to the raw totals, and changing either option rescales the series. This needs the current options at the moment the library asks for the plot values, which only createStackedAreaSeries can provide: a bare new StackedAreaSeries() added with chart.addCustomSeries autoscales from the raw values measured from zero, and needs an autoscaleInfoProvider of its own for percent or a non-zero base.
• The factory retains explicit whitespace, and gapHandling decides whether to break or bridge it. Timestamps from other series do not create gaps.
• On lightweight-charts 5.1 and later the series reports the hovered band through hitTest (the objectId is the index of the band) and dims the other bands while one is hovered, and conflated points are merged by summing each band. On 5.0.0 those hooks are simply never called.

Explicit whitespace​

Use createStackedAreaSeries to retain whitespace passed through setData and update, including historical corrections. Other series' timestamps do not break the area. The low-level StackedAreaSeries view remains available, but without the factory's gap predicate it draws continuously: the host does not provide whitespace to custom renderers.

Under time-scale conflation the area is drawn from buckets of several bars, and a whitespace run narrower than one bucket cannot be resolved at that bar spacing: it is absorbed into the bucket rather than breaking the area at every bar. Zooming in past the conflation threshold shows the gap again.