[!NOTE]

Candlekit is a vibe-coded project — designed and built rapidly and iteratively with AI-assisted development. It is functional, tested (CI green, with a Vitest suite under /tests), and documented, but treat it as early-stage software: pin a version, read the changelog before upgrading, and open an issue if something looks off.

Drawing tools — trendline, rectangle, Fibonacci, measurement ruler

Built-in indicators — Bollinger, EMA/SMA, RSI, MACD, Stochastic — toggled live

Measurement ruler — Shift-drag for % move, points, bars · time

▶ Open the live demo — drawing, indicators, measurement and replay in one chart

---

Overview

candlekit/charts wraps lightweight-charts with the pieces a real trading UI needs but the base library leaves to you: a stable chart controller, a runtime-agnostic drawing engine, an extensible indicator framework, a Shift-drag measurement ruler, multi-chart sync, broker integration and a deterministic historical replay engine. The core is framework-agnostic (no React, no DOM framework); the optional /react entry adds components and hooks.

It is plugin-first: drawing, indicators, and measurement are all ChartPlugins you can swap, extend, or omit. Drawing tools and indicators are original code built on lightweight-charts canvas primitives — no third-party drawing or indicator runtime — and the side-effect-free modules let tree-shaking drop whatever you don't import.

Features

• Core charting — candlestick, OHLC bars, line, area, volume; multiple

timeframes via a session-aware resampler; responsive auto-resize; light/dark themes with full color override.

• Drawing tools — trend line, ray, extended line, horizontal/vertical line,

arrow, rectangle, circle, Fibonacci retracement, with selection, drag-to-move, handle reshaping, locking, and persistence. Original engine rendered on lightweight-charts canvas primitives — no third-party drawing runtime.

• Indicators — extensible registry + a built-in catalog (SMA, EMA, WMA,

VWAP, Bollinger Bands, RSI, MACD, ATR, Stochastic), all original implementations. Register your own with one call.

• Measurement — price, percentage, bar-distance, time-delta, and

risk/reward, painted as a canvas ruler.

• Replay — deterministic playback over historical bars: play/pause, step

±1, speed control, seek/jump, per-bar event hooks, per-day LRU cache with pre-fetch.

• Lab (experimental) — pattern-similarity analytics over your own bars.

Echoes ("market déjà vu") finds historical windows that look like the recent price action, bands them, and projects the median of what happened next; Sketch Search matches a freehand shape you draw against history. Pure, dependency-free math + optional plugins and a React panel.

• Architecture — TypeScript, fully typed public API, tree-shakeable ESM +

CJS, event system, plugin system, and extensible data-source / indicator / drawing frameworks.

Replay

Deterministic replay — play/pause, step ±1, speed control, seek/jump

Lab — Sketch Search & Echoes

Echoes — similar past windows + median projection · Sketch Search — draw a shape, find look-alikes

Two experimental pattern-similarity tools, computed on z-normalized closes (shape, not price level), so look-alikes are found across regimes:

• Echoes — takes the last N closes as a query, finds the most similar

non-overlapping windows in history, bands them on the chart, and projects the median of what happened next forward from the last bar.

• Sketch Search — draw a freehand shape across the chart; it is resampled

and matched against history the same way.

The math (zNormalize, findSimilar, buildEchoScan, resampleStroke) is pure and dependency-free; the chart plugins (SketchSearchController, EchoesController) and the React <EchoesPanel> / <SketchSearchButton> are optional. See Lab Examples below, the full Lab guide, and examples/lab for a runnable demo.

Try it live in examples/lab (cd examples/lab && npm i && npm run dev).

The GIF above is regenerated by SCENE=lab node scripts/capture-demo.mjs.

Installation

npm install @getcandlekit/charts lightweight-charts
React bindings (optional):
npm install react react-dom

That's it. lightweight-charts is the only runtime dependency (a peer, so you control its version); react/react-dom are needed only for @getcandlekit/charts/react. Drawing tools and indicators are built in — no extra packages, no git installs.

Quick Start

Vanilla JS / TypeScript

import { ChartController, toBars } from "@getcandlekit/charts";
const el = document.getElementById("chart")!; const chart = new ChartController(el, { theme: "dark", seriesType: "candlestick" });
chart.setData(toBars(myRows)); // myRows: { ts, open, high, low, close, volume }[]

React

import { ChartView } from "@getcandlekit/charts/react";
import "@getcandlekit/charts/styles.css";
export function App({ bars }) {   return (     <div style={{ height: 480 }}>       <ChartView data={bars} seriesType="candlestick" theme="dark" />     </div>   ); }

Basic Examples

Switch series type and timeframe:

chart.setSeriesType("area");       // candlestick | ohlc | line | area
chart.setData(resample(rows, 5));  // 5-minute candles from 1-minute rows
chart.setTheme("light");

Live updates:

ws.onBar((bar) => chart.updateBar(bar)); // appends or replaces the last bar

Advanced Examples

Session-aware resampling (align buckets to a 09:30 market open instead of UTC midnight):

import { resample } from "@getcandlekit/charts";
const candles = resample(rows, 15, { sessionOpenMinutes: 9 * 60 + 30 });

Fixed-offset exchange time (render an always-UTC+5:30 market in wall-clock):

import { applyFixedOffset } from "@getcandlekit/charts";
const shifted = rows.map((r) => ({ ...r, ts: applyFixedOffset(r.ts, 330) }));

Replay Examples

import { createReplayController } from "@getcandlekit/charts";
const replay = createReplayController(); replay.onBar((e) => chart.updateBar(e.bar)); await replay.load({   id: "demo",   series: [{ symbol: "AAPL", interval: "1m" }],   start: Date.parse("2024-01-02T14:30:00Z"),   end: Date.parse("2024-01-03T21:00:00Z"),   source: myReplayDataSource, // implements ReplayDataSource }); replay.setSpeed(8); replay.play();

React transport bar:

import { ReplayControls } from "@getcandlekit/charts/react";
<ReplayControls controller={replay} />

Drawing Tool Examples

import { ChartView, DrawingToolbar } from "@getcandlekit/charts/react";
// drawing accepts true, an options object, or a DrawingController instance. <ChartView data={bars} drawing={{ storageKey: "drawings:AAPL" }}>   <DrawingToolbar /> </ChartView>;

Imperative (vanilla):

import { ChartController, DrawingController } from "@getcandlekit/charts";
const chart = new ChartController(el); const drawing = new DrawingController({ storageKey: "drawings:AAPL" }); chart.use(drawing); drawing.engine.startTool("TrendLine");

Indicator Examples

import { ChartView, IndicatorPicker, IndicatorController, createBuiltinRegistry } from "@getcandlekit/charts/react";
const indicators = new IndicatorController(createBuiltinRegistry()); indicators.add("RSI", { length: 14 }); indicators.add("EMA", { length: 21 });
<ChartView data={bars} indicators={indicators}>   <IndicatorPicker /> </ChartView>;

Register a custom indicator (the extension point):

import { IndicatorRegistry } from "@getcandlekit/charts";
const registry = new IndicatorRegistry().register({   name: "PriceMid",   title: "HL/2",   shortTitle: "MID",   category: "overlay",   defaultInputs: {},   inputConfig: [],   plotConfig: [{ id: "mid", color: "#f59e0b" }],   hlineConfig: [],   calculate: (bars) => ({     plots: { mid: bars.map((b) => ({ time: b.time, value: (b.high + b.low) / 2 })) },   }), });

Lab Examples

React (<ChartView> hosts the plugins; the components drive them):

import { ChartView, SketchSearchButton, EchoesPanel } from "@getcandlekit/charts/react";
import "@getcandlekit/charts/styles.css";
<ChartView data={bars} sketch echoes={{ windowLen: 30, horizon: 30, k: 8 }}>   <SketchSearchButton />  {/ toggle, then drag a shape on the chart /}   <EchoesPanel />         {/ Scan → bands + median projection + stats /} </ChartView>;

Imperative (vanilla — same plugins, your own UI):

import { ChartController, EchoesController, SketchSearchController } from "@getcandlekit/charts";
const chart = new ChartController(el); chart.setData(bars);
const echoes = new EchoesController({ windowLen: 30, horizon: 30, k: 8 }); chart.use(echoes); echoes.subscribe((scan) => scan && console.log(scan.stats)); // { count, upCount, medianEndPct, ... } echoes.run();
const sketch = new SketchSearchController({ onResult: (r) => console.log(r?.matches) }); chart.use(sketch); sketch.setActive(true); // arm; drag a freehand shape, release to search

Pure math, no chart (search any series of closes):

import { findSimilar, buildEchoScan } from "@getcandlekit/charts";
const matches = findSimilar(closes, closes.slice(-30), { k: 5 }); // [{ startIndex, endIndex, distance }] const scan = buildEchoScan(bars, 30, 30, 8);                      // window/horizon/k → null if too little history

Plugin Examples

import type { ChartPlugin } from "@getcandlekit/charts";
const lastPriceLabel: ChartPlugin = {   id: "last-price-label",   init(ctx) {     ctx.bus.on("data", ({ bars }) => {       const last = bars[bars.length - 1];       if (last) console.log("last close", last.close);     });   },   destroy() {}, };
chart.use(lastPriceLabel);

API Overview

| Export | Kind | Purpose | | --- | --- | --- | | ChartController | class | Imperative chart wrapper (data, series type, theme, plugins, events). | | toBars, resample, floorToBucket | fn | Pure data normalization + session-aware resampling. | | resolveTheme, lightTheme, darkTheme | fn/const | Theme presets + resolution. | | EventBus | class | Typed sync event bus. | | DrawingController, DrawingEngine | class | Built-in drawing plugin + its model/state. | | IndicatorRegistry, IndicatorController, createBuiltinRegistry | class/fn | Extensible indicator framework + built-in catalog. | | MeasurementController, RulerPrimitive | class | Shift-drag measurement. | | createReplayController | fn | Deterministic replay. | | createSyncEngine | fn | Multi-chart sync. | | EchoesController, SketchSearchController | class | Lab plugins — Echoes (déjà vu) + Sketch Search. | | findSimilar, buildEchoScan, zNormalize, resampleStroke | fn | Pure pattern-similarity math (no chart). | | ChartView (/react) | component | Declarative chart + plugin host. | | EchoesPanel, SketchSearchButton (/react) | component | Lab results panel + sketch toggle. |

Full reference: docs/api-reference.md.

Performance Notes

• Single offset conversion at the data boundary; drawings/replay stay in one

coordinate domain (no per-render timezone math).

• setData autoscale fits once on the first non-empty paint; later updates

preserve user pan/zoom.

• Replay uses a per-day LRU cache with backward/forward pre-fetch; the cursor

drives everything (no wall-clock coupling).

• Tree-shakeable ESM — a vanilla bundle never pulls React. Drawing and

indicators are self-contained (no extra runtime deps to load).

Browser Support

Evergreen browsers (Chrome, Edge, Firefox, Safari) with Canvas + ResizeObserver. ESM and CJS builds are shipped; target: es2020.

Roadmap

• [ ] Text + freehand/brush drawing tools
• [ ] Indicator settings UI (param editing) in the React picker
• [ ] Crosshair tooltip component
• [ ] More indicators (Ichimoku, SuperTrend, Keltner)
• [ ] Vue / Svelte bindings
• [ ] Screenshot/export helper

Star History

If candlekit saves you from stitching repos together, a ⭐ helps others find it.

Contributing

See CONTRIBUTING.md and AGENTS.md. In short: npm install, npm run typecheck && npm run lint && npm run test && npm run build.

License

MIT — see LICENSE. Third-party attributions in NOTICE. "Lightweight Charts™" is a trademark of TradingView, Inc.; this project is not affiliated with TradingView.