Vertical line

A series primitive that draws a full-height vertical line at a given time, with an optional label on the time axis. You attach the line to a series. The line then follows that series' time scale as the user scrolls and zooms.

Use it to mark a moment in time that matters on your chart:

• an event, such as earnings, a news release, or a dividend date;
• a trade, such as entry and exit points, with a label like Buy or Sell;
• a boundary, such as a session open or close, the start of a backtest, or the current bar.

Because each line is a separate primitive, you can place as many as you need on the same series, each with its own color, width, and label.

Usage​

Create a line for a time that exists in your series data, then attach it to that series:

import { createChart, LineSeries } from 'lightweight-charts';
import { VerticalLine } from '@tradingview/lwc-plugin-vertical-line';

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

const earningsLine = new VerticalLine('2024-04-25', {
    color: '#2962FF',
    width: 2,
    showLabel: true,
    labelText: 'Earnings',
    labelBackgroundColor: '#2962FF',
    labelTextColor: '#FFFFFF',
});
series.attachPrimitive(earningsLine);

To remove a line, detach it from the series:

series.detachPrimitive(earningsLine);

The time argument accepts any Time value supported by the chart (a business day string, a BusinessDay object, or a UTC timestamp) — use the same format as your series data.

Change a line after it has been created with applyOptions and setTime:

earningsLine.applyOptions({ color: '#F23645', labelText: 'Moved' });
earningsLine.setTime('2024-05-02');

Options​

All options are optional. Pass them as the second constructor argument.

The defaults are exported as defaultOptions.

Badge​

A badge is a short caption drawn on the line itself, for text that should stay next to the line rather than sit on the time axis:

series.attachPrimitive(new VerticalLine('2024-04-25', {
    badge: { text: 'Earnings', backgroundColor: '#2962FF' },
}));

The badge defaults are exported as defaultBadgeOptions.

Dragging​

With draggable: true the line can be moved along the time scale with the pointer, and timeChanged() reports every new time:

const line = new VerticalLine('2024-04-25', { draggable: true });
series.attachPrimitive(line);
line.timeChanged().subscribe(time => console.log(time));

Dragging suspends the chart's own scroll and scale handling for the duration of the gesture, so the chart does not pan under the pointer. Only one line per chart holds that suspension at a time: where two draggable lines overlap, the one attached first takes the gesture and the other ignores it, so the chart's options are restored exactly once. Ownership is tracked per loaded copy of this module, so two bundles of the plugin on the same page each track their own owner; load it once per page if you attach overlapping draggable lines.

Notes​

• With the default snap: 'exact' the line is drawn only when its time is a bar of the chart's time scale; a time between bars or outside the data draws nothing, and its time-axis label is hidden with it. Use snap: 'nearest' to place the line on the closest bar instead.
• The line spans the full height of the pane the series belongs to. To mark a time across several panes, attach a line to a series in each pane.
• The label is rendered by the chart's time axis, so it inherits the axis font and is hidden together with the axis if timeScale.visible is false.
• VertLine and VertLineOptions are still exported, as deprecated aliases of VerticalLine and VerticalLineOptions, and the old new VertLine(chart, series, time, options) form of the constructor still works: the chart and the series arguments are ignored. Both are kept for compatibility and will be removed in a future major version.