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).
| Parameter | Description |
|---|---|
stretch | height 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
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
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.