The Chart Container

tvl.chart() is the container that hosts one or more series and carries every chart-level option: pane layout, axes, time scale, styling, watermark, and titles. Each per-type constructor (tvl.line, tvl.candlestick, tvl.area, tvl.bar, tvl.baseline, tvl.histogram) returns a one-series TvlChart. Pass any number of them positionally to tvl.chart() and the series are concatenated into a single composed chart with chart-level options applied on top.

A standalone per-type call (e.g. tvl.line(table, ...)) is just shorthand for tvl.chart(tvl.line(table, ...)) with default chart options. The moment you need any chart-level option, wrap the series call in tvl.chart(..., option=value).

A composed multi-series, multi-pane chart

The example below combines the two most common composition patterns in one snippet: a candlestick price series and a moving-average line on the same upper pane, plus a histogram volume series on a stretched lower pane. It also sets a few chart-level options so the role of tvl.chart() is concrete.

Three series, two panes, one shared time axis. pane=0 / pane=1 route series into panes; pane_stretch_factors=[3, 1] makes the price pane three times the height of the volume pane; the remaining kwargs are pure chart-level styling.

Configure the chart

tvl.chart() accepts the full chart-level option set. The pages below drill into each option group.

Compose

• Multiple series. Overlaying several series on one chart.
• Multiple panes. Stacking panes inside one chart frame.
• Multiple axes. Independent price scales on one pane.

Annotate

• Titles and legends. Chart title (via watermark) and the in-chart legend driven by per-series title=.
• Markers. Circles, squares, or arrows attached to a series at specific points in time to flag events.
• Price lines. Horizontal lines drawn across a series at a fixed or table-driven price level.
• Watermark. Faint label drawn behind the data, for the ticker symbol, dataset name, or chart title.

Style

• Styling. Colors, fonts, grid, crosshair, layout.
• Time scale. The horizontal axis.
• Price scale. The vertical axes.
• Price formats. Number formatting on price labels.

API Reference

A single-series chart is most often created by the per-type constructor directly (e.g. tvl.area(t, timestamp="T", value="V")). Reach for tvl.chart(...) when you want multi-series, multi-pane, or fine-grained chart styling.

Returns: TvlChart A chart object that can be displayed in Deephaven.

Parameters	Type	Default	Description
*sources	TvlChart		One or more per-type construction results (e.g. tvl.candlestick(...), tvl.line(...)). Their series are merged in order; the pane each series targets comes from its pane= argument (default pane 0).
chart_type	Optional[ChartType]	None	Selects the horizontal scale backend. See ChartType for the allowed values ("standard" (default), "yield_curve", "options", "custom_numeric").
base_resolution	Optional[int]	None	The base time resolution in seconds — controls how the maturity axis is rendered.
minimum_time_range	Optional[int]	None	Minimum visible time range in maturity units.
start_time_range	Optional[int]	None	Initial visible time range.
background_color	Optional[Color]	None	Solid background color as a CSS color string (e.g. "#1a1a2e"). Mutually exclusive with the gradient pair.
background_top_color	Optional[Color]	None	Top color for a vertical gradient. Must be set together with background_bottom_color.
background_bottom_color	Optional[Color]	None	Bottom color of the gradient; pair with background_top_color.
text_color	Optional[Color]	None	Default text color for axis labels and tooltips.
font_size	Optional[int]	None	Base font size in pixels for axis labels and tooltips.
attribution_logo	Optional[bool]	None	Show the TradingView attribution logo (default True).
color_space	Optional[ColorSpace]	None	Canvas color space — see ColorSpace.
hovered_series_on_top	Optional[bool]	None	Render the hovered series above its siblings in the same pane (default True).
default_visible_price_scale_id	Optional[PriceScaleId]	None	Default price scale ("left" / "right") for series that do not specify one.
grid	Optional[Grid]	None	Grid-line configuration built with grid() / grid_lines(), e.g. grid=tvl.grid(vert=tvl.grid_lines(visible=False)).
crosshair	Optional[Crosshair]	None	Crosshair configuration built with crosshair() / crosshair_line(), e.g. crosshair=tvl.crosshair(mode="magnet", vert_line=tvl.crosshair_line(color="#aaa")).
right_price_scale	Optional[PriceScale]	None	Right price-scale styling/behavior built with price_scale().
left_price_scale	Optional[PriceScale]	None	Left price-scale config built with price_scale().
overlay_price_scale	Optional[PriceScale]	None	Default styling for overlay (stub) price scales, built with price_scale(). One PriceScale instance can be reused across all three slots.
time_scale	Optional[TimeScale]	None	Time-axis configuration built with time_scale(), e.g. time_scale=tvl.time_scale(time_visible=True, bar_spacing=8).
watermark	Optional[Watermark]	None	Text watermark built with watermark() — single-line (text=) or multi-line (lines=[tvl.watermark_line(...)]).
watermark_image	Optional[WatermarkImage]	None	Image watermark built with watermark_image(); coexists with a text watermark.
handle_scroll	Optional[bool | Scroll]	None	True / False toggles all scroll interactions at once; pass scroll() for per-gesture control.
handle_scale	Optional[bool | Scale]	None	True / False toggles all scale/zoom interactions at once; pass scale() for per-gesture control.
kinetic_scroll_touch	Optional[bool]	None	Enable kinetic scrolling on touch devices.
kinetic_scroll_mouse	Optional[bool]	None	Enable kinetic scrolling with the mouse.
price_formatter	Optional[PriceFormatter]	None	Price formatter preset; see PriceFormatter.
locale	Optional[str]	None	BCP 47 locale string for number formatting (e.g. "en-US").
tickmarks_price_formatter	Optional[TickmarksPriceFormatter]	None	Tick-label price formatter; see TickmarksPriceFormatter.
percentage_formatter	Optional[PercentageFormatter]	None	Crosshair percentage formatter; see PercentageFormatter.
tickmarks_percentage_formatter	Optional[TickmarksPercentageFormatter]	None	Tick-label percentage formatter; see TickmarksPercentageFormatter.
pane_separator_color	Optional[Color]	None	Color of the lines between panes.
pane_separator_hover_color	Optional[Color]	None	Pane separator color when hovered.
pane_enable_resize	Optional[bool]	None	Allow the user to resize panes by dragging separators.
pane_stretch_factors	Optional[list[float]]	None	Relative stretch factor per pane (longer list = more panes).
pane_preserve_empty	Optional[list[bool]]	None	Per-pane flag — if True, the pane is kept visible even when empty.
tracking_mode_exit_mode	Optional[TrackingModeExitMode]	None	When the touch-device tracking mode exits; see TrackingModeExitMode.
add_default_pane	Optional[bool]	None	Add a default pane on chart creation (default True). Set False for advanced multi-pane setups that fully specify their own panes.
tooltip	Optional[Tooltip]	None	Tracking-tooltip configuration built with tooltip() — a small overlay that follows the cursor and shows the focused series' title, value, and time. Constructing a tvl.tooltip(...) enables it; its colors come from the active Deephaven theme (no color options). In a multi-series chart it shows the single series under the cursor (falling back to the one whose value is nearest).
on_press	Optional[PressEventCallable]	None	Server-side callback invoked when the user presses (clicks) on the chart. Receives a TvlPressEvent dict (or no argument). See deephaven.plot.tradingview_lightweight.events.
on_double_press	Optional[PressEventCallable]	None	Server-side callback invoked when the user double-presses on the chart.