Documentation menu

Class

FerroChart

A chart on a <canvas>.

Static methods

FerroChart.create

static create(canvas: HTMLCanvasElement, options?: ChartCreateOptions): Promise<FerroChart>;

Creates a chart drawing into canvas, which is sized by CSS (the backing store follows its CSS size × devicePixelRatio).

Properties

barSpacing

readonly barSpacing: number;

Bar spacing in CSS px.

crosshairMode

readonly crosshairMode: 'normal' | 'magnet' | 'hidden';

The crosshair mode.

drawings

readonly drawings: Drawings;

The drawings of this chart.

mainPane

readonly mainPane: number;

Id of the top pane.

renderer

readonly renderer: 'webgpu' | 'webgl2';

The GPU API in use: 'webgpu' or 'webgl2'.

rightOffset

readonly rightOffset: number;

Empty space right of the last bar, in bars.

Methods

addBand

addBand(upper: Series, lower: Series, options?: BandOptions): number;

Fills the area between two single-value series of the same pane: fill where upper is at or above lower, fillCrossed where it is below (default: the upper series' color at 15% opacity). Returns the band id; the band is removed with either series.

addCandlestickSeries

addCandlestickSeries(options?: SeriesOptions, pane?: number): Series;

Adds a candlestick series (same as addSeries('candlestick', …)).

addFootprint

addFootprint(options: FootprintOptions, pane?: number): Series;

Adds a footprint: per candle, the sell and buy volume at each price level, fed with appendTrades. Shaded cells from 12 px per bar, numbers from 60 px: create the chart with a maxBarSpacing above 60 to zoom in that far.

addHeatmap

addHeatmap(options: HeatmapOptions, pane?: number): Series;

Adds a heatmap of order book depth (appendDepth) or traded volume (appendTrades) per time column and price level, placed by time between the candles.

addIndicator

addIndicator(source: Series, name: string, params?: Record<string, number | string>, placement?: Placement): Indicator;

Attaches indicator name (e.g. 'sma', 'macd'; the list and the parameters are at /docs/indicators) computed from source. Parameters are in camelCase ({ n: 50, source: 'hl2' }, { fast: 12, slow: 26, signal: 9 }); missing ones take the defaults. A key the indicator does not use throws, naming the accepted keys.

addLayer

addLayer(plugin: LayerPluginJs): number;

Adds a layer plugin: plugin.build(ctx) returns the commands to draw in every frame, in CSS px. plugin.pane (default: none, the whole chart) and plugin.position ('background', 'belowSeries', 'aboveSeries' (default) or 'overlay') are read once. Returns the layer id. Call invalidateLayer when the plugin's own content changes.

addPane

addPane(stretch?: number | null): number;

Adds a pane below the others; returns its id. Throws for a stretch that is not a positive finite number (as setPaneStretch).

ParameterDescription
stretchheight relative to the other panes (default 1)

addSeries

addSeries(kind: SeriesKind, options?: SeriesOptions, pane?: number): Series;

Adds a series of kind to pane (default: the main pane).

addTpo

addTpo(options: TpoOptions, pane?: number): Series;

Adds a TPO (market profile) series, one slot per session, fed with candles through appendBars. Letters need wide slots: create the chart with a large maxBarSpacing; otherwise histograms are drawn.

addTransformSeries

addTransformSeries(name: TransformName, params: TransformParams, options?: SeriesOptions, pane?: number): Series;

Adds a series transform: name is 'renko', 'rangeBars', 'kagi' or 'pointFigure', with the parameters described at /docs/series ({ boxSize: 0.5 }, { atr: 14, kind: 'ohlc' }, { range: 1 }, { reversalPercent: 2 }, { boxSize: 1, reversal: 3 }). The series takes OHLC bars (setData, update; a tick is a bar with four equal prices) and draws what the transform makes of them. A chart has at most one transform series and no other series but volume.

addVolumeSeries

addVolumeSeries(source: Series, pane?: number | null): Series;

Adds a volume histogram of the volume column of source, on pane (default: the main pane, in its bottom quarter).

applyDrawingSync

applyDrawingSync(op: DrawingSyncOp): void;

Applies a drawing operation of another chart (not undoable, not sent again); received drawings go to the main pane.

applyPriceScaleOptions

applyPriceScaleOptions(options: PriceScaleOptions, pane?: number | null): void;

Changes the price scale of pane (default: the main pane). Absent keys keep their value. All or nothing: if a value is invalid, the call throws and the scale is left as it was. Setting range turns auto-scaling off, so range with autoScale: true throws.

applySync

applySync(message: SyncMessage): void;

Applies a message another chart posted (its 'sync' event), e.g. one forwarded from a worker. It is not posted again.

attachSidePlot

attachSidePlot(plot: FerroPlot, pane?: number | null): void;

Lines plot up with a pane (default: the main one): every frame of the chart sets the plot's right axis to the prices at the plot area's top and bottom, as the pane maps them, so a price is at the same height in both (the canvases' page positions are read each frame). The chart is the only source: the right axis is locked, and set to a log axis when the pane's scale is logarithmic. Typical use: a volume profile or order book depth as horizontal bars beside the candles. The plot's attribution logo is removed (the chart's stands for both).

bandOptions

bandOptions(id: number): BandOptions | null;

The colors of a band (null colors are the defaults); null for an unknown id.

coordinateToLogical

coordinateToLogical(x: number): number;

Logical index (fractional) at x (CSS px from the canvas' left edge).

dataRange

dataRange(): LogicalRange | null;

Logical indices of the first and last bar, null without data. Logical indices do not change when older data is prepended (the first one becomes negative).

destroy

destroy(): void;

Removes all listeners and releases the GPU resources. The object can no longer be used.

detachSidePlot

detachSidePlot(plot: FerroPlot): void;

Stops lining plot up with this chart (its right axis stays locked).

drawingSyncState

drawingSyncState(): DrawingSyncOp[];

The synced drawings of this chart as 'add' operations, for loadDrawingSyncState on a chart that joins from a worker.

finishIntro

finishIntro(): void;

Ends the intro animation now, showing everything.

fitContent

fitContent(): void;

Shows all data.

indexOfTime

indexOfTime(time: number | bigint | Date): number | null;

Logical index of the bar at time time (UTC ms or a Date), null if no bar has it.

invalidateLayer

invalidateLayer(id: number): void;

Redraws a layer plugin after its own content changed.

joinSync

joinSync(group: SyncGroup, options?: SyncOptions): void;

Joins group (leaving the current one): crosshair and visible range follow the other charts of the group, by time.

leaveSync

leaveSync(): void;

Leaves the sync group.

loadDrawingSyncState

loadDrawingSyncState(state: DrawingSyncOp[]): void;

Makes the synced drawings match state (from drawingSyncState). Throws, leaving the chart unchanged, for an invalid state.

loadState

loadState(state: ChartState): void;

Loads a state from saveState into a chart set up with the same panes. The drawings replace the current ones; the undo history is cleared. Throws, leaving the chart unchanged, if the state does not fit.

logicalToCoordinate

logicalToCoordinate(index: number): number;

x (CSS px from the canvas' left edge) of the center of logical index index.

paneStretch

paneStretch(pane: number): number | undefined;

Height of a pane relative to the others.

panes

panes(): number[];

Pane ids, top to bottom.

playIntro

playIntro(options?: IntroOptions): Promise<void>;

Intro animation: the chart is shown empty at once (grid and axes), then after delay ms its data is drawn from left to right over duration ms. Price lines, value labels and the crosshair appear at the end. A press, wheel, pinch or key ends it early. The promise resolves when it ends (also through finishIntro).

priceScale

priceScale(pane?: number | null): Required<PriceScaleOptions>;

The price scale of pane (default: the main pane).

removeBand

removeBand(id: number): void;

Removes a band.

removeLayer

removeLayer(id: number): void;

Removes a layer plugin.

removePane

removePane(pane: number): void;

Removes a pane with its series and drawings (not the last one).

saveState

saveState(): ChartState;

Saves the view, layout and drawings as plain JSON-compatible data. Data, series and indicators are not included.

scrollToRealtime

scrollToRealtime(): void;

Scrolls to the latest bar.

setAttributionLogo(on: boolean): void;

Shows or removes the attribution logo (see attributionLogo).

setBandOptions

setBandOptions(id: number, options: BandOptions): void;

Changes some colors of a band; keys left out keep their value.

setBarSpacing

setBarSpacing(cssPx: number): void;

Sets the bar spacing in CSS pixels.

setCrosshairMode

setCrosshairMode(mode: 'normal' | 'magnet' | 'hidden'): void;

Crosshair mode: 'normal', 'magnet' (snaps to the nearest of the bar's open, high, low and close) or 'hidden'.

setPaneStretch

setPaneStretch(pane: number, stretch: number): void;

Sets the height of a pane relative to the others.

setRightOffset

setRightOffset(bars: number): void;

Sets the empty space right of the last bar, in bars (may be negative).

setVisibleLogicalRange

setVisibleLogicalRange(from: number, to: number): void;

Shows logical indices from..to across the plot (as far as the spacing limits allow); also before the first frame.

syncOptions

syncOptions(): Required<SyncOptions> | null;

What the chart shares with its group, null outside a group.

takeDrawingSyncOps

takeDrawingSyncOps(): DrawingSyncOp[];

Takes the drawing sync operations this chart sent and the page has not taken yet (oldest first, at most 1024), e.g. to forward them to a chart in a worker with applyDrawingSync.

timeAtIndex

timeAtIndex(index: number): number | null;

Time (UTC ms) of the bar at logical index index, null outside the data.

visibleLogicalRange

visibleLogicalRange(): LogicalRange;

The visible logical range (plot edges, fractional).

on

on<K extends keyof ChartEventMap>(event: K, callback: (event: ChartEventMap[K]) => void): void;

Subscribes to an event of ChartEventMap (crosshair, visible range, history requests, drawings, sync messages, warnings). Events are delivered after the frame that produced them. An exception thrown by the callback is reported (reportError, shown in the console) and does not stop the other callbacks.

off

off<K extends keyof ChartEventMap>(event: K, callback: (event: ChartEventMap[K]) => void): void;

Removes a callback added with on.

Like every object of the API, a FerroChart holds WebAssembly memory. Objects returned by the chart are freed with it; free() (or using) releases one earlier.