Openalgo Charts

OpenAlgo Charts skill

openalgo-charts is a from-scratch, dependency-free HTML5-canvas charting engine: a canvas rendering pipeline with vector export, no DOM per bar, nine bundle entry points, 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,workspace}/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 what they add on import (the draw tier into its own tool registry, the others into the base engine's registries); 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, so a feature you do not load costs zero bytes. The workspace tier is pure configuration and persistence; it registers nothing.

Limits are the CI-enforced budgets in .size-limit.json. This reference targets 2.6.0; a section marked (unreleased) is on the main branch only and is not in that release. In a source checkout, run npm run size before quoting byte counts. In a consumer app, check the installed version and measure its actual imports with the app's bundler. Reference measurements and every budget row live 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 seven non-widget optional 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.