# 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.

```python order=composed,ohlc
import deephaven.plot.tradingview_lightweight as tvl

ohlc = tvl.data.ohlc()

bars = tvl.candlestick(ohlc, pane=0)
ema = tvl.line(
    ohlc, timestamp="Timestamp", value="Ema",
    color="#ff9800", line_width=2, pane=0, title="EMA(20)",
)
volume = tvl.histogram(
    ohlc, timestamp="Timestamp", value="Volume",
    color="rgba(96,165,250,0.5)", pane=1, title="Volume",
)

composed = tvl.chart(
    bars,
    ema,
    volume,
    pane_stretch_factors=[3, 1],
    crosshair=tvl.crosshair(mode="magnet"),
    time_scale=tvl.time_scale(time_visible=True),
)
```

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](multi-series.md). Overlaying several series on one chart.
- [Multiple panes](multi-pane.md). Stacking panes inside one chart frame.
- [Multiple axes](multiple-axes.md). Independent price scales on one pane.

**Annotate**

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

**Style**

- [Styling](styling.md). Colors, fonts, grid, crosshair, layout.
- [Time scale](time-scale.md). The horizontal axis.
- [Price scale](price-scale.md). The vertical axes.
- [Price formats](price-formats.md). 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.

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