Candela

Candela Charts docs

Install

Candela ships its own canvas engine, so there is nothing else to install.

shell
npm i @candela-trade/charts @candela-trade/adapters
main.ts
import { CandelaChart } from '@candela-trade/charts'
import { createSimulatedDatafeed } from '@candela-trade/adapters'
import '@candela-trade/charts/style.css'

const chart = new CandelaChart({
  container: document.getElementById('chart')!, // give it a height
  symbol: { ticker: 'CNDL', pricePrecision: 2 },
  period: { multiplier: 5, timespan: 'minute', text: '5m' },
  datafeed: createSimulatedDatafeed(),
  theme: 'midnight',
  mainIndicators: ['EMA', 'VPVR', 'VOL'], // VOL and MACD here sit along the bottom of the price chart
  subIndicators: ['RSI']
})

Connect data

A datafeed is four methods: searchSymbols, getHistoryBars, subscribe and unsubscribe. Use a bundled adapter or createDatafeed() for anything else.

typescript
interface Datafeed {
  searchSymbols(search?: string): Promise<SymbolInfo[]>
  getHistoryBars(symbol: SymbolInfo, period: Period, from: number, to: number): Promise<Bar[]>
  subscribe(symbol: SymbolInfo, period: Period, callback: (bar: Bar) => void): void
  unsubscribe(symbol: SymbolInfo, period: Period, callback?: (bar: Bar) => void): void
}

Adapters & proxies

Vendor API keys should not ship to browsers. Every adapter takes a baseUrl (and a stream URL) so you can route through a thin proxy that injects credentials. This one is for Next.js:

app/api/massive/[...path]/route.ts
export async function GET(req: Request, { params }: { params: Promise<{ path: string[] }> }) {
  const { path } = await params
  const url = new URL(req.url)
  const upstream = `https://api.massive.com/${path.join('/')}${url.search}`
  const res = await fetch(upstream, { headers: { Authorization: `Bearer ${process.env.MASSIVE_KEY}` } })
  return new Response(res.body, { status: res.status, headers: { 'content-type': 'application/json' } })
}

Databento's live API is raw TCP. Run a relay that subscribes with the official client and forwards JSON records over a WebSocket, using the protocol documented in @candela-trade/adapters/databento.

Theming

Seven built-in themes: midnight, daylight, aurora, terminal, nord, paper and neon (pitch black with glowing candles; any theme can glow with candle.glow). Register your own from tokens. One definition styles both the DOM chrome and the canvas.

typescript
import { registerTheme } from '@candela-trade/charts'

registerTheme({
  name: 'acme', mode: 'dark', extends: 'midnight',
  tokens: { primary: '#7C5CFF', up: '#14B8A6', down: '#FB7185', radius: 8, fontFamily: 'Inter, sans-serif' },
  chart: { grid: { show: false } }          // any canvas style override
})
chart.setTheme('acme')

Feature flags & API

typescript
new CandelaChart({
  // ...
  chartType: 'heikin_ashi',   // candle_solid | candle_stroke | candle_up_stroke | candle_volume | heikin_ashi | ohlc | area
  features: { commandPalette: true, replay: true, volumeProfile: true, countdown: true,
              themeSwitcher: false, screenshot: true, fullscreen: true, alerts: true },
})

chart.setChartType('area')
chart.startReplay(Date.parse('2026-11-03T14:30:00Z'))
chart.playReplay(10)           // bars per second; pauseReplay() / stopReplay()
chart.openCommandPalette('fib') // optional query, already typed
chart.getChart()               // the canvas engine: convertToPixel, getDataList, …

Alerts

Users create alerts from the toolbar's Alert button, the + on the price scale, a right click, ⌥A, or the bell on a selected drawing. Price alerts draw a line you can drag; alerts on trend lines, rays, horizontal lines, channels and rectangles follow the drawing bar by bar. Conditions: crossing (up, down), greater or less than, entering, exiting, inside or outside a channel, and moving up or down by an amount or a percentage within a number of bars. Triggers: only once, once per bar, once per bar close, once per minute, with an optional expiry.

Alerts belong to the page, not one chart: every chart with features.alerts on shares them and they fire once. A chart feeds in the prices it shows; symbols no chart is showing are watched through your datafeed (turn that off with watchOffscreen: false).

typescript
new CandelaChart({
  // ...
  alerts: savedAlerts,                         // restore what onAlertsChange gave you
  onAlertsChange: (alerts) => save(alerts),
  alertOptions: {
    storageKey: 'my-app-alerts',               // or let the library keep them in localStorage
    channels: [{ id: 'email', label: 'Email' }], // your own channels, offered in the dialog
  },
  onAlert: (event) => notify(event.channels, event.message), // once per firing
})

chart.createAlert({ condition: 'crossing_up', value: 182.5, trigger: 'once_per_bar_close', name: 'Breakout' })
chart.createAlert({ condition: 'crossing', source: { type: 'line', points: [a, b] } }) // a sloped level from code
chart.updateAlert(id, { status: 'paused' })
chart.openAlertDialog()                         // or openAlertDialog(id) to edit
chart.showAlerts()                              // the alerts manager and log

Pattern recognition

Two studies find patterns as they form. CHART_PATTERNS draws 35 chart patterns (head and shoulders, double and triple tops and bottoms, rounding tops and bottoms, cups, diamonds, flags, pennants, triangles, wedges, rectangles, channels, broadening formations and eight harmonic patterns) with their trigger line, projected target and invalidation. CANDLE_PATTERNS labels 19 candlestick patterns and waits for the next candle to confirm or fail each one. Both are in the indicator picker under Patterns; their settings choose the patterns, the sensitivity and how finished patterns are kept.

Each pattern moves through forming, confirmed, target or failed, deciding on closed bars only. Clicking a label opens a card with what still has to happen, the levels that matter and an alert on the next step. The detectors are exported too, for scanners and your own UI.

typescript
new CandelaChart({
  // ...
  mainIndicators: ['CHART_PATTERNS', 'CANDLE_PATTERNS'],
})

const { chart: found, candle } = chart.getPatterns()  // what the studies found
chart.openPatternCard({ id: 'head-and-shoulders' })     // the newest one's card, as if clicked

import { detectChartPatterns, detectCandlePatterns } from '@candela-trade/charts'
detectChartPatterns(bars, { sensitivity: 1 })            // 0 low, 1 medium, 2 high
// → [{ id, bias, state, points, triggers, height, target?, invalid, breakAt?, … }]
detectCandlePatterns(bars, { trend: true, trendBars: 6 })

Linked charts & events

Charts with the same drawingSyncId share the crosshair and indicator settings. drawingSync decides who shares drawings: 'symbol' (default) shares with every chart on the same ticker, 'group' only within the sync id, 'none' never.

typescript
new CandelaChart({
  // ...
  drawingSyncId: 'layout-1',
  drawingSync: 'group',
  onSync: (e) => console.log(e.kind, e.action, e.targets),   // what this chart pushed, and to which charts
  onReplay: (e) => score(e.type, e.bar),                      // start | step | end | exit
  onConfigChange: (config) => save(config),                   // drawings and indicators as plain JSON
})

// Drawings created in code stay local unless you ask for them to sync.
chart.createOverlay({ name: 'fibonacciLine', points: [a, b] }, { sync: true })
chart.overrideOverlay({ id, points }, { sync: true })
chart.setDrawingSyncId('')     // leave the group: crosshair and group drawings stop

Licence keys

Set your key once, before or after creating charts. Verification is offline. Without a valid key, production hostnames show a watermark and a console notice. Development hosts (localhost, *.local) only show a small badge.

typescript
import { LicenseManager } from '@candela-trade/charts'

LicenseManager.setLicenseKey(import.meta.env.VITE_CANDELA_KEY)
LicenseManager.subscribe((status) => console.log(status.code)) // valid | missing | invalid | expired | version | domain

Licence agreement

Candela Charts, including its canvas engine, is proprietary software covered by the Candela commercial licence agreement. The full terms ship in the package as LICENSE.md.