Openalgo Chart Indicator

Add or author an indicator. Read indicators for the full built-in catalogue with exact ids, inputs and defaults before writing code - do not guess an id. There are 112 built-ins and the ids are hyphenated lowercase, not derivable from the display name (williams-percent-r, not willr).

Arguments

• $0 = indicator id, or a plain-language name to resolve to an id.
• $1 = target pane. Default: whatever the descriptor's placement says.

Step 0 - the tier must be imported

import 'openalgo-charts/indicators';   // side effect: registers the 112 built-ins

Without it chart.addIndicator throws. Add this import once, at the app entry, not in every module. Verify it is present before adding an indicator:

rg -n "openalgo-charts/indicators" src app

If loading custom indicator modules asynchronously, await registration before adding ids or restoring layouts. Concurrent panes and pickers must share the pending promise, not a premature ready flag. The package does not load arbitrary user scripts; see host-integration.

Path A - add a built-in

chart.addIndicator('bollinger');                            // overlays the price pane
const macd = chart.addIndicator('macd', { fastPeriod: 8 }); // gets its own pane

Resolve the id against the source, not from memory. The catalogue is one array, so read it rather than grepping descriptor files:

node --input-type=module -e "import * as i from 'openalgo-charts/indicators'; for (const d of i.BUILTIN_INDICATORS) console.log(d.id, '|', d.name, '|', d.category, '|', d.placement)"
# upstream checkout: the tier bundle resolves as a relative path
node --input-type=module -e "import * as i from './dist/openalgo-charts.indicators.mjs'; for (const d of i.BUILTIN_INDICATORS) console.log(d.id, '|', d.name, '|', d.inputs.map(x => x.key + '=' + x.default).join(' '))"

At runtime, hasIndicator(id) is the guard and registeredIndicators() the live list. If the user names an indicator that has no built-in descriptor, say so plainly and go to Path C rather than substituting a different indicator.

Path B - restyle an existing instance

Every plot gets colour, opacity, thickness, line style and plot style for free, generated from the descriptor. The keys are <plotKey>:opacity, :width, :lineStyle, :type.

Colour is the exception. The colour key is plot.colorKey when the descriptor declares one, and <plotKey>:color only when it does not. Every built-in declares one, so 'macd:color' is silently ignored while 'macdColor' works. Resolve the real key with plotStyleKeys(plot) rather than composing it by hand.

28 built-ins also declare fills (shaded channels, and background overbought/oversold bands). A fill is restyled through its colorUpKey / colorDownKey settings keys, not through any plot key.

macd.setSettings({ 'macd:width': 2, 'macd:lineStyle': 'dashed', macdColor: '#26a69a' });

To build a settings dialog, generate it from the descriptor rather than hand-writing a form. The descriptor's own inputs are the parameters tab; indicatorStyleInputs(descriptor) gives the style tab. The chart emits indicatorSettings when the user clicks the gear on a pane legend - that event is the hook to open your dialog. The library ships no dialog.

Path C - author a custom indicator

Use registerIndicator when the value is computed from the chart's own OHLCV. A descriptor is data: id, name, placement, inputs, plots, optional levels, and a pure calc. Each plot names a registered chart type, so you write no drawing code.

Since 1.7.1 a descriptor can also return free-standing geometry from draws(ctx) (lines, boxes, labels and polylines anchored to { time, price }, with ray extension and multi-line text), derive its levels from ctx.bars / ctx.values rather than settings alone, and send a single plot to the price pane with overlay: true while the rest of the study keeps its own pane. colorBy now reaches line, area and step, not just histogram and column. The ./calc helpers are all exported, including pivotHigh, pivotLow and smaSeededEma, so a ported study composes them instead of re-deriving them.

Since 1.8.1, and the reason to reach past a plot before hand-rolling something:

• calc takes an optional fourth argument, IndicatorCalcContext: barState (isNew, isConfirmed, isRealtime, lastIndex), plus symbol, interval, timezone and now(). calcTail takes it sixth. Optional and trailing, so an existing descriptor is untouched. isConfirmed is inferred from the last bar's gap against the chart clock, so a holiday or a session break widens it: it means "this bar's span has elapsed", not "the exchange is closed".
• alerts declares conditions the runtime watches, emitted as 'indicator:alert' on the chart bus. They fire only on a live tail change, so adding the indicator to a loaded chart, changing a setting, paging history or switching symbol announces nothing.
• background(ctx) shades the indicator's own pane per bar (pass a translucent rgba(), it draws over the grid); barColors(ctx) recolours the main price candles, one publisher at a time, last writer wins.
• plot.ohlc names four calc columns so one plot draws as candles or OHLC bars.
• withAlpha / fromGradient from the package root, for any per-bar colour rule. Do not write a hex parser.
• intervalParts and isIntradayInterval / isDailyInterval / isSecondsInterval / isTickInterval answer what kind of bar the chart is on. Never branch by matching the interval string.
• parseSessionSpec / inSessionAt / sessionFlags for a window you state ('0915-1015', '0930-1600:23456'), as opposed to sessionStartFlags, which reads the trading day back out of the bar gaps.

Since 2.4.0, for the constructs a ported study most often could not express (every one optional, nothing older changes):

• securitySeries(bars, interval, opts) from openalgo-charts/indicators folds the chart's bars to a higher timeframe, one value per bar. The default reads the bucket as it stood at that bar and never repaints; offset: k reads the last completed bucket; lookahead: true reads final values and repaints. session: '0915-1530' anchors sub-day buckets to the session open. This replaces every hand-rolled fold.
• plot.offset paints a column that many bars to the right, the tail landing in the right margin (a displaced cloud). Fills follow the first plot's offset; the legend reads what is drawn under the cursor. SeriesStyle.barOffset is the same thing on any series.
• A thrown calc no longer takes the frame down: it is published as { state: 'error' } on the instance data status and indicator:data-status, the previous plots stay up, and the next good pass publishes ready. Throw IndicatorInputError for a condition the user can fix. addIndicator still refuses a descriptor whose first pass throws.
• alerts[].message may be a function of the firing bar's context.
• Markers: shapes cross and xcross; positions paneTop and paneBottom, pinned to the plot edge with no bar or price needed.
• fills[].overlay puts a band on the price pane beside overlay plots.
• plot.colorParts returns { body, wick, border } per bar, carried as Bar.wickColor / Bar.borderColor and honoured by both candle renderers; colorBy is unchanged.
• draws() labels and boxes take tooltip and id: hit-testable, reported through subscribeClick, tooltip painted on hover by the layer itself.
• Inputs interval and time: a timeframe code (select over the built-in tokens plus registered codes) and a wall-clock string in the chart zone.
• table options fontSize: 'auto' fits each cell.
• ctx.requestBars(request) on the attach context asks the host for another instrument's bars; the host registers a provider with chart.setBarsProvider (or ChartOptions.barsProvider) and it rejects with a clear message when there is none. See Path D for the Tier-2 half.