ChartHandle

Documentation / @elitechart/core / ChartHandle

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: chart.ts:449

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: chart.ts:562

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: chart.ts:597

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: chart.ts:321

Type Parameters

S

S

Parameters

tool

DrawingTool<S>

state

S

Returns

string

See

removeDrawing / clearDrawings

addOverlay()

code

addOverlay(fn): () => void;

Defined in: chart.ts:306

Parameters

fn

OverlayFn

Returns

() => void

appendBar()

code

appendBar(bar): void;

Defined in: chart.ts:316

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: chart.ts:345

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: chart.ts:413

Whether a redo is currently available.

Returns

boolean

canUndo()

code

canUndo(): boolean;

Defined in: chart.ts:411

Whether an undo is currently available.

Returns

boolean

clearAxisAnnotations()

code

clearAxisAnnotations(): void;

Defined in: chart.ts:453

Remove every axis annotation.

Returns

void

clearCorporateEvents()

code

clearCorporateEvents(): void;

Defined in: chart.ts:608

Remove all corporate events.

Returns

void

clearDrawings()

code

clearDrawings(): void;

Defined in: chart.ts:349

Remove every drawing.

Returns

void

clearHistory()

code

clearHistory(): void;

Defined in: chart.ts:415

Clear the undo/redo history.

Returns

void

clearReplayRange()

code

clearReplayRange(): void;

Defined in: chart.ts:530

Remove any previously-set replay range.

Returns

void

createAlert()

code

createAlert(input): string;

Defined in: chart.ts:421

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: chart.ts:611

Release resources. Idempotent.

Returns

void

duplicateDrawing()

code

duplicateDrawing(id): string | null;

Defined in: chart.ts:343

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: chart.ts:504

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: chart.ts:506

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

Returns

void

exportPng()

code

exportPng(opts?): Promise<Blob>;

Defined in: chart.ts:490

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: chart.ts:296

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: chart.ts:258

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: chart.ts:250

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: chart.ts:581

Current magnet mode.

Returns

MagnetMode

getPerfStats()

code

getPerfStats(): SchedulerStats;

Defined in: chart.ts:476

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: chart.ts:375

Find a registered plugin by id.

Parameters

id

string

Returns

AnyPlugin | undefined

getPointFigureOptions()

code

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

Defined in: chart.ts:267

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: chart.ts:274

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: chart.ts:242

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: chart.ts:516

Current replay state snapshot.

Returns

ReplayState

getResolvedTheme()

code

getResolvedTheme(): ResolvedTheme;

Defined in: chart.ts:283

Current resolved-theme snapshot.

Returns

ResolvedTheme

getSelectedDrawing()

code

getSelectedDrawing(): string | null;

Defined in: chart.ts:387

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

Returns

string | null

getSelectedDrawings()

code

getSelectedDrawings(): readonly string[];

Defined in: chart.ts:393

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: chart.ts:383

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

Returns

string | null

isDrawingLocked()

code

isDrawingLocked(id): boolean | undefined;

Defined in: chart.ts:331

Query lock state. undefined when the id is unknown.

Parameters

id

string

Returns

boolean | undefined

isGridVisible()

code

isGridVisible(): boolean;

Defined in: chart.ts:287

Whether gridlines are currently drawn.

Returns

boolean

isPersistentTool()

code

isPersistentTool(): boolean;

Defined in: chart.ts:590

Current persistent-tool state.

Returns

boolean

isReplaying()

code

isReplaying(): boolean;

Defined in: chart.ts:514

Whether replay mode is active.

Returns

boolean

listAlerts()

code

listAlerts(): readonly Alert[];

Defined in: chart.ts:435

Enumerate all alerts (triggered + pending).

Returns

readonly Alert[]

listAxisAnnotations()

code

listAxisAnnotations(): readonly AxisAnnotation[];

Defined in: chart.ts:455

Enumerate currently-registered axis annotations.

Returns

readonly AxisAnnotation[]

listCompareSeries()

code

listCompareSeries(): readonly CompareSeries[];

Defined in: chart.ts:573

List all compare series currently overlaid.

Returns

readonly CompareSeries[]

listCorporateEvents()

code

listCorporateEvents(): readonly CorporateEvent[];

Defined in: chart.ts:606

List every registered corporate event.

Returns

readonly CorporateEvent[]

listDrawings()

code

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

Defined in: chart.ts:333

Enumerate registered drawings (id + toolId + locked).

Returns

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

listPlugins()

code

listPlugins(): readonly AnyPlugin[];

Defined in: chart.ts:373

List every registered plugin.

Returns

readonly AnyPlugin[]

loadDrawings()

code

loadDrawings(list, registry): void;

Defined in: chart.ts:360

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: chart.ts:554

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: chart.ts:463

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: chart.ts:227

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: chart.ts:400

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

Parameters

deltaMs

number

Returns

void

patchTheme()

code

patchTheme(partial): void;

Defined in: chart.ts:281

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: chart.ts:512

Pause auto-advance.

Returns

void

playReplay()

code

playReplay(speedMs?): void;

Defined in: chart.ts:510

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

Parameters

speedMs?

number

Returns

void

redo()

code

redo(): boolean;

Defined in: chart.ts:409

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

Returns

boolean

registerPlugin()

code

registerPlugin(plugin): RegistrationResult;

Defined in: chart.ts:369

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

Parameters

removeAlert()

code

removeAlert(id): boolean;

Defined in: chart.ts:427

Remove an alert. Returns true when removed.

Parameters

id

string

Returns

boolean

removeAxisAnnotation()

code

removeAxisAnnotation(id): boolean;

Defined in: chart.ts:451

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

Parameters

id

string

Returns

boolean

removeCompareSeries()

code

removeCompareSeries(id): boolean;

Defined in: chart.ts:569

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

Parameters

id

string

Returns

boolean

removeCorporateEvent()

code

removeCorporateEvent(id): boolean;

Defined in: chart.ts:604

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

Parameters

id

string

Returns

boolean

removeDrawing()

code

removeDrawing(id): boolean;

Defined in: chart.ts:323

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

Parameters

id

string

Returns

boolean

resetView()

code

resetView(): void;

Defined in: chart.ts:404

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

Returns

void

selectReplayRange()

code

selectReplayRange(): void;

Defined in: chart.ts:536

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: chart.ts:347

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: chart.ts:351

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: chart.ts:543

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: chart.ts:294

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: chart.ts:329

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: chart.ts:327

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: chart.ts:285

Toggle gridlines. When hidden, tick labels still render.

Parameters

visible

boolean

Returns

void

setKagiOptions()

code

setKagiOptions(opts): void;

Defined in: chart.ts:256

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: chart.ts:234

Change how the current series is visualized.

Parameters

kind

SeriesKind

Returns

void

setLineBreakOptions()

code

setLineBreakOptions(opts): void;

Defined in: chart.ts:248

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: chart.ts:579

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: chart.ts:588

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: chart.ts:265

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: chart.ts:272

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: chart.ts:240

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: chart.ts:524

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: chart.ts:385

Programmatically set the selected drawing. null clears the selection.

Parameters

id

string | null

Returns

void

setSeries()

code

setSeries(series): void;

Defined in: chart.ts:232

Replace the underlying series. Resets the visible window.

Parameters

series

Series

Returns

void

setTheme()

code

setTheme(theme): void;

Defined in: chart.ts:276

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

Parameters

theme

ChartForgeTheme

Returns

void

setToolMode()

code

setToolMode(tool): void;

Defined in: chart.ts:381

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: chart.ts:508

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: chart.ts:311

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: chart.ts:398

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: chart.ts:468

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: chart.ts:407

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

Returns

boolean

unregisterPlugin()

code

unregisterPlugin(id): boolean;

Defined in: chart.ts:371

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

Parameters

id

string

Returns

boolean

updateAlert()

code

updateAlert(id, patch): boolean;

Defined in: chart.ts:433

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: chart.ts:571

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: chart.ts:325

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: chart.ts:402

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

Parameters

factor

number

Returns

void