ChartCanvas & panes

The chart root, vertically stacked panes and how components plug into the engine.

A chart is a tree of components:

<ChartCanvas data={bars}>
  {/* data, x axis viewport, render loop */}
  <Pane id="price" size={3}>
    {/* a vertical slot with its own price scales */}
    <CandlestickSeries />
    <YAxis />
  </Pane>
  <Pane id="momentum">
    <LineSeries y="momentum" />
    <YAxis />
  </Pane>
  <XAxis /> {/* shared by every pane */}
</ChartCanvas>

concept-panes.tsx

"use client";
import { ChartCanvas, Pane } from "@reincharts/core";
import { CandlestickSeries, LineSeries } from "@reincharts/series";
import { XAxis, YAxis } from "@reincharts/axes";
import { daily } from "@/lib/data";
import { useDocsChartTheme } from "@/lib/use-docs-theme";

// any array of objects works: here daily OHLC bars plus a "momentum" field (close vs. 10 bars earlier)
const bars = daily.map((d, i) => ({ ...d, momentum: i >= 10 ? d.close - daily[i - 10].close : undefined }));

export default function ChartCanvasAndPanes() {
    const theme = useDocsChartTheme();
    return (
        <ChartCanvas data={bars} theme={theme}>
            {/* data, x axis viewport, render loop */}
            <Pane id="price" size={3}>
                {/* a vertical slot with its own price scales */}
                <CandlestickSeries />
                <YAxis />
            </Pane>
            <Pane id="momentum">
                <LineSeries y="momentum" />
                <YAxis />
            </Pane>
            <XAxis /> {/* shared by every pane */}
        </ChartCanvas>
    );
}

ChartCanvas

<ChartCanvas> creates a ChartEngine: a plain TypeScript object that owns the data, the horizontal viewport, the panes and their price scales, the layout and a single requestAnimationFrame render loop. Children register renderables with it (anything that draws) and the engine draws them in zIndex order on two stacked canvases:

scene: grid, series, annotations, drawings, axes. Redrawn when data, the viewport or the scales change.
top: crosshair, hover highlights, in-progress drawings. Redrawn on every pointer move without touching the scene.

Without width / height the chart fills its parent and follows its size. Every prop (data mapping, initial view, interaction, sync, callbacks) is listed in the ChartCanvas API reference.

The engine ref

The ref of <ChartCanvas> is the engine itself, which exposes imperative controls:

const chart = useRef<ChartEngine<Bar>>(null);

<ChartCanvas ref={chart} data={bars}>
  {/* ... */}
</ChartCanvas>;

chart.current?.zoomIn();
chart.current?.zoomOut();
chart.current?.resetView(); // back to the initial view, re-enables autoscale
chart.current?.fitContent(); // show all data
chart.current?.scrollToRealtime(); // jump to the newest bar
chart.current?.setVisibleRange(new Date("2016-01-01"), new Date("2016-06-30"));

concept-engine-ref.tsx

"use client";
import { ChartCanvas, type ChartEngine, Pane } from "@reincharts/core";
import { CandlestickSeries } from "@reincharts/series";
import { XAxis, YAxis } from "@reincharts/axes";
import { useRef } from "react";
import { ToolbarButton, WithToolbar } from "@/components/preview/controls";
import { daily, type Bar } from "@/lib/data";
import { useDocsChartTheme } from "@/lib/use-docs-theme";

export default function EngineRef() {
    const theme = useDocsChartTheme();
    const chart = useRef<ChartEngine<Bar>>(null);
    return (
        <WithToolbar
            toolbar={
                <>
                    <ToolbarButton onClick={() => chart.current?.zoomIn()}>zoomIn()</ToolbarButton>
                    <ToolbarButton onClick={() => chart.current?.zoomOut()}>zoomOut()</ToolbarButton>
                    <ToolbarButton onClick={() => chart.current?.resetView()}>resetView()</ToolbarButton>
                    <ToolbarButton onClick={() => chart.current?.fitContent()}>fitContent()</ToolbarButton>
                    <ToolbarButton onClick={() => chart.current?.scrollToRealtime()}>scrollToRealtime()</ToolbarButton>
                    <ToolbarButton
                        onClick={() => chart.current?.setVisibleRange(new Date("2016-01-01"), new Date("2016-06-30"))}
                    >
                        setVisibleRange(…)
                    </ToolbarButton>
                </>
            }
        >
            <ChartCanvas ref={chart} data={daily} theme={theme}>
                <Pane>
                    <CandlestickSeries />
                    <YAxis />
                </Pane>
                <XAxis />
            </ChartCanvas>
        </WithToolbar>
    );
}

The engine also has resetPaneSizes() and screenshot() (a PNG data URL).

Panes

Panes stack vertically and split the height by their size (stretch factor, default 1) unless a fixed height is given; minHeight and order refine the layout. Give panes a stable id when something refers to them (drawings, saved layouts, legends of another pane).

Users resize panes by dragging the separator between two of them, and double-clicking a separator maximizes the pane below it (double-click again to restore). Dragged sizes are kept until you call resetPaneSizes() on the engine, which restores every pane's size / height props:

<button onClick={() => chart.current?.resetPaneSizes()}>Reset panes</button>

Components outside any <Pane> (series placed directly in <ChartCanvas>) go to an implicit "main" pane, so the smallest chart needs no <Pane> at all.

Each pane has named price scales: "right" by default, and any other id you reference from a series' scale prop. See Price scales.

Overlays

<ChartOverlay> positions regular DOM over a pane's plot area (or the whole chart), for legends, buttons or any HTML. Pointer events pass through to the chart unless you enable them on your own elements.

<ChartCanvas data={bars}>
  <Pane>
    <CandlestickSeries />
    <YAxis />
    <ChartOverlay>
      <div style={{ padding: 8 }}>MSFT · 1D</div>
    </ChartOverlay>
  </Pane>
  <XAxis />
</ChartCanvas>

concept-overlay.tsx

"use client";
import { ChartCanvas, ChartOverlay, Pane } from "@reincharts/core";
import { CandlestickSeries } from "@reincharts/series";
import { XAxis, YAxis } from "@reincharts/axes";
import { daily } from "@/lib/data";
import { useDocsChartTheme } from "@/lib/use-docs-theme";

export default function Overlay() {
    const theme = useDocsChartTheme();
    return (
        <ChartCanvas data={daily} theme={theme}>
            <Pane>
                <CandlestickSeries />
                <YAxis />
                <ChartOverlay>
                    <div style={{ padding: 8 }}>MSFT · 1D</div>
                </ChartOverlay>
            </Pane>
            <XAxis />
        </ChartCanvas>
    );
}

Hooks

Components inside a chart can talk to the engine with hooks. These are the building blocks of every series, axis and tool, and of your own components:

Hook	Purpose
`useChart()`	The `ChartEngine` of the closest `<ChartCanvas>`.
`usePaneId()`	Id of the closest `<Pane>` (`"main"` outside panes).
`useChartState(selector, isEqual?)`	Subscribe to layout, visible range or crosshair; re-renders only when the selection changes.
`useRenderable(spec)`	Register something that draws on the canvas. See Custom series.
`useHitTarget(spec)`	Register an interactive object (hover, click, drag).
`useChartEvent(type, handler)`	Listen to chart events: pointer events in chart coordinates, `keydown`, `rangechange`...

ChartCanvasCopy Anchor Link

The engine refCopy Anchor Link

PanesCopy Anchor Link

OverlaysCopy Anchor Link

HooksCopy Anchor Link

On this page

ChartCanvas

The engine ref

Panes

Overlays

Hooks