Skip to main content
← Back to plugin catalog

Session highlighting

NewOverlaysWorks with lightweight-charts ^5.0.0v1.0.0

Shades the background behind each bar from a color function of its time, for trading sessions, weekends, market hours or any other time-based highlight.

Interactive example — the real plugin running on a live chart. Scroll, zoom, and hover. Open the full demo

A series primitive that shades the background behind each bar of a series. You give it a function from a bar's time to a color, and every bar of the attached series gets a full-height column in that color, as wide as the bar itself. The columns follow the series as the chart scrolls and zooms.

Use it to show where one trading session ends and the next begins, to tint pre-market and after-hours bars, to mark weekends or holidays, or to shade any other time-based condition behind the data.

Installation​

Install the package. It requires lightweight-charts ^5.0.0 in your project:

npm install @tradingview/lwc-plugin-session-highlighting

Then import the plugin and add it to a chart:

import { createChart, CandlestickSeries } from 'lightweight-charts';
import { SessionHighlighting } from '@tradingview/lwc-plugin-session-highlighting';

const chart = createChart(document.getElementById('container'));
const series = chart.addSeries(CandlestickSeries);
series.setData(data);

series.attachPrimitive(new SessionHighlighting(time => {
const day = new Date(time * 1000).getUTCDay();
return day === 0 || day === 6 ? 'rgba(255, 152, 1, 0.2)' : '';
}));

Usage​

The highlighter​

The first constructor argument is the highlighter: a function which receives a bar's time and returns a CSS color. Return an empty string for a bar that should not be shaded. The time comes in whatever form your data uses, so for business-day data check for an object:

import { isBusinessDay } from 'lightweight-charts';

function toDate(time) {
if (isBusinessDay(time)) {
return new Date(Date.UTC(time.year, time.month - 1, time.day));
}
return typeof time === 'number' ? new Date(time * 1000) : new Date(time);
}

const highlighter = time => {
const hour = toDate(time).getUTCHours();
if (hour < 9 || hour >= 16) {
return 'rgba(120, 123, 134, 0.15)'; // outside the main session
}
return '';
};

const highlighting = new SessionHighlighting(highlighter);
series.attachPrimitive(highlighting);

The highlighter is called once per bar when the series data is set, and once for the last bar when series.update() appends or replaces it, so it can do real work per call; series.pop() drops the popped bars without calling it. Keep it a function of the time alone: a historical update, which is series.update(bar, true), re-asks it for the last bar rather than for the bar it changed, and one that turns a bar into whitespace, or whitespace into a bar, re-asks it for every bar. Translucent colors let the grid and the series show through; the shading is drawn behind both by default.

To remove the shading, detach it from the series:

series.detachPrimitive(highlighting);

Changing the shading​

highlighting.applyOptions({ zOrder: 'top', visible: false });
highlighting.setHighlighter(time => '#F0F3FA'); // recolors every bar
highlighting.options(); // the current options, with the defaults filled in

applyOptions merges: an option which is not passed, or is passed as undefined, is left unchanged.

Options​

Options are passed as the second constructor argument, which is optional, as is every option in it. The type is SessionHighlightingOptions, and the defaults are exported as defaultOptions.

OptionTypeDefaultDescription
visiblebooleantrueWhether the shading is drawn at all.
zOrder'bottom' | 'normal' | 'top''bottom'Layer the shading is drawn in. 'bottom' puts it behind the grid and the series.

Notes​

  • Each column is exactly one bar wide, taken from the time scale's bar spacing, so neighboring columns abut with no seams and no overlap at any zoom level or device pixel ratio.
  • Only bars of the attached series are shaded. Whitespace items and gaps in the data get no column, even where another series has a bar at that time.
  • The shading appears only in the pane the series is drawn in, never under the price scales or the time scale. To shade a second pane, attach another SessionHighlighting to a series in that pane.
  • Only the bars on screen are drawn, so the cost of a paint is bounded by the width of the chart, not by the length of the history. An incremental series.update() or series.pop() does read the series data once to find out what changed, which is proportional to the number of bars.

Metadata​

PublisherTradingView (official)
npm package@tradingview/lwc-plugin-session-highlighting
Version1.0.0
Supported rangelightweight-charts ^5.0.0
Plugin typeseries-primitive
LicenseApache-2.0
PublishedNov 13, 2026
Tagssessionbackgroundshadinghighlightmarket hoursweekend
Repositorytradingview/lightweight-charts/tree/master/packages/lwc-plugin-session-highlighting