Pretty histogram series

A custom series that draws a histogram with rounded bars. Unlike the built-in histogram series, it can round the outer corners of each bar, control the bar width as a share of the bar spacing, colour bars by their sign, draw a border and fade the fill into a second colour. The result is a softer look that fits dashboards and marketing-style charts.

Use it for volume panes, single-value indicators, or any bar chart where the default square bars look too heavy.

Usage​

Add the series with addCustomSeries, then set histogram data:

import { createChart } from 'lightweight-charts';
import { createPrettyHistogramSeries } from '@tradingview/lwc-plugin-pretty-histogram-series';

const chart = createChart(document.getElementById('container'));
const series = createPrettyHistogramSeries(chart, {
    color: '#2962FF',
    widthPercent: 60,
    radius: 6,
});

series.setData([
    { time: '2024-04-22', value: 12.5 },
    { time: '2024-04-23', value: -4.1 },
    { time: '2024-04-24', value: 8.3, color: '#F23645' },
]);

Each data point is { time, value, color? } — the same shape as the built-in histogram series. A per-point color overrides the series color for that bar. Points without a value are treated as whitespace.

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

Two-tone bars​

Set upColor and downColor to colour each bar by its sign relative to base, the way a volume pane usually does:

series.applyOptions({
    base: 0,
    upColor: '#089981',
    downColor: '#F23645',
});

A per-point color still wins over both.

The base line​

Bars grow from base (0 by default), and the base is always reported to the autoscale alongside the values, exactly as the built-in histogram series does. Bars are therefore never cut off at the edge of the pane, and no custom autoscaleInfoProvider is needed.

base is read when the data is set, so change it before or together with setData if you also rely on the autoscale following it.

Creating a series​

Use createPrettyHistogramSeries(chart, options?, paneIndex?). It returns the normal series API, with the plugin's data and options types preserved. The helper makes scaling options available before the first setData and rebuilds plot values automatically when those options change through series.applyOptions. This keeps autoscaling, last-value labels and crosshair values consistent. The helper retains a shallow copy of the input data, including whitespace, and re-ingests it only when a scaling option changes. Streaming updates remain incremental.

The low-level PrettyHistogramSeries pane view remains available for integrations that supply their own options getter to its constructor. Passing scaling options only to chart.addCustomSeries(new PrettyHistogramSeries(), options) cannot make them available before data ingestion on LWC 5.0; use the creation helper instead.

Options​

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

Notes​

• Bars are anchored at base and the base is always part of the autoscale, so the series behaves like the built-in histogram; see The base line.
• Bar widths reproduce the built-in histogram exactly in 'histogram' width mode and at widthPercent: 100: the same pixel grid, the same one-pixel gap, and no alignment carried across a whitespace gap.
• Flat, borderless bars are drawn in batches: consecutive bars of the same color are filled in one canvas operation. Setting borderColor, gradientColor or highlightHovered paints bar by bar instead.
• hitTest (which reports the hovered bar through the crosshair as bar-<index>) and conflationReducer are used by Lightweight Charts 5.1 and later. On 5.0 they are simply never called, and highlightHovered has no effect.