Openalgo Charts

OpenAlgo Charts skill

openalgo-charts is a from-scratch, dependency-free HTML5-canvas charting engine: one canvas pipeline, no SVG, no DOM per bar, eight lazy-loaded bundle tiers, zero runtime dependencies.

Works the same whether the project is a downstream npm consumer app or an upstream openalgo-charts source checkout. Detect which one you are in and resolve every API name from whatever typings are locally available.

Source lookup order

Do not assume you are inside the upstream source repository.

1. In a consumer app, inspect the installed package first:
   • node_modules/openalgo-charts/package.json for the actual version.
   • node_modules/openalgo-charts/dist/index.d.ts for the base API surface, and dist/{trade,draw,indicators,transform,profile,webgl,widget}/index.d.ts for each tier.
2. In the upstream repo, inspect dist/index.d.ts first, then src/ if generated output is unavailable.
3. ARCHITECTURE.md and website/pages/docs/*.mdx are supporting evidence, but local typings win when they disagree.

Verify before answering (copy-paste):

node -p "require('./node_modules/openalgo-charts/package.json').version"
rg -n "createChart|addSeries|addIndicator|DrawingController|OrderEngine" node_modules/openalgo-charts/dist/index.d.ts
# upstream checkout instead of a consumer app:
rg -n "createChart|addSeries|addIndicator" dist/index.d.ts src/index.ts
# which tiers does this project actually load?
rg -n "from 'openalgo-charts" src app

If the relevant file is unavailable, say what could not be verified. Do not invent option names, methods, exports, event names, or indicator ids.

Mental model

Eight layers, in dependency order. Most bugs come from confusing one for another.

1. Chart - createChart(container, options) returns a Chart. One chart per container element. It owns everything below.
2. DataLayer - one per chart. Merges every series by time onto a single shared logical index space 0..N-1. This is the load-bearing idea; see rule 2 below.
3. Scales - chart.timeScale maps logical index to x; each pane's PriceScale maps price to y. Panes autoscale independently.
4. Panes - vertically stacked drawing regions, each with two canvases (base + overlay) and up to three price scales ('right', 'left', '' overlay).
5. Series - chart.addSeries(type, options) returns a SeriesApi. The type names an entry in the chart-type registry; the core never switches on type.
6. Registries - chart types, indicators, and drawing tools are all descriptors in a Map. Adding one is a registration, never a core change.
7. Primitives - the extension point. Anything that draws but is not a series: price lines, markers, legends, profiles, trading pills, drawings.
8. Tiers - indicators, draw, transform, profile, trade, webgl are separate bundles that register into the base engine's registries on import; widget sits above them all and is the one tier that builds DOM.

Install and tiers

npm install openalgo-charts

Import only what you use. Each tier is a separate entry point that registers into the base engine, so a feature you do not load costs zero bytes.

Limits are the CI-enforced budgets in .size-limit.json. Measured on the 2.0.2 build: base engine 66.45 KB against 67 KB, draw tier 25.82 KB against 26 KB, indicator tier 27.27 KB against 30 KB, widget tier 35.56 KB against 36 KB, a widget terminal (base + draw + indicators + widget, what one createWidget call loads) 155.09 KB against 156 KB, and the whole package 182.39 KB against 183 KB. The aggregate budget always sits above the sum of the tier ceilings it contains, or it would fail while every tier it contains passes. Nothing is excluded from these figures because there are no runtime dependencies to exclude; the exact table is in bundling-and-tiers.

The clipboard lives in the draw tier, not the base one, because it needs the drawing-tool registry. DrawingClipboard and friends come from openalgo-charts/draw.

The 60-second chart

import { createChart } from 'openalgo-charts';

const chart = createChart(document.getElementById('chart')!);
const series = chart.addSeries('candlestick');

series.setData([
  { time: 1705286700, open: 100, high: 101, low: 99.5, close: 100.6, volume: 1200 },
  { time: 1705286760, open: 100.6, high: 101.4, low: 100.2, close: 101.1, volume: 900 },
]);

chart.fitContent();

time is UTC seconds. The container must have a non-zero size before the chart can lay out.

Non-negotiable rules

1. Time is UTC seconds everywhere, never milliseconds. Math.floor(Date.now() / 1000), not Date.now(). Feed adapters convert broker formats at the edge. Which wall clock those seconds are labelled in is ChartOptions.timezone, an IANA name defaulting to Asia/Kolkata; never offset the timestamps themselves to fake a zone, or every session anchor and gap moves with them.
2. The time axis is gapless and index-based, not timestamp-proportional. x is logicalIndex * barSpacing, so weekends, holidays and session breaks have no index and collapse to nothing. Never compute an x from a timestamp difference; use chart.timeToCoordinate(t) or chart.timeScale.
3. One bar per time per series, ascending. Duplicate times collapse to the last one written.
4. Nothing crosses a chart boundary as a logical index. Sync by instant. Because rule 2 makes the index a property of that chart's own bars, index 300 is a different moment on every chart in a grid. Any value passed between charts (a linked crosshair, a shared viewport, a highlighted bar) converts index to time on the sender with indexToTimeFloat and time back to index on the receiver with timeToIndex / timeToIndexFloat, against that chart's own DataLayer. createLinkGroup, followerIndex and followerRange do this; a hand-rolled b.setVisibleLogicalRange(a.getVisibleLogicalRange()) does not, and it looks correct until the two charts hold different bars. An instant outside the receiver's first or last bar is an absence: draw nothing rather than clamping to an edge bar. See chart-linking.
5. Never cache the forming bar. A closed bar is immutable; the last bar is alive until its interval ends. Serving a snapshot of it puts a stale close on the last-price line, the axis tag, the header LTP and every indicator computed off it, with no spinner and no staleness badge. withBarCache drops trailing unclosed bars for this reason. A fast wrong price is a worse failure than a slow right one on a chart that draws Buy and Sell buttons.
6. Never deep-import. import { X } from 'openalgo-charts' or a published tier specifier only. A deep path into dist/ internals inlines a second copy of the registry Map, and createChart will never see what your tier registered. See rollup.config.js.
7. A tier must be imported before its features resolve. chart.addIndicator('macd') needs import 'openalgo-charts/indicators'; addSeries('kagi') needs import 'openalgo-charts/transform' and throws a specific tier-naming error without it.
8. Price-scale margins are fractions of the pane height, not padding on the data span. The data band occupies 1 - marginTop - marginBottom of the pane.
9. Drawing anchors are { time, price }, never pixels. Pixel anchors slide the moment a gap collapses or the user zooms.
10. Canvas drawing happens in bitmap pixels. Multiply media px by dpr in any custom primitive, or it blurs and misaligns on HiDPI.
11. chart.trading renders trade state; it does not place orders. The host pushes exchange state in and turns the emitted trading:* events into broker calls. The transactional path is openalgo-charts/trade.
12. The engine ships no DOM chrome; openalgo-charts/widget is the one tier that does. The base and the six engine tiers have no toolbar, no dialogs, no settings forms, no command palette. Drawing tools, indicator settings, replay transports and order menus are the host's UI, driven by descriptors and events. A host that does not want to write that chrome imports the widget tier and calls createWidget (see widget); a host that does gets the description of that UI: chartSettingsSchema(chart) for a settings dialog, the contextmenu event for a right-click menu, and chart.priceAxisState(...) for a menu raised on a price axis. Chrome you write is held to the UI standard in themes-and-styling: styled scrollbars, small square swatches, paired up/down colours on one row, themed form controls, and no control with nothing behind it.
13. A control with no data in the current context is rendered disabled, not hidden. PriceLevels.available(kind) and PriceAxisState.active / scaled / movable exist to be read for exactly this. Hiding it loses the information that the state is off.
14. Never use emojis or icons in code, comments, logs, or generated UI text. Project rule.

References

Detailed reference for each topic is in references/. Read the one that matches the task before writing code.

Triage

Core API cheat sheet

Verified names. Get these wrong and nothing works.

// chart
const chart = createChart(el, options);
chart.addSeries(type, { paneIndex, style, priceScaleId, priceFormat });
chart.addIndicator(id, settings, { paneIndex });   // needs the indicators tier
chart.addPriceLine(opts, paneIndex);
chart.addPrimitive(primitive, paneIndex);
chart.fitContent();
chart.applyOptions({ theme, grid, canvas, statusLine, priceScale, priceFormatter, timeFormatter, timezone, crosshairMode });
chart.setTheme(theme);
chart.setTimezone('America/New_York') / chart.timezone();   // IANA name, default 'Asia/Kolkata'
chart.panes();                          // readonly Pane[]
chart.primarySeries() / chart.primarySeriesInfo();
chart.setCanvasOptions(opts) / chart.setStatusLineOptions(opts) / chart.setPriceScaleOptions(opts);
chart.setAxisChromeOptions({ sessionClock: true, barCountdown: true }) / chart.axisChromeOptions();

// one price axis at a time (what a menu on an axis strip acts on)
chart.priceAxisState(paneIndex, scaleId);               // PriceAxisState | null
chart.setPriceAxisOptions(paneIndex, scaleId, patch);
chart.setPriceAxisAutoFit(paneIndex, scaleId, on);
chart.setPriceAxisLockRatio(paneIndex, scaleId, on);    // boolean
chart.movePriceAxis(paneIndex, 'right', 'left');        // boolean
PRICE_SCALE_MODES;                      // ['linear','logarithmic','percentage','indexed-to-100']
chart.getState() / chart.restoreState(state);
chart.on(event, cb);                    // returns an unsubscribe function
chart.subscribeCrosshairMove(cb);
chart.timeToCoordinate(t) / chart.coordinateToTime(x);
chart.priceToCoordinate(p, paneIndex) / chart.coordinateToPrice(y, paneIndex);
chart.destroy();                        // idempotent; emits 'destroy', then drops every listener
chart.isDestroyed;                      // getter, not a method

// getters, not methods
chart.timeScale;   // TimeScale
chart.dataLayer;   // DataLayer
chart.trading;     // TradingController, created on first access
chart.shortcuts;   // ShortcutManager | null

// series handle
series.setData(items);
series.update(item);
series.prependData(items);
series.getData();
series.applyOptions({ visible: false });   // not setStyle
series.priceScale();
series.createMarkers();
series.remove();

// headless controllers, base bundle, no tier import
new ReplayController(chart, { bars, startIndex, barMs });  // seek/step/play/pause/stop/state
addComparison(chart, { symbol, bars });                    // setBars/remove/list/alignment
chartSettingsSchema(chart) / readChartSettings(chart) / applyChartSettings(chart, patch);

// linked chart grid (base bundle). Syncs by INSTANT, never by logical index.
const group = createLinkGroup({ crosshair: true, viewport: true, symbol: false, whenMissing: 'nearest' });
group.add(chart, { symbol: 'RELIANCE', onSymbol: (s, c) => loadBars(s, c) });
group.remove(chart) / group.setOptions(patch) / group.setSymbol(chart, s) / group.destroy();
group.members() / group.has(chart) / group.symbol() / group.crosshairIndex(chart);
followerIndex(followerDataLayer, timeSec, 'nearest' | 'hide');   // number | null
followerRange(leaderDataLayer, followerDataLayer, range);        // LogicalRange | null

// warm-load bar cache: wraps ANY DataFeed (base bundle)
const feed = withBarCache(sourceFeed, { ttlMs, max, maxBars, storage, now, intervalSeconds });
feed.getBars({ symbol, exchange, interval, from, to, noCache: true });
feed.invalidate({ symbol, exchange, interval }) / feed.clear() / feed.stats() / feed.source;

// interval registry (base bundle): a bucketing rule, not a duration
registerInterval({ code: '1MO', bucketing: { mode: 'calendar', unit: 'month', count: 1 } });
resolveInterval(code)        // throws UnknownIntervalError
tryResolveInterval(code) / isKnownInterval(code) / registeredIntervals() / unregisterInterval(code);
bucketStartOf(bucketing, timeSec, zone?) / nextBucketStart(...) / isTimeBucketed(bucketing);

// drawing clipboard (draw tier) - all async
await draw.copy(target?) / await draw.cut(target?) / await draw.paste();
draw.clipboard().lastError();

// reference levels (a primitive: previous close, session high/low, bid/ask, ...)
const levels = new PriceLevels({ levels: { previousClose: { line: true, label: true } } });
chart.addPrimitive(levels, 0);
levels.setLevel(kind, patch) / levels.setQuote(q) / levels.values() / levels.available(kind);
computePriceLevels({ bars, anchorTime });   // the same numbers, pure, no canvas

chart.fitContent() takes no arguments; chart.timeScale.fitContent(barCount) does.

Code-generation rules

• Verify option names against local typings before writing them. Many similarly named options exist at chart, series, pane and scale level. Confirm which level owns the option.
• Minimal snippets. One feature per code block. Combining an indicator, a drawing tool and a trading line in one snippet hides which API does what.
• Import from the package entry or a published tier specifier. Never a deep path.
• Match the user's host. A React user wants the effect lifecycle; a vanilla user does not; a no-bundler user needs the standalone build.
• State which tier a feature needs whenever the answer uses one.
• Do not invent. If a name does not appear in the installed typings or upstream source, it does not exist.

Answer contract

When answering an openalgo-charts question:

1. Name the API and the tier it lives in.
2. Show one minimal snippet, not a mega-demo.
3. Call out the main foot-gun for that task, from pitfalls.
4. Say what local source was checked (version, typings), or state that it could not be verified.