ChartHandle

Documentation / @elitechart/elitechart / ChartHandle

Defined in: core/dist/index.d.ts:2473

Public chart handle returned by createChart. Drives the entire chart lifecycle — series, theme, drawings, alerts, replay, layout.

Always call chart.destroy() on unmount to release resources.

Example

code

const chart: ChartHandle = createChart(el, { series });
chart.on('crosshair:move', updateLegend);
chart.setKind('heikin-ashi');
chart.appendBar(latestBar);
// on unmount:
chart.destroy();

Methods

addAxisAnnotation()

code

addAxisAnnotation(input): string;

Defined in: core/dist/index.d.ts:2712

Push a coloured pill onto the right price gutter at the given price level. Used by embedders that want to highlight specific prices (selected drawing anchors, target / stop levels, etc.) without writing a custom overlay layer. Returns the pill's id for later removal.

Pills paint on Layer.Cursor next to the live-price pill, so they're cheap to add/remove and always sit on top of the chart.

Parameters

input

Omit<AxisAnnotation, "id"> & { id?: string; }

Returns

string

See

removeAxisAnnotation / clearAxisAnnotations

addCompareSeries()

code

addCompareSeries(input): string;

Defined in: core/dist/index.d.ts:2825

Overlay another symbol's bars on the same chart, scaled so its first visible bar aligns with the primary series' first visible bar (anchor- matched). Useful for relative-performance comparisons. Returns the generated compare-series id.

Parameters

input

bars

readonly Bar[]

color?

string

lineWidth?

number

symbol

SymbolInfo

Returns

string

addCorporateEvent()

code

addCorporateEvent(input): string;

Defined in: core/dist/index.d.ts:2857

Register a corporate event (earnings / dividend / split / news). Renders a small badge on the bottom edge of the plot area at the event's time. Returns the generated id.

Parameters

input

kind

CorporateEventKind

note?

string

time

TimestampMs

value?

number

Returns

string

addDrawing()

code

addDrawing<S>(tool, state): string;

Defined in: core/dist/index.d.ts:2583

Type Parameters

S

S

Parameters

tool

DrawingTool<S>

state

S

Returns

string

See

removeDrawing / clearDrawings

addOverlay()

code

addOverlay(fn): () => void;

Defined in: core/dist/index.d.ts:2568

Parameters

fn

OverlayFn

Returns

() => void

appendBar()

code

appendBar(bar): void;

Defined in: core/dist/index.d.ts:2578

Append a new bar. If the viewport is currently pinned near the right edge (auto-follow), the window shifts to keep the new bar visible.

Parameters

bar

Bar

Returns

void

bringDrawingToFront()

code

bringDrawingToFront(id): boolean;

Defined in: core/dist/index.d.ts:2607

Move a drawing to the front of the z-order (last in the array).

Parameters

id

string

Returns

boolean

canRedo()

code

canRedo(): boolean;

Defined in: core/dist/index.d.ts:2675

Whether a redo is currently available.

Returns

boolean

canUndo()

code

canUndo(): boolean;

Defined in: core/dist/index.d.ts:2673

Whether an undo is currently available.

Returns

boolean

clearAxisAnnotations()

code

clearAxisAnnotations(): void;

Defined in: core/dist/index.d.ts:2718

Remove every axis annotation.

Returns

void

clearCorporateEvents()

code

clearCorporateEvents(): void;

Defined in: core/dist/index.d.ts:2868

Remove all corporate events.

Returns

void

clearDrawings()

code

clearDrawings(): void;

Defined in: core/dist/index.d.ts:2611

Remove every drawing.

Returns

void

clearHistory()

code

clearHistory(): void;

Defined in: core/dist/index.d.ts:2677

Clear the undo/redo history.

Returns

void

clearReplayRange()

code

clearReplayRange(): void;

Defined in: core/dist/index.d.ts:2796

Remove any previously-set replay range.

Returns

void

createAlert()

code

createAlert(input): string;

Defined in: core/dist/index.d.ts:2682

Create a simple price alert at price. Fires once when the most-recent bar's range crosses the threshold. Returns the generated alert id.

Parameters

input

note?

string

price

Price

toolDrawingId?

string

Returns

string

destroy()

code

destroy(): void;

Defined in: core/dist/index.d.ts:2870

Release resources. Idempotent.

Returns

void

duplicateDrawing()

code

duplicateDrawing(id): string | null;

Defined in: core/dist/index.d.ts:2605

Duplicate a drawing, returning the new id. The clone inherits the source's state (structured-cloned) and style overrides. Returns null if id is unknown.

Parameters

id

string

Returns

string | null

enterReplay()

code

enterReplay(input?): void;

Defined in: core/dist/index.d.ts:2766

Enter bar-replay mode. The chart hides bars after atIndex (or atTime) and acts as if those bars never arrived. Live-data suppression is the embedder's responsibility; ticks that arrive while replay is active are still stored in the underlying series but not rendered until replay exits or the cursor advances past them. Defaults to the 75%-of-history mark when neither anchor is given.

Parameters

input?

atIndex?

number

atTime?

TimestampMs

Returns

void

exitReplay()

code

exitReplay(): void;

Defined in: core/dist/index.d.ts:2771

Exit replay mode and render the full series. Stops auto-advance if running.

Returns

void

exportPng()

code

exportPng(opts?): Promise<Blob>;

Defined in: core/dist/index.d.ts:2753

Composite every layer canvas into a single image and return it as a Blob. Resolves when the encode is done; rejects if toBlob returns null (canvas is too big or tainted). The resulting image is the chart's current visible state at device-pixel- accurate resolution, so it prints cleanly at any size.

Pass { mimeType: 'image/jpeg', quality: 0.92 } for JPEG; default is lossless PNG. background fills the image below the Grid layer (defaults to the theme's bgCanvas) so screenshots are never transparent on Retina screens.

Parameters

opts?

background?

string

mimeType?

"image/png" | "image/jpeg" | "image/webp"

quality?

number

Returns

Promise<Blob>

getBottomPaneBounds()

code

getBottomPaneBounds(): {
  bottom: number;
  left: number;
  right: number;
  top: number;
};

Defined in: core/dist/index.d.ts:2558

Pixel bounds of the reserved sub-pane strip (for overlay renderers).

Returns

code

{
  bottom: number;
  left: number;
  right: number;
  top: number;
}

bottom

code

readonly bottom: number;

left

code

readonly left: number;

right

code

readonly right: number;

top

code

readonly top: number;

getKagiOptions()

code

getKagiOptions(): {
  reversalPercent: number;
  reversalPrice?: number;
};

Defined in: core/dist/index.d.ts:2513

Read the current Kagi options (cloned, safe to mutate).

Returns

code

{
  reversalPercent: number;
  reversalPrice?: number;
}

reversalPercent

code

readonly reversalPercent: number;

reversalPrice?

code

readonly optional reversalPrice?: number;

getLineBreakOptions()

code

getLineBreakOptions(): {
  lineCount: number;
};

Defined in: core/dist/index.d.ts:2503

Read the current Line Break options (cloned, safe to mutate).

Returns

code

{
  lineCount: number;
}

lineCount

code

readonly lineCount: number;

getMagnet()

code

getMagnet(): MagnetMode;

Defined in: core/dist/index.d.ts:2843

Current magnet mode.

Returns

MagnetMode

getPerfStats()

code

getPerfStats(): SchedulerStats;

Defined in: core/dist/index.d.ts:2740

Rolling paint-time stats: last / avg / peak ms over the last ~30 frames plus total frame count and the last paint's dirty-layer bitmask. Use for dev perf HUDs, benchmark verification, or automated perf tests.

Returns

SchedulerStats

getPlugin()

code

getPlugin(id): AnyPlugin | undefined;

Defined in: core/dist/index.d.ts:2638

Find a registered plugin by id.

Parameters

id

string

Returns

AnyPlugin | undefined

getPointFigureOptions()

code

getPointFigureOptions(): {
  boxSize: number;
  reversalBoxes: number;
};

Defined in: core/dist/index.d.ts:2525

Read the current P&F options (cloned, safe to mutate).

Returns

code

{
  boxSize: number;
  reversalBoxes: number;
}

boxSize

code

readonly boxSize: number;

reversalBoxes

code

readonly reversalBoxes: number;

getRangeBarsOptions()

code

getRangeBarsOptions(): {
  rangeSize: number;
};

Defined in: core/dist/index.d.ts:2535

Read the current Range Bars options (cloned, safe to mutate).

Returns

code

{
  rangeSize: number;
}

rangeSize

code

readonly rangeSize: number;

getRenkoOptions()

code

getRenkoOptions(): {
  brickSize: number;
  reversal: 1 | 2;
};

Defined in: core/dist/index.d.ts:2490

Read the current Renko options (cloned, safe to mutate).

Returns

code

{
  brickSize: number;
  reversal: 1 | 2;
}

brickSize

code

readonly brickSize: number;

reversal

code

readonly reversal: 1 | 2;

getReplayState()

code

getReplayState(): ReplayState;

Defined in: core/dist/index.d.ts:2781

Current replay state snapshot.

Returns

ReplayState

getResolvedTheme()

code

getResolvedTheme(): ResolvedTheme;

Defined in: core/dist/index.d.ts:2546

Current resolved-theme snapshot.

Returns

ResolvedTheme

getSelectedDrawing()

code

getSelectedDrawing(): string | null;

Defined in: core/dist/index.d.ts:2650

Currently-selected (primary) drawing id, or null.

Returns

string | null

getSelectedDrawings()

code

getSelectedDrawings(): readonly string[];

Defined in: core/dist/index.d.ts:2656

Full multi-selection set (all drawings selected via Shift-click). The primary returned from getSelectedDrawing() is always a member when the set is non-empty.

Returns

readonly string[]

getToolMode()

code

getToolMode(): string | null;

Defined in: core/dist/index.d.ts:2646

Current active tool id, or null when no tool mode is active.

Returns

string | null

isDrawingLocked()

code

isDrawingLocked(id): boolean | undefined;

Defined in: core/dist/index.d.ts:2593

Query lock state. undefined when the id is unknown.

Parameters

id

string

Returns

boolean | undefined

isGridVisible()

code

isGridVisible(): boolean;

Defined in: core/dist/index.d.ts:2550

Whether gridlines are currently drawn.

Returns

boolean

isPersistentTool()

code

isPersistentTool(): boolean;

Defined in: core/dist/index.d.ts:2851

Current persistent-tool state.

Returns

boolean

isReplaying()

code

isReplaying(): boolean;

Defined in: core/dist/index.d.ts:2779

Whether replay mode is active.

Returns

boolean

listAlerts()

code

listAlerts(): readonly Alert[];

Defined in: core/dist/index.d.ts:2699

Enumerate all alerts (triggered + pending).

Returns

readonly Alert[]

listAxisAnnotations()

code

listAxisAnnotations(): readonly AxisAnnotation[];

Defined in: core/dist/index.d.ts:2720

Enumerate currently-registered axis annotations.

Returns

readonly AxisAnnotation[]

listCompareSeries()

code

listCompareSeries(): readonly CompareSeries[];

Defined in: core/dist/index.d.ts:2836

List all compare series currently overlaid.

Returns

readonly CompareSeries[]

listCorporateEvents()

code

listCorporateEvents(): readonly CorporateEvent[];

Defined in: core/dist/index.d.ts:2866

List every registered corporate event.

Returns

readonly CorporateEvent[]

listDrawings()

code

listDrawings(): readonly {
  id: string;
  locked: boolean;
  toolId: string;
}[];

Defined in: core/dist/index.d.ts:2595

Enumerate registered drawings (id + toolId + locked).

Returns

readonly { id: string; locked: boolean; toolId: string; }[]

listPlugins()

code

listPlugins(): readonly AnyPlugin[];

Defined in: core/dist/index.d.ts:2636

List every registered plugin.

Returns

readonly AnyPlugin[]

loadDrawings()

code

loadDrawings(list, registry): void;

Defined in: core/dist/index.d.ts:2622

Load drawings from a previously serialized list. Tools referenced by toolId must already be available in the supplied registry.

Parameters

list

readonly { id: string; state: unknown; toolId: string; }[]

registry

ReadonlyMap<string, DrawingTool<unknown>>

Returns

void

loadLayout()

code

loadLayout(layout, drawingRegistry): void;

Defined in: core/dist/index.d.ts:2818

Restore a previously-serialized layout.

drawingRegistry maps tool-id → DrawingTool for each drawing that might appear in the layout. Drawings referencing unknown tools are skipped (with an error callback).

Clears history, alerts, and current drawings before applying.

Parameters

layout

ChartLayout

drawingRegistry

ReadonlyMap<string, DrawingTool<unknown>>

Returns

void

manageAlerts()

code

manageAlerts(): void;

Defined in: core/dist/index.d.ts:2728

Open the built-in alerts management dialog. No-op (just refreshes) when already open. Closes via Esc or the × button. Rebuilds rows automatically on any alert event so edits made through other paths (context-menu create, axis-plus "+" create, triggers) stay reflected in the list.

Returns

void

on()

code

on<K>(event, listener): () => void;

Defined in: core/dist/index.d.ts:2475

Subscribe to chart events. Returns an unsubscribe function.

Type Parameters

K

K extends keyof ChartEventMap

Parameters

event

K

listener

(payload) => void

Returns

() => void

panTimeBy()

code

panTimeBy(deltaMs): void;

Defined in: core/dist/index.d.ts:2663

Pan the time axis by deltaMs (positive = shift forward in time).

Parameters

deltaMs

number

Returns

void

patchTheme()

code

patchTheme(partial): void;

Defined in: core/dist/index.d.ts:2544

Patch specific theme tokens without a full theme swap. Useful for Settings panels that tweak one or two colors (e.g. bullish candle).

Parameters

partial

Partial<ResolvedTheme>

Returns

void

pauseReplay()

code

pauseReplay(): void;

Defined in: core/dist/index.d.ts:2777

Pause auto-advance.

Returns

void

playReplay()

code

playReplay(speedMs?): void;

Defined in: core/dist/index.d.ts:2775

Start auto-advancing the cursor. Calls stepReplay(1) every speedMs ms.

Parameters

speedMs?

number

Returns

void

redo()

code

redo(): boolean;

Defined in: core/dist/index.d.ts:2671

Redo the last undone command. Returns true when something was redone.

Returns

boolean

registerPlugin()

code

registerPlugin(plugin): RegistrationResult;

Defined in: core/dist/index.d.ts:2632

Register a plugin (indicator / overlay / drawing tool). Rejects plugins targeting an unsupported interfaceVersion or a duplicate id.

Parameters

plugin

AnyPlugin

Returns

RegistrationResult

See

unregisterPlugin / listPlugins

removeAlert()

code

removeAlert(id): boolean;

Defined in: core/dist/index.d.ts:2688

Remove an alert. Returns true when removed.

Parameters

id

string

Returns

boolean

removeAxisAnnotation()

code

removeAxisAnnotation(id): boolean;

Defined in: core/dist/index.d.ts:2716

Remove an axis annotation by id. Returns true when removed.

Parameters

id

string

Returns

boolean

removeCompareSeries()

code

removeCompareSeries(id): boolean;

Defined in: core/dist/index.d.ts:2832

Remove a compare series by id. Returns true when removed.

Parameters

id

string

Returns

boolean

removeCorporateEvent()

code

removeCorporateEvent(id): boolean;

Defined in: core/dist/index.d.ts:2864

Remove a corporate event by id. Returns true on success.

Parameters

id

string

Returns

boolean

removeDrawing()

code

removeDrawing(id): boolean;

Defined in: core/dist/index.d.ts:2585

Remove a drawing by id. Returns true if a drawing was removed.

Parameters

id

string

Returns

boolean

resetView()

code

resetView(): void;

Defined in: core/dist/index.d.ts:2667

Restore the visible window to the default (most recent N bars).

Returns

void

selectReplayRange()

code

selectReplayRange(): void;

Defined in: core/dist/index.d.ts:2802

Arm drag-to-select replay range mode. The next pointer drag on the chart body defines [fromTime, toTime]; on release the range is committed via setReplayRange and the mode auto-exits.

Returns

void

sendDrawingToBack()

code

sendDrawingToBack(id): boolean;

Defined in: core/dist/index.d.ts:2609

Move a drawing to the back of the z-order (first in the array).

Parameters

id

string

Returns

boolean

serializeDrawings()

code

serializeDrawings(): readonly {
  id: string;
  state: unknown;
  toolId: string;
}[];

Defined in: core/dist/index.d.ts:2613

JSON-safe projection of every drawing's state, keyed by drawing id.

Returns

readonly { id: string; state: unknown; toolId: string; }[]

serializeLayout()

code

serializeLayout(meta?): ChartLayout;

Defined in: core/dist/index.d.ts:2808

Produce a JSON-safe snapshot of the chart's layout (kind, theme name, symbol metadata, viewport, drawings, alerts). Bars are NOT included — the embedder re-fetches them from their datafeed on restore.

Parameters

meta?

Readonly<Record<string, unknown>>

Returns

ChartLayout

setBottomPaneReserve()

code

setBottomPaneReserve(px): void;

Defined in: core/dist/index.d.ts:2556

Reserve px of vertical space between the price plot and the time axis for oscillator sub-panes. Pass 0 to remove the reserve and restore the full-height price plot. Triggers a re-layout.

Parameters

px

number

Returns

void

setDrawingLocked()

code

setDrawingLocked(id, locked): boolean;

Defined in: core/dist/index.d.ts:2591

Lock or unlock a drawing. Locked drawings refuse drag but remain selectable.

Parameters

id

string

locked

boolean

Returns

boolean

setDrawingStyle()

code

setDrawingStyle(id, overrides): boolean;

Defined in: core/dist/index.d.ts:2589

Set or merge per-drawing style overrides (color, line width, etc).

Parameters

id

string

overrides

Partial<DrawingStyle>

Returns

boolean

setGridVisible()

code

setGridVisible(visible): void;

Defined in: core/dist/index.d.ts:2548

Toggle gridlines. When hidden, tick labels still render.

Parameters

visible

boolean

Returns

void

setKagiOptions()

code

setKagiOptions(opts): void;

Defined in: core/dist/index.d.ts:2511

Configure the Kagi builder. Takes effect on the next paint when kind === 'kagi'. Default: { reversalPercent: 4 } (industry-canonical). Pass reversalPrice instead for a fixed-units threshold.

Parameters

opts

KagiOptions

Returns

void

setKind()

code

setKind(kind): void;

Defined in: core/dist/index.d.ts:2479

Change how the current series is visualized.

Parameters

kind

SeriesKind

Returns

void

setLineBreakOptions()

code

setLineBreakOptions(opts): void;

Defined in: core/dist/index.d.ts:2499

Configure the Line Break builder. Takes effect on the next paint when kind === 'line-break'. Default: { lineCount: 3 } (canonical Three Line Break).

Parameters

opts

lineCount

number

Returns

void

setMagnet()

code

setMagnet(mode): void;

Defined in: core/dist/index.d.ts:2841

Change magnet mode at runtime. Emits 'magnet:change'. Affects subsequent crosshair:move events and tool anchor placement.

Parameters

mode

MagnetMode

Returns

void

setPersistentTool()

code

setPersistentTool(on): void;

Defined in: core/dist/index.d.ts:2849

Toggle "stay in drawing mode" — after a placement the tool remains active (as if the user re-clicked the palette). Mirrors the canonical "pin" affordance. Defaults to the persistentTool chart option value.

Parameters

on

boolean

Returns

void

setPointFigureOptions()

code

setPointFigureOptions(opts): void;

Defined in: core/dist/index.d.ts:2523

Configure the Point & Figure builder. Takes effect on the next paint when kind === 'point-figure'. Default: { boxSize: 1, reversalBoxes: 3 } (Cohen, How to Use the Three-Point Reversal Method of Point and Figure Stock Market Trading).

Parameters

opts

PointFigureOptions

Returns

void

setRangeBarsOptions()

code

setRangeBarsOptions(opts): void;

Defined in: core/dist/index.d.ts:2533

Configure the Range Bars builder. Takes effect on the next paint when kind === 'range-bars'. Default: { rangeSize: 1 }.

Parameters

opts

RangeBarsOptions

Returns

void

setRenkoOptions()

code

setRenkoOptions(opts): void;

Defined in: core/dist/index.d.ts:2485

Configure the Renko brick builder. Takes effect on the next paint when kind === 'renko'. Default: { brickSize: 1, reversal: 2 } (industry-canonical).

Parameters

opts

brickSize

number

reversal?

1 | 2

Returns

void

setReplayRange()

code

setReplayRange(input): void;

Defined in: core/dist/index.d.ts:2788

Pin the replay to a specific bar range. Future stepReplay / playReplay calls will be clamped to [fromIndex, toIndex]. Pass either explicit bar indices or timestamps (binary-searched). Call clearReplayRange to remove the pin.

Parameters

input

| { fromIndex: number; toIndex: number; } | { fromTime: TimestampMs; toTime: TimestampMs; }

Returns

void

setSelectedDrawing()

code

setSelectedDrawing(id): void;

Defined in: core/dist/index.d.ts:2648

Programmatically set the selected drawing. null clears the selection.

Parameters

id

string | null

Returns

void

setSeries()

code

setSeries(series): void;

Defined in: core/dist/index.d.ts:2477

Replace the underlying series. Resets the visible window.

Parameters

series

Series

Returns

void

setTheme()

code

setTheme(theme): void;

Defined in: core/dist/index.d.ts:2539

Apply a new theme. Takes effect on the next frame.

Parameters

theme

ChartForgeTheme

Returns

void

setToolMode()

code

setToolMode(tool): void;

Defined in: core/dist/index.d.ts:2644

Enter a tool-mode for interactive drawing. Each subsequent plot-area click contributes an anchor; once tool.anchorCount anchors are collected the drawing is added automatically. Pass null to exit tool mode.

Parameters

tool

| DrawingTool<unknown> | null

Returns

void

stepReplay()

code

stepReplay(n?): void;

Defined in: core/dist/index.d.ts:2773

Advance the replay cursor by n bars. Negative rewinds. Clamps to [0, lastIndex].

Parameters

n?

number

Returns

void

tickLastBar()

code

tickLastBar(bar): void;

Defined in: core/dist/index.d.ts:2573

Replace the last bar in-place — viewport is preserved. Use for live tick updates ("last trade just moved the close").

Parameters

bar

Bar

Returns

void

toggleSelectedDrawing()

code

toggleSelectedDrawing(id): void;

Defined in: core/dist/index.d.ts:2661

Toggle a drawing's multi-selection state. Used by consumers that want programmatic equivalents of Shift-click.

Parameters

id

string

Returns

void

toggleShortcutHelp()

code

toggleShortcutHelp(): void;

Defined in: core/dist/index.d.ts:2733

Show or hide the built-in keyboard-shortcut help overlay. Calling when open closes it. Equivalent to the user pressing ?.

Returns

void

undo()

code

undo(): boolean;

Defined in: core/dist/index.d.ts:2669

Undo the last reversible command. Returns true when something was undone.

Returns

boolean

unregisterPlugin()

code

unregisterPlugin(id): boolean;

Defined in: core/dist/index.d.ts:2634

Unregister by id. Returns true if a plugin was removed.

Parameters

id

string

Returns

boolean

updateAlert()

code

updateAlert(id, patch): boolean;

Defined in: core/dist/index.d.ts:2694

Edit an alert's price and/or note in place. Returns true when the alert existed. Resets triggered to false when the price changes so the alert can re-fire at the new level.

Parameters

id

string

patch

note?

string

price?

Price

Returns

boolean

updateCompareSeriesBars()

code

updateCompareSeriesBars(id, bars): boolean;

Defined in: core/dist/index.d.ts:2834

Replace the bars of an existing compare series (e.g. a tick stream update).

Parameters

id

string

bars

readonly Bar[]

Returns

boolean

updateDrawing()

code

updateDrawing<S>(id, state): boolean;

Defined in: core/dist/index.d.ts:2587

Replace a drawing's state by id. Returns true if a drawing was updated.

Type Parameters

S

S

Parameters

id

string

state

S

Returns

boolean

zoomTime()

code

zoomTime(factor): void;

Defined in: core/dist/index.d.ts:2665

Zoom the time axis by factor, anchored to the chart center. 0 < factor < 1 → zoom-in.

Parameters

factor

number

Returns

void