Interface: TraceModule<Calc, C>

Experimental

A trace module: core's schema/defaults contract plus the render parts (plan §4.4, E22.1). All render parts are optional, so a core-only module still validates and defaults.

Interaction parts (M1 wave 2): crossTraceCalc (stacking/grouping), hoverPoints, selectPoints, legendIcon; M1 wave 3: colorbar; M2 wave 1: crossTraceLayout and legendItems (domain traces such as pie), and hoverPoints for domain traces (see HoverQuery).

Extends

• CoreTraceModule<C>

Type Parameters

Type Parameter	Default type
Calc	unknown
C extends Children	Children

Properties

Property	Modifier	Type	Description	Overrides	Inherited from
a11y?	readonly	() => Promise<Readonly<Record<string, TraceA11y | undefined>>>	Experimental The module's accessibility code behind a dynamic import() (S2.14), so charts nobody navigates by keyboard don't load it: resolves to the parts by trace type (one chunk can serve every module of a package). The runtime loads it on the chart's first keyboard focus and, for a module without its own describe, after the chart's first description (the generic line shows until then). The module's own keyboardPoints and describe win over the loaded ones.	-	-
animatable?	readonly	readonly string[]	Experimental Attribute paths that support transitions (E7.3).	-	CoreTraceModule.animatable
categories	readonly	readonly TraceCategory[]	Experimental	-	CoreTraceModule.categories
layoutSchema?	readonly	Children	Experimental Layout attributes owned by this trace type (e.g. barmode), coerced when a trace of this type is present.	-	CoreTraceModule.layoutSchema
meta	readonly	TraceModuleMeta	Experimental	-	CoreTraceModule.meta
plot?	readonly	TraceRenderer<Calc>	Experimental	CoreTraceModule.plot	-
schema	readonly	ObjectNode<C>	Experimental	-	CoreTraceModule.schema
touchAction?	readonly	"none" | "pan-y"	Experimental Touch gestures the trace's own pointer handling (TraceView.handlePointer) needs from the browser (E6.6), whatever the dragmode: 'pan-y' when its drags work starting sideways (a swipe that starts vertically still scrolls the page: sankey node drags, polar axis drags), 'none' when a drag in any direction is the trace's (table scrolling, parcoords brushing). The chart canvas' touch-action is the most restrictive of its visible traces' and what its dragmode needs. Default: taps only (the page keeps swipes and pinches).	-	-
type	readonly	string	Experimental	-	CoreTraceModule.type

Methods

axisData()?

optional axisData(trace, axisId): unknown;

Experimental

Multi-subplot traces: the data the trace puts on axis axisId (its category list comes from it, like a trace's x on its x axis), or undefined for none.

Parameters

Parameter	Type
trace	FullTrace
axisId	string

Returns

unknown

---

axisHints()?

optional axisHints(trace):
  | TraceAxisHints
  | undefined;

Experimental

Axis defaults a cartesian trace asks for (ADR-029), called with the defaulted trace while the axes are defaulted: hidden axes, equal scales, and where its positions are when they are not in x / y. Return undefined (or leave the method out) for a trace that is drawn on its axes like any other. The 3D scenes ask it of their traces too, for their three axes.

Parameters

Parameter	Type
trace	FullTrace

Returns

| TraceAxisHints | undefined

Inherited from

CoreTraceModule.axisHints

---

calc()?

optional calc(trace, ctx): Calc;

Experimental

Pure calc: full trace → calcdata.

Parameters

Parameter	Type
trace	FullTrace
ctx	CalcContext

Returns

Calc

Overrides

CoreTraceModule.calc;

---

calcAppend()?

optional calcAppend(
   previous,
   trace,
   ctx,
   append
): Calc | undefined;

Experimental

Streaming calc (E7.2): the trace's calc after extendTraces / prependTraces, from its previous calc, converting only the added points (the retained points' data is unchanged, see TraceAppend). Must equal what calc returns for the new data. Return undefined to fall back to calc (e.g. attributes whose values depend on every point). The previous calc must stay readable until extremesAppend ran (it reads the removed points).

Parameters

Parameter	Type
previous	Calc
trace	FullTrace
ctx	CalcContext
append	TraceAppend

Returns

Calc | undefined

---

categoryValues()?

optional categoryValues(
   calc,
   trace,
   axis,
   ctx
): CategorySamples | undefined;

Experimental

Samples for the value-based categoryorders (E3.6: total descending, median ascending, …; Plotly's sortAxisCategoriesByValue): per point, the category index on axis (the linear coordinate calc produced) and the value to aggregate — a bar's own size (after barnorm), a scatter point's other coordinate, … in calc space. Called after crossTraceCalc for visible traces on a category axis with such an order; if the order changes, the runtime rebuilds the axis' scale and runs calc (and crossTraceCalc) again, like Plotly's second calc pass. Return undefined when the trace has nothing to contribute on this axis (e.g. it is a bar's size axis); traces without this method don't contribute either.

Parameters

Parameter	Type
calc	Calc
trace	FullTrace
axis	"x" | "y"
ctx	CalcContext

Returns

CategorySamples | undefined

---

cells()?

optional cells(trace): readonly TraceCellRef[];

Experimental

Multi-subplot traces (M3 wave 2, E10.9 splom): the cartesian subplots the trace draws on, instead of the one its xaxis / yaxis would name (such a trace is not in the cartesian category and has neither; core's supply-defaults creates its axes and subplots, see core's stashSplomAxis). The runtime then gives calc every axis (ctx.axes), autoranges each axis from extremes(…).byAxis, draws the view with ctx.cells (one per existing subplot, updated on zoom and pan of any of them), and asks hoverPoints / selectPoints once per cell under the pointer or the selection, with that cell's axes and transform in the context. The selection is per trace, so selecting in one cell selects the same points in every cell.

Parameters

Parameter	Type
trace	FullTrace

Returns

readonly TraceCellRef[]

---

colorbar()?

optional colorbar(trace, ctx): ColorbarSpec | null;

Experimental

The colorbar this trace wants (E5.3), or null. Traces sharing a coloraxis return the same coloraxis id; the colorbar component draws one bar per coloraxis (from layout.coloraxisN) and one per trace otherwise (from the trace's own …colorbar container).

Parameters

Parameter	Type
trace	FullTrace
ctx	LegendIconContext

Returns

ColorbarSpec | null

Overrides

CoreTraceModule.colorbar;

---

crossTraceCalc()?

optional crossTraceCalc(entries, ctx): void | Iterable<number, any, any>;

Experimental

Cross-trace calc (bar stacking/grouping, stacked areas): called once per subplot and stack group with every visible trace of the group on it, in trace order, after calc and before extremes. Mutates the calcs in place (e.g. writes stacked bases and group offsets), so it must be idempotent: it reruns on already-processed calcs when another member changes.

The group is the trace type, unless the module's categories list a shared stack group (currently 'bar-like', see the runtime's STACK_GROUPS): then all traces whose modules list it stack together — bar and histogram; waterfall and funnel lay out per type, as in Plotly — and the group's first module (in trace order) that has crossTraceCalc runs it for all of them.

Changed report (E7.2 / E16.3). The return value says which entries' views must redraw:

• undefined (return nothing): every entry changed. Each gets calc, plot and style in its update plan and loses plan.append (so extremes are recomputed and streaming views redraw whole) — the safe default, and what bar does.
• An iterable of entry.index values (the trace's index in data, not its position in entries): only those entries get that treatment. Indices not among entries are ignored. An entry that is not listed keeps its update plan exactly as it was — including plan.append (the streaming fast path of extendTraces) and plot: false (its view is not redrawn and its extremes are not recomputed). So a module may only omit an entry when what its view draws and its autorange read from the calc is unchanged by this call (ideally the very same arrays and objects as before), or when the trace itself was recalculated this pass and this call did not rewrite what calc / calcAppend produced — its plan then already carries calc (or append) from the runtime. When in doubt, list the entry. An empty iterable means nothing changed.

Parameters

Parameter	Type
entries	readonly CrossTraceEntry<Calc>[]
ctx	CrossTraceContext

Returns

void | Iterable<number, any, any>

Overrides

CoreTraceModule.crossTraceCalc;

---

crossTraceLayout()?

optional crossTraceLayout(entries, ctx): void;

Experimental

Cross-trace step for traces in the domain category (M2 wave 1, E4.5): called once per trace type with every visible trace of that type that has a calc, in trace order, with their solved domains — after calc and the final layout pass (margins known), before plot. Pie uses it for what spans traces and depends on the layout: the label → color map shared by all pies (Plotly's _piecolormap) and scalegroup radii. Mutates the calcs in place, so it must be idempotent; it reruns after every layout pass or recalc of a member, and the members' views then get plot: true.

Modules sharing one crossTraceLayout function are one group (M4 wave 1: scatterpolar and barpolar autorange their shared polar subplots together): it is called once with the members of every such module.

Parameters

Parameter	Type
entries	readonly DomainTraceEntry<Calc>[]
ctx	DomainLayoutContext

Returns

void

---

describe()?

optional describe(ctx): TraceDescription | undefined;

Experimental

What assistive technology is told about this trace (E17.1, M2 wave 2): the runtime renders it into the chart's visually hidden description. Traces without it get a generic line (type, name, point count).

Parameters

Parameter	Type
ctx	DescribeContext<Calc>

Returns

TraceDescription | undefined

---

eventData()?

optional eventData(
   calc,
   trace,
   pointIndex,
   selection?
): Readonly<Record<string, unknown>>;

Experimental

Extra fields of point pointIndex in selection events (plotly.js _module.eventData), e.g. polar r / theta. Default: none. selection: the indices of every point of the trace in the selection the event reports, in the order of the event's points (the same array for each of them), for fields that depend on the others (a graph node lists its links to the other selected nodes).

Parameters

Parameter	Type
calc	Calc
trace	FullTrace
pointIndex	number
selection?	readonly number[]

Returns

Readonly<Record<string, unknown>>

---

extremes()?

optional extremes(
   calc,
   trace,
   ctx
): TraceExtremes;

Experimental

Autorange contribution, in linear coordinates with px padding.

Parameters

Parameter	Type
calc	Calc
trace	FullTrace
ctx	CalcContext

Returns

TraceExtremes

---

extremesAppend()?

optional extremesAppend(
   previous,
   calc,
   previousCalc,
   trace,
   ctx,
   append
): TraceExtremes | undefined;

Experimental

Streaming autorange (E7.2): the trace's extremes after calcAppend, from its previous extremes, the added points and the removed ones (in previousCalc) — typically merged in O(added + removed), recomputed only when a removed point was an extreme. Return undefined to fall back to extremes.

Parameters

Parameter	Type
previous	TraceExtremes
calc	Calc
previousCalc	Calc
trace	FullTrace
ctx	CalcContext
append	TraceAppend

Returns

TraceExtremes | undefined

---

hoverPoints()?

optional hoverPoints(
   calc,
   trace,
   query,
   ctx
): HoverPoint[];

Experimental

Points near the pointer for hover (E6.1). Empty when nothing is within query.distance. Domain traces (M2 wave 1) are asked on every hover, wherever the pointer is: they return the point under query.cx / query.cy (container px) with distance 0, or nothing.

Parameters

Parameter	Type
calc	Calc
trace	FullTrace
query	HoverQuery
ctx	HoverContext

Returns

HoverPoint[]

Overrides

CoreTraceModule.hoverPoints;

---

keyboardPoints()?

optional keyboardPoints(
   calc,
   trace,
   ctx
): KeyboardStops | undefined;

Experimental

Every stop keyboard navigation (E6.5) visits, in reading order (pie: its slices in drawing order), shaped like hoverPoints' results; a stop may say where the arrows lead from it (KeyboardPoint.nav: hierarchies, grids) and how it is announced. Cartesian traces whose stops are their data points don't need it (they are navigated along their x / y data). For other cartesian traces (histogram bins, box statistics) an array of stops is ordered along the position axis by its anchors, and stops built on demand (a grid's cells) are followed through nav. Domain traces without it are skipped. Called again after every pipeline run. It may load on first use instead: see a11y.

Parameters

Parameter	Type
calc	Calc
trace	FullTrace
ctx	HoverContext

Returns

KeyboardStops | undefined

---

legendIcon()?

optional legendIcon(trace, ctx?): LegendGlyph;

Experimental

What the legend draws for this trace (E5.2). ctx (M1 wave 2, optional for callers) gives fullLayout, e.g. to resolve colors linked to a coloraxis.

Parameters

Parameter	Type
trace	FullTrace
ctx?	LegendIconContext

Returns

LegendGlyph

Overrides

CoreTraceModule.legendIcon;

---

legendItems()?

optional legendItems(
   calc,
   trace,
   ctx
): readonly LegendItem[] | undefined;

Experimental

One legend item per point instead of one per trace (M2 wave 1, E9.11; Plotly's pie-like legends): pie returns one item per label, in calc order. Items with the same key across traces of one legendgroup show once (the first wins). A click toggles the item's key in layout.hiddenlabels and a double-click isolates it (Plotly's handle_click for pie-like traces); hidden items are drawn faded. Return undefined to fall back to one item per trace (legendIcon).

Parameters

Parameter	Type
calc	Calc
trace	FullTrace
ctx	LegendIconContext

Returns

readonly LegendItem[] | undefined

---

selectPoints()?

optional selectPoints(
   calc,
   trace,
   query,
   ctx
): number[];

Experimental

Indices of the points inside a box or lasso selection (E6.3).

Parameters

Parameter	Type
calc	Calc
trace	FullTrace
query	SelectionQuery
ctx	HoverContext

Returns

number[]

Overrides

CoreTraceModule.selectPoints;

---

subplotDomain()?

optional subplotDomain(trace, fullLayout):
  | {
  x: readonly [number, number];
  y: readonly [number, number];
}
  | undefined;

Experimental

Traces placed by a layout container instead of their own domain (M4 wave 1: polar traces, layout[trace.subplot].domain): the domain the trace draws in, or undefined when it has none. The runtime then treats the trace like a domain trace: it draws into the overlay with TracePlotContext.domain, takes part in crossTraceLayout and is hovered like one.

Parameters

Parameter	Type
trace	FullTrace
fullLayout	FullLayout

Returns

| { x: readonly [number, number]; y: readonly [number, number]; } | undefined

---

supplyDefaults()

supplyDefaults(
   traceIn,
   traceOut,
   ctx
): void;

Experimental

Fill traceOut from traceIn using ctx.coerce. Called after common attributes are coerced, and only for traces with visible !== false.

Parameters

Parameter	Type
traceIn	Readonly<Record<string, unknown>>
traceOut	FullTrace
ctx	TraceDefaultsContext

Returns

void

Inherited from

CoreTraceModule.supplyDefaults

---

supplyLayoutDefaults()?

optional supplyLayoutDefaults(
   layoutIn,
   layoutOut,
   ctx
): void;

Experimental

Extra layout defaults logic, run after layoutSchema is coerced.

Parameters

Parameter	Type
layoutIn	Readonly<Record<string, unknown>>
layoutOut	FullLayout
ctx	LayoutDefaultsContext

Returns

void

Inherited from

CoreTraceModule.supplyLayoutDefaults