Class: Chart

A chart bound to a DOM element. Create with createChart (or newPlot). All update methods return a promise that resolves with the chart once the result is fully drawn.

Interaction (hover, click, zoom / pan, selection; plan E6) is attached unless config.staticPlot; see fx/interaction.ts for the dispatch order and ComponentView's handlePointer for how components take pointer events first.

Properties

Property	Modifier	Type	Description
`element`	`readonly`	`HTMLElement`	The element the chart renders into (it owns one canvas inside it).
`ready`	`readonly`	`Promise`<`Chart`>	Resolves once the first figure is fully drawn — including async text (tick labels, titles, legend) and any follow-up pass components asked for — so it is safe to screenshot or export (see "Update promises" above). Rejects on a strict-mode validation error.

Accessors

axes

Get Signature

get axes(): ReadonlyMap<string, AxisInfo>;

Experimental

The solved layout: axes and subplots (read-only snapshots of runtime state).

Returns

ReadonlyMap<string, AxisInfo>

config

Get Signature

get config(): unknown;

Returns

unknown

data

Get Signature

get data(): readonly Readonly<Record<string, unknown>>[];

The figure's traces as given (after updates). Treat as read-only.

Returns

readonly Readonly<Record<string, unknown>>[]

datasets

Get Signature

get datasets():
  | Readonly<Record<string, Readonly<Record<string, unknown>>>>
  | undefined;

Named datasets as given (after updates). Treat as read-only.

Returns

| Readonly<Record<string, Readonly<Record<string, unknown>>>> | undefined

description

Get Signature

get description(): ChartDescription | undefined;

What assistive technology is told about the chart (as of the last pipeline run): the accessible name, chart type summary, axes, trace summaries and data tables the hidden DOM mirror shows. undefined before the first draw.

Returns

ChartDescription | undefined

destroyed

Get Signature

get destroyed(): boolean;

Returns

boolean

frames

Get Signature

get frames(): unknown;

Animation frames as given (after updates). Treat as read-only.

Returns

unknown

fullConfig

Get Signature

get fullConfig():
  | FullObject<{
  a11y: ObjectNode<{
     dataTable: Attr<false | "visible" | "hidden", {
        description: "The traces' data tables: `'hidden'` for screen readers only (first 100 rows), `'visible'` shown below the chart with every row (virtualized), `false` none. Holochart only (plan E17.3).";
        dflt: "hidden";
        values: readonly ["hidden", "visible", false];
     }>;
     keyboard: Attr<boolean, {
        description: "Keyboard access: Tab reaches the plot area (the arrows step through the data, `+` / `-` zoom) and the legend items. Holochart only (plan E6.5, E17.4).";
        dflt: true;
     }>;
     patterns: Attr<boolean, {
        description: "Give bars, histograms, polar bars, filled areas (`fillpattern`) and pie slices a distinct pattern each, as an encoding redundant with color, unless the trace or template sets one. Holochart only (plan E17.5).";
        dflt: false;
     }>;
     reducedMotion: Attr<boolean | "auto", {
        description: "Snap transitions and drill-down tweens instead of animating them: `'auto'` when the user's system asks for reduced motion (the `prefers-reduced-motion` media query), `true` always, `false` never. Holochart only (plan E17.5).";
        dflt: "auto";
        values: readonly ["auto", true, false];
     }>;
     summaries: Attr<boolean, {
        description: "Add generated summaries of trends and extremes (\"Revenue rises from 1.2M in Jan to 3.4M in Dec\") to what screen readers get. Their code loads after the first draw. Holochart only (plan E17.2).";
        dflt: true;
     }>;
  }>;
  antialias: Attr<boolean, {
     description: "Request an antialiased WebGL context (fixed at context creation).";
     dflt: true;
  }>;
  ariaLabel: Attr<string, {
     description: "The chart's accessible name (`aria-label`), read by screen readers. Empty: `layout.meta.description` when set, else the figure title followed by an automatic summary (\"Line chart with 3 traces\"). Holochart only (plan E17.1).";
     dflt: "";
  }>;
  debug: Attr<boolean, {
     description: "Log update plans and pipeline timings to the console.";
     dflt: false;
  }>;
  displaylogo: Attr<boolean, {
     description: "Accepted for Plotly compatibility and ignored: the modebar has no logo.";
     dflt: true;
  }>;
  displayModeBar: Attr<boolean | "hover", {
     description: "Show the modebar always (`true`), never (`false`) or on hover.";
     dflt: "hover";
     values: readonly ["hover", true, false];
  }>;
  doubleClick: Attr<false | "autosize" | "reset" | "reset+autosize", {
     description: "What double-clicking the plot area does.";
     dflt: "reset+autosize";
     values: readonly [false, "reset", "autosize", "reset+autosize"];
  }>;
  doubleClickDelay: Attr<number, {
     description: "Maximum delay between two clicks of a double-click, in milliseconds.";
     dflt: 300;
     min: 0;
  }>;
  editable: Attr<boolean, {
     description: "Make titles, legend, annotations and shapes editable in place (E6.7).";
     dflt: false;
  }>;
  edits: ObjectNode<{
     annotationPosition: Attr<boolean, {
        description: "Drag annotations.";
        dflt: false;
     }>;
     annotationTail: Attr<boolean, {
        description: "Drag annotation arrow tails.";
        dflt: false;
     }>;
     annotationText: Attr<boolean, {
        description: "Edit annotation text.";
        dflt: false;
     }>;
     axisTitleText: Attr<boolean, {
        description: "Edit axis titles.";
        dflt: false;
     }>;
     colorbarPosition: Attr<boolean, {
        description: "Drag colorbars.";
        dflt: false;
     }>;
     colorbarTitleText: Attr<boolean, {
        description: "Edit colorbar titles.";
        dflt: false;
     }>;
     legendPosition: Attr<boolean, {
        description: "Drag the legend.";
        dflt: false;
     }>;
     legendText: Attr<boolean, {
        description: "Edit trace names in the legend.";
        dflt: false;
     }>;
     shapePosition: Attr<boolean, {
        description: "Drag and resize shapes.";
        dflt: false;
     }>;
     titleText: Attr<boolean, {
        description: "Edit the figure title.";
        dflt: false;
     }>;
  }>;
  hoverRenderer: Attr<"dom", {
     description: "How hover labels render. Only `dom` (positioned HTML over the canvas) exists in M1; a WebGL label renderer is planned (E5.7).";
     dflt: "dom";
     values: readonly ["dom"];
  }>;
  locale: Attr<string, {
     description: "Locale of UI strings and number and date formats, e.g. `'de'` or `'de-CH'` (which falls back to `de`, then English). Locales come from `locales` or `register()` (`@mk7s/holochart-locales` ships plotly.js's).";
     dflt: "en-US";
     noBlank: true;
  }>;
  locales: AttrSpec<unknown, unknown>;
  maxPixelRatio: Attr<number, {
     description: "Upper limit of the pixel ratio that `pixelRatio: \"auto\"` takes from the display. Raise it for sharper output on 3× screens, at the cost of drawing more pixels.";
     dflt: 2;
     max: 8;
     min: 0.25;
  }>;
  modeBarButtonsToAdd: AttrSpec<unknown, unknown>;
  modeBarButtonsToRemove: AttrSpec<string[], string[]>;
  pixelRatio: Attr<number | "auto", {
     description: "Renderer pixel ratio. `auto` uses `window.devicePixelRatio`, up to `maxPixelRatio`.";
     dflt: "auto";
     extras: readonly ["auto"];
     max: 8;
     min: 0.25;
  }>;
  powerPreference: Attr<"default" | "high-performance" | "low-power", {
     description: "WebGL context power preference hint.";
     dflt: "default";
     values: readonly ["default", "high-performance", "low-power"];
  }>;
  renderHover: AttrSpec<AnyFunction,
     | AnyFunction
    | undefined>;
  responsive: Attr<boolean, {
     description: "Resize the chart when its container or the window resizes.";
     dflt: false;
  }>;
  scrollZoom: Attr<
     | boolean
     | "map"
     | "cartesian"
     | "scene"
     | "geo"
     | `map+${string}`
     | `cartesian+${string}`
     | `scene+${string}`
     | `geo+${string}`, {
     description: "Which subplot kinds zoom on mouse wheel. `true`/`false` enable/disable all of them.";
     dflt: "scene+geo+map";
     extras: readonly [true, false];
     flags: readonly ["cartesian", "scene", "geo", "map"];
  }>;
  sharedRenderer: Attr<boolean | "auto", {
     description: "Draw through one WebGL context shared by every chart on the page instead of a context per chart (browsers keep about 16, fewer on mobile). `auto` gives the first 4 charts a context of their own and shares for the rest. `false` always takes a context.";
     dflt: "auto";
     values: readonly ["auto", true, false];
  }>;
  staticPlot: Attr<boolean, {
     description: "Render once with no interactivity (no hover, zoom or modebar).";
     dflt: false;
  }>;
  strict: Attr<boolean, {
     description: "Throw on the first validation error instead of warning (once per attribute path).";
     dflt: false;
  }>;
  textRenderer: Attr<"dom" | "webgl", {
     description: "Render text as WebGL SDF glyphs or as a DOM overlay (ADR-005).";
     dflt: "webgl";
     values: readonly ["webgl", "dom"];
  }>;
  toImageButtonOptions: ObjectNode<{
     filename: Attr<string, {
        description: "File name.";
        dflt: "newplot";
        noBlank: true;
     }>;
     format: Attr<"png" | "jpeg" | "webp", {
        description: "Image format.";
        dflt: "png";
        values: readonly ["png", "jpeg", "webp"];
     }>;
     height: Attr<number, {
        description: "Height in CSS pixels (defaults to the chart).";
        min: 1;
     }>;
     scale: Attr<number, {
        description: "Resolution multiplier.";
        dflt: 1;
        min: 0;
     }>;
     width: Attr<number, {
        description: "Width in CSS pixels (defaults to the chart).";
        min: 1;
     }>;
  }>;
  topojsonURL: Attr<string, {
     description: string;
     dflt: "";
  }>;
  worker: Attr<boolean | "auto", {
     description: "Run the calc stage in a Web Worker (ADR-011). `auto` switches on above a data-size threshold.";
     dflt: false;
     values: readonly [true, false, "auto"];
  }>;
}>
  | undefined;

Returns

| FullObject<{ a11y: ObjectNode<{ dataTable: Attr<false | "visible" | "hidden", { description: "The traces' data tables: `'hidden'` for screen readers only (first 100 rows), `'visible'` shown below the chart with every row (virtualized), `false` none. Holochart only (plan E17.3)."; dflt: "hidden"; values: readonly ["hidden", "visible", false]; }>; keyboard: Attr<boolean, { description: "Keyboard access: Tab reaches the plot area (the arrows step through the data, `+` / `-` zoom) and the legend items. Holochart only (plan E6.5, E17.4)."; dflt: true; }>; patterns: Attr<boolean, { description: "Give bars, histograms, polar bars, filled areas (`fillpattern`) and pie slices a distinct pattern each, as an encoding redundant with color, unless the trace or template sets one. Holochart only (plan E17.5)."; dflt: false; }>; reducedMotion: Attr<boolean | "auto", { description: "Snap transitions and drill-down tweens instead of animating them: `'auto'` when the user's system asks for reduced motion (the `prefers-reduced-motion` media query), `true` always, `false` never. Holochart only (plan E17.5)."; dflt: "auto"; values: readonly ["auto", true, false]; }>; summaries: Attr<boolean, { description: "Add generated summaries of trends and extremes ("Revenue rises from 1.2M in Jan to 3.4M in Dec") to what screen readers get. Their code loads after the first draw. Holochart only (plan E17.2)."; dflt: true; }>; }>; antialias: Attr<boolean, { description: "Request an antialiased WebGL context (fixed at context creation)."; dflt: true; }>; ariaLabel: Attr<string, { description: "The chart's accessible name (`aria-label`), read by screen readers. Empty: `layout.meta.description` when set, else the figure title followed by an automatic summary ("Line chart with 3 traces"). Holochart only (plan E17.1)."; dflt: ""; }>; debug: Attr<boolean, { description: "Log update plans and pipeline timings to the console."; dflt: false; }>; displaylogo: Attr<boolean, { description: "Accepted for Plotly compatibility and ignored: the modebar has no logo."; dflt: true; }>; displayModeBar: Attr<boolean | "hover", { description: "Show the modebar always (`true`), never (`false`) or on hover."; dflt: "hover"; values: readonly ["hover", true, false]; }>; doubleClick: Attr<false | "autosize" | "reset" | "reset+autosize", { description: "What double-clicking the plot area does."; dflt: "reset+autosize"; values: readonly [false, "reset", "autosize", "reset+autosize"]; }>; doubleClickDelay: Attr<number, { description: "Maximum delay between two clicks of a double-click, in milliseconds."; dflt: 300; min: 0; }>; editable: Attr<boolean, { description: "Make titles, legend, annotations and shapes editable in place (E6.7)."; dflt: false; }>; edits: ObjectNode<{ annotationPosition: Attr<boolean, { description: "Drag annotations."; dflt: false; }>; annotationTail: Attr<boolean, { description: "Drag annotation arrow tails."; dflt: false; }>; annotationText: Attr<boolean, { description: "Edit annotation text."; dflt: false; }>; axisTitleText: Attr<boolean, { description: "Edit axis titles."; dflt: false; }>; colorbarPosition: Attr<boolean, { description: "Drag colorbars."; dflt: false; }>; colorbarTitleText: Attr<boolean, { description: "Edit colorbar titles."; dflt: false; }>; legendPosition: Attr<boolean, { description: "Drag the legend."; dflt: false; }>; legendText: Attr<boolean, { description: "Edit trace names in the legend."; dflt: false; }>; shapePosition: Attr<boolean, { description: "Drag and resize shapes."; dflt: false; }>; titleText: Attr<boolean, { description: "Edit the figure title."; dflt: false; }>; }>; hoverRenderer: Attr<"dom", { description: "How hover labels render. Only `dom` (positioned HTML over the canvas) exists in M1; a WebGL label renderer is planned (E5.7)."; dflt: "dom"; values: readonly ["dom"]; }>; locale: Attr<string, { description: "Locale of UI strings and number and date formats, e.g. `'de'` or `'de-CH'` (which falls back to `de`, then English). Locales come from `locales` or `register()` (`@mk7s/holochart-locales` ships plotly.js's)."; dflt: "en-US"; noBlank: true; }>; locales: AttrSpec<unknown, unknown>; maxPixelRatio: Attr<number, { description: "Upper limit of the pixel ratio that `pixelRatio: "auto"` takes from the display. Raise it for sharper output on 3× screens, at the cost of drawing more pixels."; dflt: 2; max: 8; min: 0.25; }>; modeBarButtonsToAdd: AttrSpec<unknown, unknown>; modeBarButtonsToRemove: AttrSpec<string[], string[]>; pixelRatio: Attr<number | "auto", { description: "Renderer pixel ratio. `auto` uses `window.devicePixelRatio`, up to `maxPixelRatio`."; dflt: "auto"; extras: readonly ["auto"]; max: 8; min: 0.25; }>; powerPreference: Attr<"default" | "high-performance" | "low-power", { description: "WebGL context power preference hint."; dflt: "default"; values: readonly ["default", "high-performance", "low-power"]; }>; renderHover: AttrSpec<AnyFunction, | AnyFunction | undefined>; responsive: Attr<boolean, { description: "Resize the chart when its container or the window resizes."; dflt: false; }>; scrollZoom: Attr< | boolean | "map" | "cartesian" | "scene" | "geo" | `map+${string}` | `cartesian+${string}` | `scene+${string}` | `geo+${string}`, { description: "Which subplot kinds zoom on mouse wheel. `true`/`false` enable/disable all of them."; dflt: "scene+geo+map"; extras: readonly [true, false]; flags: readonly ["cartesian", "scene", "geo", "map"]; }>; sharedRenderer: Attr<boolean | "auto", { description: "Draw through one WebGL context shared by every chart on the page instead of a context per chart (browsers keep about 16, fewer on mobile). `auto` gives the first 4 charts a context of their own and shares for the rest. `false` always takes a context."; dflt: "auto"; values: readonly ["auto", true, false]; }>; staticPlot: Attr<boolean, { description: "Render once with no interactivity (no hover, zoom or modebar)."; dflt: false; }>; strict: Attr<boolean, { description: "Throw on the first validation error instead of warning (once per attribute path)."; dflt: false; }>; textRenderer: Attr<"dom" | "webgl", { description: "Render text as WebGL SDF glyphs or as a DOM overlay (ADR-005)."; dflt: "webgl"; values: readonly ["webgl", "dom"]; }>; toImageButtonOptions: ObjectNode<{ filename: Attr<string, { description: "File name."; dflt: "newplot"; noBlank: true; }>; format: Attr<"png" | "jpeg" | "webp", { description: "Image format."; dflt: "png"; values: readonly ["png", "jpeg", "webp"]; }>; height: Attr<number, { description: "Height in CSS pixels (defaults to the chart)."; min: 1; }>; scale: Attr<number, { description: "Resolution multiplier."; dflt: 1; min: 0; }>; width: Attr<number, { description: "Width in CSS pixels (defaults to the chart)."; min: 1; }>; }>; topojsonURL: Attr<string, { description: string; dflt: ""; }>; worker: Attr<boolean | "auto", { description: "Run the calc stage in a Web Worker (ADR-011). `auto` switches on above a data-size threshold."; dflt: false; values: readonly [true, false, "auto"]; }>; }> | undefined

fullData

Get Signature

get fullData(): readonly FullTrace[];

Traces after defaults (as of the last pipeline run).

Returns

readonly FullTrace[]

fullLayout

Get Signature

get fullLayout(): FullLayout | undefined;

Layout after defaults and layout (axis ranges hold the ranges in use).

Returns

FullLayout | undefined

interaction

Get Signature

get interaction(): FxSettings;

Experimental

The interaction settings in effect (hovermode, dragmode, clickmode, …).

Returns

FxSettings

layout

Get Signature

get layout(): Readonly<Record<string, unknown>>;

Returns

Readonly<Record<string, unknown>>

registry

Get Signature

get registry(): ChartRegistry;

Experimental

The registry this chart resolves trace types and components from. chartToJSON(chart) reads it to decide which style functions become per-point arrays.

Returns

ChartRegistry

size

Get Signature

get size(): Readonly<Size>;

Figure size in CSS px.

Returns

Readonly<Size>

subplots

Get Signature

get subplots(): ReadonlyMap<string, SubplotInfo>;

Experimental

The solved subplots, by id (see Chart.axes).

Returns

ReadonlyMap<string, SubplotInfo>

three

Get Signature

get three(): ChartThree;

Returns

ChartThree

Methods

addFrames()

addFrames(frames, indices?): Promise<Chart>;

Add animation frames (Plotly addFrames): a frame whose name is taken replaces that frame; others are inserted at indices[i] (default: appended). Unnamed frames are named 'frame <n>'. See animate.

Parameters

Parameter	Type
`frames`	\| readonly `FrameInput`<`object`>[] \| `null` \| `undefined`
`indices?`	`number` \| readonly (`number` \| `null` \| `undefined`)[]

Returns

Promise<Chart>

addTraces()

addTraces(traces, newIndices?): Promise<Chart>;

Add traces (at the end, or at newIndices in the final order, like Plotly).

Parameters

Parameter	Type
`traces`	`object` \| readonly `object`[]
`newIndices?`	`TraceIndices`

Returns

Promise<Chart>

animate()

animate(target?, options?): Promise<Chart>;

Play frames (Plotly animate): every frame, a frame group by name, frame names in a list (['2007']), or frame objects; each frame transitions in over transition.duration and the next starts frame.duration later. Resolves once the last frame has played; rejects when a later call (mode: 'next' / 'immediate') drops it. Emits animating, animatingframe (sliders follow it), transitioning / transitioned and animated. The animation code loads on first use.

Parameters

Parameter	Type
`target?`	`AnimateTarget`
`options?`	`AnimationOptions`

Returns

Promise<Chart>

Example

await chart.animate(null, { frame: { duration: 500 }, transition: { duration: 300 } });
await chart.animate([null], { mode: 'immediate' }); // pause

animateCamera()

animateCamera(camera, options?): Promise<Chart>;

Fly a 3D scene's camera to camera (E7.5; Plotly's scene.camera shape, missing parts kept): it orbits the scene over duration ms with easing, then commits the camera with a relayout ('scene.camera') and resolves. Dragging the scene, a camera change or another animateCamera interrupts it (rejects, AnimationInterrupted); reduced motion jumps.

Parameters

Parameter	Type
`camera`	`CameraTarget`
`options`	`CameraAnimationOptions`

Returns

Promise<Chart>

Example

await chart.animateCamera({ eye: { x: 2, y: 0, z: 0.5 } }, { duration: 1500 });

autoscale()

autoscale(): Promise<Chart>;

Autorange every axis (modebar "autoscale").

Returns

Promise<Chart>

clearSelection()

clearSelection(): Promise<Chart>;

Clear every selection, layout.selections included (emits deselect when there was one).

Returns

Promise<Chart>

commitRanges()

commitRanges(ranges): Promise<Chart>;

Experimental

Set axis ranges as a user interaction (M3 wave 2, E5.9): linear coordinates keyed by axis id, committed with one GUI relayout (kept across uirevision) whose event carries Plotly's 'xaxis.range[0]' / 'xaxis.range[1]' keys, like the end of a zoom drag.

Parameters

Parameter	Type
`ranges`	`Readonly`<`Record`<`string`, readonly [`number`, `number`]>>

Returns

Promise<Chart>

deleteFrames()

deleteFrames(indices?): Promise<Chart>;

Remove frames by index (Plotly deleteFrames); every frame when indices is omitted.

Parameters

Parameter	Type
`indices?`	`number` \| readonly `number`[] \| `null`

Returns

Promise<Chart>

deleteTraces()

deleteTraces(indices): Promise<Chart>;

Remove traces by index (negative indices count from the end).

Parameters

Parameter	Type
`indices`	`TraceIndices`

Returns

Promise<Chart>

describe()

describe(): Promise<ChartDescription | undefined>;

The description with its generated summary (E17.2): resolves once the summary code (and, with config.a11y.dataTable: 'visible', the table code) has loaded, which happens after the first draw anyway. undefined before the first draw.

Returns

Promise<ChartDescription | undefined>

destroy()

destroy(): void;

Free every GPU resource, listener and DOM node the chart created. Idempotent.

Returns

void

downloadImage()

downloadImage(options?): Promise<string>;

toImage and save the result as <filename>.<format> (default newplot.png) through a download link (Plotly's downloadImage). Resolves to the file name.

Parameters

Parameter	Type
`options`	`DownloadImageOptions`

Returns

Promise<string>

emit()

emit<K>(type, payload): boolean;

Experimental

Emit an event to this chart's listeners (components use it for legendclick, …). Returns false when a listener returned false, i.e. the default action should be skipped.

Type Parameters

Type Parameter
`K` extends keyof `ChartEvents`

Parameters

Parameter	Type
`type`	`K`
`payload`	`ChartEvents`[`K`]

Returns

boolean

extendTraces()

extendTraces(
   update,
   indices,
   maxPoints?
): Promise<Chart>;

Append points to traces (Plotly extendTraces, plan E7.2): update gives, per attribute string, one array of new values per listed trace — extendTraces({ x: [[4, 5]], y: [[1, 2]] }, [0]). maxPoints keeps only the last points (a rolling window): a number for everything, an object with one number per trace per key ({ y: [1000] }), or { maxPoints: 1000 }.

Arrays are not mutated: plain arrays are replaced by new ones, typed arrays by views into a buffer that grows in place (see spliceArray). Streaming-aware traces (scatter) convert and upload only the new points and update the autorange incrementally. Resolves after render; a redraw event follows (Plotly's plotly_redraw).

Parameters

Parameter	Type
`update`	`StreamUpdate`
`indices`	`TraceIndices`
`maxPoints?`	`MaxPoints`

Returns

Promise<Chart>

Throws

(rejects) With Plotly's messages for malformed arguments, or when a key names a missing or non-array attribute; nothing is changed then.

getCalcdata()

getCalcdata(index): unknown;

Experimental

Calcdata of trace index, as produced by its module's calc.

Parameters

Parameter	Type
`index`	`number`

Returns

unknown

getTraceObjects()

getTraceObjects(index): Object3D<Object3DEventMap>[];

The three.js objects trace index currently draws with.

Parameters

Parameter	Type
`index`	`number`

Returns

Object3D<Object3DEventMap>[]

hover()

hover(target): void;

Show hover labels and emit hover programmatically (Plotly Fx.hover): points by trace and index, or a position in data units ({ xval, yval, subplot? }) resolved with hovermode.

Parameters

Parameter	Type
`target`	\| readonly `object`[] \| { `subplot?`: `string`; `xval?`: `unknown`; `yval?`: `unknown`; }

Returns

void

moveTraces()

moveTraces(current, newIndices?): Promise<Chart>;

Reorder traces (Plotly moveTraces); without newIndices they move to the end.

Parameters

Parameter	Type
`current`	`TraceIndices`
`newIndices?`	`TraceIndices`

Returns

Promise<Chart>

off()

off<K>(type, listener?): void;

Unsubscribe listener, or every listener of type when omitted.

Type Parameters

Type Parameter
`K` extends `ChartEventKey`

Parameters

Parameter	Type
`type`	`K`
`listener?`	`ChartListener`<`K`>

Returns

void

on()

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

Subscribe to an event (Plotly names such as 'plotly_relayout' work too).

Type Parameters

Type Parameter
`K` extends `ChartEventKey`

Parameters

Parameter	Type
`type`	`K`
`listener`	`ChartListener`<`K`>

Returns

() => void

once()

once<K>(type, listener): () => void;

Type Parameters

Type Parameter
`K` extends `ChartEventKey`

Parameters

Parameter	Type
`type`	`K`
`listener`	`ChartListener`<`K`>

Returns

() => void

prependTraces()

prependTraces(
   update,
   indices,
   maxPoints?
): Promise<Chart>;

Insert points at the start of traces (Plotly prependTraces); see extendTraces.

Parameters

Parameter	Type
`update`	`StreamUpdate`
`indices`	`TraceIndices`
`maxPoints?`	`MaxPoints`

Returns

Promise<Chart>

previewRanges()

previewRanges(ranges): void;

Experimental

Show axis ranges now without committing them (M3 wave 2, E5.9: interactive components such as the range slider preview a drag this way): linear coordinates keyed by axis id ({ x: [l0, l1] }). Like a zoom drag, traces only get new transforms, components redraw their ticks, linked axes (matches, scaleanchor) follow, and relayouting is emitted; the input layout is untouched. Finish with commitRanges, or undo by previewing the ranges shown before.

Parameters

Parameter	Type
`ranges`	`Readonly`<`Record`<`string`, readonly [`number`, `number`]>>

Returns

void

react()

react(figure): Promise<Chart>;

Replace the figure (Plotly react). Only what changed is recomputed (core diffFigures): matched traces keep their GPU objects, data arrays compare by reference, and a changed config re-creates the renderer.

Parameters

Parameter	Type
`figure`	`FigureInput`

Returns

Promise<Chart>

refreshHover()

refreshHover(): void;

Experimental

Hover again where the pointer is, on the next frame (M6: for hover sources that answer asynchronously, such as a 3D scene's GPU picking, or whose points moved without a redraw, such as an orbiting camera). No-op when the pointer is away or a gesture is in progress.

Returns

void

relayout()

relayout(update, options?): Promise<Chart>;

Change layout attributes by attribute string (Plotly relayout), e.g. 'xaxis.range[0]'. gui: true marks it as a user interaction (zoom, modebar), which uirevision preserves.

Parameters

Parameter	Type
`update`	`LayoutUpdate`
`options`	{ `gui?`: `boolean`; }
`options.gui?`	`boolean`

Returns

Promise<Chart>

resetAxes()

resetAxes(): Promise<Chart>;

Return every axis to its initial range (modebar "reset axes").

Returns

Promise<Chart>

resize()

resize(): Promise<Chart>;

Re-measure the container and re-layout (automatic with config.responsive).

Returns

Promise<Chart>

restyle()

restyle(
   update,
   traces?,
   options?
): Promise<Chart>;

Change trace attributes by attribute string (Plotly restyle). Array values give one value per listed trace, so wrap data arrays: restyle({ x: [[1, 2, 3]] }, 0). null resets an attribute to its default; undefined is ignored.

Parameters

Parameter	Type
`update`	`AttributeUpdate`
`traces?`	`TraceIndices`
`options?`	{ `gui?`: `boolean`; }
`options.gui?`	`boolean`

Returns

Promise<Chart>

setDragmode()

setDragmode(mode): Promise<Chart>;

Set layout.dragmode as a user interaction (modebar buttons; kept across uirevision).

Parameters

Parameter	Type
`mode`	`Dragmode`

Returns

Promise<Chart>

setHovermode()

setHovermode(mode): Promise<Chart>;

Set layout.hovermode as a user interaction (modebar hover buttons).

Parameters

Parameter	Type
`mode`	`Hovermode`

Returns

Promise<Chart>

toImage()

toImage(options?): Promise<string>;

Render the chart to an image (Plotly's toImage): resolves to a data URL (data:image/png; base64,…). The figure is laid out again at width × height (default: the chart's size) and drawn offscreen at scale pixels per CSS px — not a screenshot of the canvas, and the live chart is untouched. Includes everything drawn in WebGL (traces, axes, text, legend, annotations, shapes, images) and the current interactive selection; excludes the modebar, hover labels and selection outlines. transparent: true drops the background. The export code loads on first use.

Parameters

Parameter	Type
`options`	`ToImageOptions`

Returns

Promise<string>

Example

const png = await chart.toImage({ width: 1200, height: 600, scale: 2 });

toJSON()

toJSON(): never;

Not supported: a chart is not JSON data. Call chartToJSON(chart), which keeps the serializer out of bundles that never save a figure. This stub makes JSON.stringify(chart) fail loudly instead of writing the chart object's own fields.

Returns

never

Deprecated

Use chartToJSON(chart).

unhover()

unhover(): void;

Hide hover labels (emits unhover when something was hovered).

Returns

void

update()

update(patch, options?): Promise<Chart>;

Deep-merge a partial figure (plan §7.2): chart.update({ data: [{ y }] }, { traces: [2] }). Nested objects merge; arrays and other values replace; null resets to the default.

Parameters

Parameter	Type
`patch`	`FigurePatch`
`options`	{ `traces?`: `TraceIndices`; }
`options.traces?`	`TraceIndices`

Returns

Promise<Chart>

updateAttributes()

updateAttributes(
   traceUpdate,
   layoutUpdate,
   traces?
): Promise<Chart>;

restyle and relayout in one update (Plotly's update).

Parameters

Parameter	Type
`traceUpdate`	`AttributeUpdate`
`layoutUpdate`	`LayoutUpdate`
`traces?`	`TraceIndices`

Returns

Promise<Chart>

zoom()

zoom(factor, options?): Promise<Chart>;

Zoom every (non-fixed) axis of a subplot — all subplots by default — around its center: factor < 1 zooms in (modebar zoom in: 0.5, zoom out: 2).

Parameters

Parameter	Type
`factor`	`number`
`options`	{ `subplot?`: `string`; }
`options.subplot?`	`string`

Returns

Promise<Chart>

Class: Chart ​

Properties ​

Accessors ​

axes ​

Get Signature ​

Returns ​

config ​

Get Signature ​

Returns ​

data ​

Get Signature ​

Returns ​

datasets ​

Get Signature ​

Returns ​

description ​

Get Signature ​

Returns ​

destroyed ​

Get Signature ​

Returns ​

frames ​

Get Signature ​

Returns ​

fullConfig ​

Get Signature ​

Returns ​

fullData ​

Get Signature ​

Returns ​

fullLayout ​

Get Signature ​

Returns ​

interaction ​

Get Signature ​

Returns ​

layout ​

Get Signature ​

Returns ​

registry ​

Get Signature ​

Returns ​

size ​

Get Signature ​

Returns ​

subplots ​

Get Signature ​

Returns ​

three ​

Get Signature ​

Returns ​

Methods ​

addFrames() ​

Parameters ​

Returns ​

addTraces() ​

Parameters ​

Returns ​

animate() ​

Parameters ​

Returns ​

Example ​

animateCamera() ​

Parameters ​

Returns ​

Example ​

autoscale() ​

Returns ​

clearSelection() ​

Returns ​

commitRanges() ​

Parameters ​

Returns ​

deleteFrames() ​

Parameters ​

Returns ​

deleteTraces() ​

Parameters ​

Returns ​

describe() ​

Class: Chart

Properties

Accessors

axes

Get Signature

Returns

config

Get Signature

Returns

data

Get Signature

Returns

datasets

Get Signature

Returns

description

Get Signature

Returns

destroyed

Get Signature

Returns

frames

Get Signature

Returns

fullConfig

Get Signature

Returns

fullData

Get Signature

Returns

fullLayout

Get Signature

Returns

interaction

Get Signature

Returns

layout

Get Signature

Returns

registry

Get Signature

Returns

size

Get Signature

Returns

subplots

Get Signature

Returns

three

Get Signature

Returns

Methods

addFrames()

Parameters

Returns

addTraces()

Parameters

Returns

animate()

Parameters

Returns

Example

animateCamera()

Parameters

Returns

Example

autoscale()

Returns

clearSelection()

Returns

commitRanges()

Parameters

Returns

deleteFrames()

Parameters

Returns

deleteTraces()

Parameters

Returns

describe()