Plugins

Plugins extend the chart with visualisations beyond the built-in series types. Import from lightweight_charts.plugins.

from lightweight_charts.plugins import (
    Tooltip,
    BandsIndicator,
    SessionHighlighting,
    HeatmapSeries,
    VolumeProfile,
    PositionTool,
)

---

Tooltip

class Tooltip(series, line_color: COLOR, follow_mode: str, title: str)

A floating tooltip that follows the crosshair and displays OHLCV price data for the bar under the cursor. Automatically switches the chart crosshair to Magnet mode.

• series — the primary series to attach the tooltip to.

• line_color — colour of the tooltip border line.

• follow_mode — 'top' (default) or 'tracking'.

• title — optional label shown at the top of the tooltip.

---

apply_options(line_color, follow_mode, title)

Updates tooltip display options. Only supplied arguments change.

---

delete()

Detaches and removes the tooltip from the series.

---

BandsIndicator

class BandsIndicator(upper_series, lower_series, line_color: COLOR, fill_color: COLOR, line_width: int)

Draws band lines and a filled region between an upper and lower series (e.g. Bollinger Bands, Keltner Channels, Donchian Channels).

• upper_series — a SeriesCommon-derived series representing the upper band.

• lower_series — a SeriesCommon-derived series representing the lower band.

• line_color — colour of both band lines.

• fill_color — fill colour of the region between the bands.

• line_width — line width in pixels.

Example:

import pandas as pd
from lightweight_charts import Chart
from lightweight_charts.plugins import BandsIndicator

chart = Chart()
df = pd.read_csv('ohlcv.csv')
chart.set(df)

mid = df['close'].rolling(20).mean()
std = df['close'].rolling(20).std()
upper_df = pd.DataFrame({'time': df['time'], 'Upper': mid + 2 * std})
lower_df = pd.DataFrame({'time': df['time'], 'Lower': mid - 2 * std})

upper = chart.create_line('Upper')
lower = chart.create_line('Lower')
upper.set(upper_df)
lower.set(lower_df)

bands = BandsIndicator(upper, lower)
chart.show(block=True)

---

delete()

Detaches and removes the bands indicator.

---

SessionHighlighting

class SessionHighlighting(series, default_color: COLOR)

Highlights the chart background for specified time ranges to mark trading sessions (e.g. London open, New York open).

• series — the series to attach the highlighting to.

• default_color — default background colour outside sessions (default: transparent).

---

set_sessions(sessions: list)

Sets the time ranges to highlight.

Each entry is a dict with:

• start — session start as Unix seconds (int).

• end — session end as Unix seconds (int).

• color — (optional) CSS colour string for this session.

Example:

from datetime import datetime, timezone

def to_unix(dt_str):
    return int(datetime.fromisoformat(dt_str).replace(tzinfo=timezone.utc).timestamp())

highlighting.set_sessions([
    {'start': to_unix('2024-01-01 08:00'), 'end': to_unix('2024-01-01 16:30')},
    {'start': to_unix('2024-01-01 13:30'), 'end': to_unix('2024-01-01 16:00'),
     'color': 'rgba(255, 165, 0, 0.1)'},
])

---

delete()

Detaches and removes the session highlighting.

---

HeatmapSeries

class HeatmapSeries(chart, bid_color: COLOR, ask_color: COLOR, cell_border_width: int, cell_border_color: COLOR, pane_index: int)

Custom series rendering a price-level heatmap — ideal for order-book liquidity visualisation.

• chart — the parent Chart (or StreamChart) instance.

• bid_color — base colour for bid-side cells.

• ask_color — base colour for ask-side cells.

• cell_border_width — width of cell borders in pixels.

• cell_border_color — colour of cell borders.

• pane_index — pane to place the series on.

Custom shader functions (bid_shader_js, ask_shader_js, cell_shader_js) can be passed as JavaScript strings to override per-cell colouring.

---

set(time, bids: list, asks: list)

Replaces all heatmap data with a single orderbook snapshot.

• time — timestamp (Unix seconds, datetime, or string).

• bids — list of (price, size) tuples for bid levels.

• asks — list of (price, size) tuples for ask levels.

---

update(time, bids: list, asks: list)

Appends or updates the heatmap bar at the given timestamp with a new snapshot.

Same parameter format as set().

---

VolumeProfile

class VolumeProfile(series, time, profile, width: int)

Renders a volume-profile histogram at a specific time position on a series. The profile is a vertical bar chart of price levels vs. accumulated volume.

• series — the series to anchor the profile to.

• time — anchor timestamp (Unix seconds, datetime, or string).

• profile — price-level volume data: list of {'price': float, 'vol': float} dicts, or a DataFrame with price and vol columns.

• width — width of the profile in bar units (default 10).

Example:

import pandas as pd
from lightweight_charts import Chart
from lightweight_charts.plugins import VolumeProfile

chart = Chart()
df = pd.read_csv('ohlcv.csv')
chart.set(df)

# Build a profile: price levels bucketed into 20 bins
bins = pd.cut(df['close'], bins=20)
profile = df.groupby(bins, observed=True).agg(
    price=('close', 'mean'),
    vol=('volume', 'sum')
).dropna().reset_index(drop=True)

vp = VolumeProfile(chart.candle_series, df.iloc[-1]['time'], profile)
chart.show(block=True)

---

delete()

Detaches and removes the volume profile.

---

PositionTool

class PositionTool(series, entry: NUM, stop: NUM, target: NUM, entry_time: TIME, end_time: TIME, stop_color: COLOR, target_color: COLOR, quantity: NUM)

Risk/reward overlay visualising an open trade position. Renders a stop zone (red rectangle) and target zone (green rectangle) between the entry price and stop/target prices.

Hovering over the overlay reveals an entry price line (blue) with the following metrics:

• Entry price and bar count, shown inside the rectangle above the line.

• Risk/reward ratio (e.g. 1:2), shown below the line.

• TP/SL prices anchored at the left inner edge of their respective zones.

• Win/lose amounts at the right inner edge — monetary (e.g. +$125.00) when quantity is supplied, or raw point delta otherwise.

Price-ordering constraints:

• Long position: target > entry > stop

• Short position: stop > entry > target

• series — the series to attach the overlay to.

• entry — entry price.

• stop — stop-loss price.

• target — take-profit price.

• entry_time — timestamp of entry bar.

• end_time — (optional) end timestamp; if omitted, the overlay auto-tracks the latest bar (always at least 15 bars wide from entry).

• stop_color / target_color — fill colours for each zone.

• quantity — (optional) number of units/contracts; enables monetary win/lose display. Must be > 0.

Example:

from lightweight_charts import Chart
from lightweight_charts.plugins import PositionTool
import pandas as pd

chart = Chart()
df = pd.read_csv('ohlcv.csv')
chart.set(df)

pos = PositionTool(
    chart.candle_series,
    entry=100.0, stop=95.0, target=112.0,
    entry_time=df.iloc[10]['time'],
    quantity=10,
)
chart.show(block=True)

---

update(entry, stop, target, end_time, quantity)

Updates one or more position parameters. Only supplied arguments change; others retain their current values.

---

delete()

Detaches and permanently removes the position overlay.