Chart Instance

createChartBridge(canvas, options) returns a chart instance — a plain JavaScript object exposing 80+ methods grouped by topic. This page documents the lifecycle methods you'll always use. Topic-specific methods live on the same instance and are documented on their own pages.

const chart = await createChartBridge(canvas, { licenseKey: '...' })

chart.start()        // ← lifecycle
chart.setTheme()     // ← display
chart.setKlines()    // ← data
chart.enableRsi()    // ← indicators
chart.addTrendline() // ← drawings
// …

Lifecycle

chart.start()

Boots the internal render loop. After this call, the chart paints whenever there's something new to draw, and stays idle otherwise (zero CPU on a steady chart).

Call start() once after the first data load. Calling it again on an already-running chart is a no-op.

chart.stop()

Pauses the render loop and cancels any pending requestAnimationFrame. The chart stays on screen at the last frame. Useful when:

• A modal opens over the chart and you want to free GPU time.
• The user switches to a different tab in your app (but you don't want to destroy the chart, just freeze it).
• You're entering a long batch of setKlines() / setHeatmap() calls and want to skip intermediate renders.

After stop(), call start() to resume.

chart.destroy()

Tears down the chart: cancels the render loop, removes event listeners (mouse, touch, keyboard, resize observers), releases the engine module, and clears the canvas.

Always call destroy() when your component unmounts. Forgetting this leaks ~5–20 MB of engine memory per component instance and keeps an event-listener fan-out alive on a detached DOM node.

// React
useEffect(() => {
  let chart
  ;(async () => {
    chart = await createChartBridge(canvasRef.current, { licenseKey })
    chart.start()
  })()
  return () => chart?.destroy()
}, [])

// Vue 3
let chart
onMounted(async () => {
  chart = await createChartBridge(canvasRef.value, { licenseKey })
  chart.start()
})
onBeforeUnmount(() => chart?.destroy())

chart.resize(retries?)

Re-reads the canvas's getBoundingClientRect() and resizes the internal framebuffer to match. Call this when:

• The chart's container changes size (sidebar open/close, window resize, orientation change).
• The chart was created inside a hidden parent and the parent later becomes visible.
• DevicePixelRatio changes (user drags the window between two monitors with different DPR).

The chart does not auto-watch its parent's size — that costs a ResizeObserver per chart instance. Wire your own ResizeObserver once at the top of your app:

const ro = new ResizeObserver(() => chart.resize())
ro.observe(canvas.parentElement)

The optional retries argument tells the engine to retry up to N times if the parent's size is still 0 (race condition during mount). Default is sufficient for 99 % of cases; bump it to 3 if you create the chart inside an animated reveal.

Render scheduling

The chart redraws automatically when:

• Data changes (setKlines, appendKline, setHeatmap, …).
• View changes (pan, zoom, theme switch, indicator toggle).
• The canvas resizes.

You almost never need to trigger a redraw manually. The two exceptions:

chart.renderFrameNow()

Force one synchronous redraw before the next animation frame. Useful for:

• Taking a screenshot (canvas.toDataURL()) right after a data load.
• Hand-off scenarios where you're swapping the underlying canvas and need the last frame stable.

chart.renderSync()

Same as renderFrameNow() but bypasses internal dirty tracking. Always renders even when nothing changed. Use only if you've been bitten by the cache and need a hard refresh — 99 % of the time renderFrameNow() is what you want.

Pausing render mid-update

Some workflows update many things in one go (setKlines + four indicator changes + a theme swap). The render loop coalesces these into one frame for free, so most users don't need to do anything. For the rare case where you want to bound render cost:

chart.stop()
chart.setKlines(t, o, h, l, c, v)
chart.enableRsi()
chart.setMacd(true)
chart.setTheme('light')
chart.start()  // single render with all the changes applied

Display settings

chart.setTheme(theme)

Each theme sets the full palette: background, grid, candle bull/bear, wick, crosshair, price-axis text, and indicator colors. To customise individual colors after the theme swap, call the relevant setX method below.

The full color customisation surface — candle bodies / wicks / borders, grid alpha, crosshair style / width / magnet, last-price-line dash, background gradient, layer hide-toggles — lives on its own page: Theming & Colors.

chart.setPrecision(digits)

For BTC: 2. For altcoins under $1: 4 or 6. The engine does not auto-detect — set this once on data load.

chart.setCandleInterval(seconds)

Tells the engine how many seconds each candle covers. Drives the time-axis grid spacing, the gap behaviour between candles, and the "candle is forming" state for the last bar.

Candle colors

chart.setCandleBullColor('#26a69a')        // body fill, up candles
chart.setCandleBearColor('#ef5350')        // body fill, down candles
chart.setCandleBullBorderColor('#26a69a')  // 1 px border, up candles
chart.setCandleBearBorderColor('#ef5350')  // 1 px border, down candles
chart.setCandleBullWickColor('#26a69a')    // wick, up candles
chart.setCandleBearWickColor('#ef5350')    // wick, down candles

All six take a CSS hex string (with or without #). Effect is immediate.

Background, grid, crosshair

chart.setBackgroundColor('#0B0E11')   // chart background
chart.setGridColor('#1f2429')         // grid lines
chart.setGridHVisible(true)           // horizontal grid lines on/off
chart.setGridVVisible(true)           // vertical grid lines on/off

chart.setCrosshairColor('#787b86')    // crosshair color
chart.setCrosshairWidth(1)            // pixels
chart.setCrosshairStyle('dashed')     // 'solid' | 'dashed' | 'dotted'
chart.setCrosshairMagnet(true)        // snap to nearest candle close

Y-axis scaling

chart.setYAutoScale(true)             // auto-fit visible candles
chart.setLastPriceLine(true)          // draw the "current price" horizontal line

When setYAutoScale(false), the user is in manual scale mode (they're dragging the Y axis). Restore auto-fit by calling setYAutoScale(true).

Querying the chart

chart.getTheme()

Returns 'dark' or 'light'.

chart.getYAutoScale()

Returns the current auto-scale state. false means the user has manually scaled the Y axis.

chart.getKlineVisible()

Returns true if the candle layer is on screen, false if it was hidden via setKlineVisible(false) (e.g. when running an indicators-only view).

chart.getLastClose()

Returns the close price of the most recently appended candle, or null if no data is loaded. Cheaper than reading from your own data array because the engine already has it in memory.

Events

The chart instance exposes a small set of event hooks. Each takes a callback function or null to detach. Listeners are torn down automatically on destroy().

chart.onTooltip((data, sx, sy) => {
  // data: JSON string with the hovered bar's OHLCV + indicator values.
  // sx, sy: screen coordinates of the crosshair.
})

chart.onCrosshairMove((sx, sy, zone) => {
  // sx, sy: crosshair pixel position.
  // zone: 0 = main pane, 1+ = indicator subpanes.
})

chart.onPanEnd(() => {
  // Fired when the user releases a pan gesture. Good place to trigger
  // historical kline fetches for infinite scroll.
})

chart.onPostRender(() => {
  // Fired after every frame paint. Avoid expensive work here — runs at
  // up to 60 Hz during interactions.
})

For drawing-specific events (selection, double-click), see Drawing.

Next

• Data Loading — setKlines, appendKline, updateLastKline, and the real-time update pattern.
• Theming & Colors — the full color customisation surface: candles, background, grid, crosshair, last price line, fonts, layer visibility.
• Events & Tooltips — read what's under the cursor and render your own tooltip in your own DOM.
• Orderbook Heatmap — the depth-as-heatmap layer behind the candles.
• Indicators — enable / disable / configure each of the 18+ built-in indicators.
• Performance & Smoothness — when to call pause / resume, how to handle resize, what to do on visibilitychange.