Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TargetProcess/tauCharts/llms.txt

Use this file to discover all available pages before exploring further.

Plot is the base class that Chart extends. It owns the rendering pipeline, the filter store, the event system, and the layout DOM structure. In the vast majority of cases you should use Chart, which auto-detects the chart type and converts a ChartSpec into the internal GPL format for you. Use Plot directly only when you need to supply a pre-built GPL spec (an object that already has sources and scales properties) and want to bypass the type-based conversion layer entirely.
Because Chart extends Plot, every method documented here is also available on Chart instances.

​
When to use Plot vs Chart

ScenarioUse
Standard chart types (bar, line, scatterplot, etc.) with ChartSpecChart
Custom GPL spec with explicit sources and scalesPlot
Plugin development that operates on the base classPlot (as a type reference)
All other production useChart

​
Constructor

new Taucharts.Plot(config: ChartSpec)
Creates a new Plot instance. Accepts the same ChartSpec shape as Chart. Unlike Chart, Plot does not run the chart-type registry lookup: if your config looks like a GPL spec (has both sources and scales top-level properties) it is used as-is; otherwise it is passed through SpecConverter.
​
config
ChartSpec
required
Configuration object. See ChartSpec for the full field reference. When passing a GPL spec directly, ensure the object has sources and scales properties.

​
Methods

​
renderTo

renderTo(targetOrSelector: Element | string, size?: PlotSize): void
Appends the chart layout to the given container and starts the rendering pipeline. If the data sources are empty the content area is replaced with config.emptyContainer HTML (an empty string by default).
​
targetOrSelector
Element | string
required
A DOM element or CSS selector string identifying the container. Throws Error('Target element not found') if the selector matches nothing.
​
size
PlotSize
Explicit { width?, height? } in pixels. When omitted the chart measures the container automatically.

​
getSVG

getSVG(): SVGSVGElement
Returns the <svg> element produced by the last render. Returns null when the chart has not yet been rendered or when the data is empty.

​
addFilter

addFilter(filter: any): number
Registers a data filter. Filters are applied to the data source before each render so they affect both the visual encoding and the domain of every scale.
​
filter
object
required
An object with at minimum a predicate: (row) => boolean function. Additional optional fields:
  • tag — string label for grouping filters (e.g. 'user', 'default'). Filters with the same tag are managed together.
  • src — data source key. Defaults to '/', the primary source.
Returns a numeric ID. Store it to pass to removeFilter.

​
removeFilter

removeFilter(id: number): this
Removes the filter with the given ID from the filter store. Returns this for chaining. Does not trigger a re-render; call refresh() separately.
​
id
number
required
The numeric ID returned by addFilter.

​
refresh

refresh(): void
Triggers a full re-render into the same container and at the same size as the most recent renderTo call. No-op if renderTo has not been called yet.

​
updateConfig

updateConfig(config: ChartSpec): void
Replaces the current configuration by calling applyConfig, then immediately calls refresh. All existing filters are cleared when the config is applied.
​
config
ChartSpec
required
Complete replacement configuration object.

​
resize

resize(size?: PlotSize): void
Re-renders the chart at a new size. Equivalent to calling renderTo(currentTarget, size).
​
size
PlotSize
New dimensions. Omit to let the chart re-measure its container.

​
getLayout

getLayout(): PlotLayout
Returns the PlotLayout object holding references to all structural DOM elements. See the PlotLayout interface in the Chart reference for the full field list.

​
destroy

destroy(): void
Destroys all grammar nodes, removes the SVG and layout elements from the DOM, cancels in-flight async rendering tasks, and unregisters all event listeners via the Emitter base class.
A destroyed instance cannot be re-rendered. Construct a new Plot or Chart if you need to render again.

​
Emitter methods

Plot implements the Emitter interface. All Chart instances inherit these methods.

​
on

on(name: string, callback: EventCallback, context?: any): EventHandlerMap
Subscribes to a named event. Returns an EventHandlerMap suitable for removeHandler.
​
name
string
required
Event name. The Plot source defines typed overloads for 'render', 'beforerender', 'specready', 'unitsstructureexpanded', 'renderingtimeout', 'renderingerror', 'unitdraw', 'elementclick', 'elementmouseover', and 'elementmouseout'.
​
callback
EventCallback
required
Signature: (sender: Emitter, data: any) => void.
​
context
any
Optional this binding for the callback.

​
addHandler

addHandler(callbacks: EventHandlerMap, context?: any): void
Subscribes multiple handlers in one call.
​
callbacks
EventHandlerMap
required
Object map of { eventName: callback } pairs.
​
context
any
Optional this binding for all callbacks in the map.

​
removeHandler

removeHandler(callbacks: EventHandlerMap, context?: any): void
Unsubscribes handlers previously registered with addHandler. Pass the same callbacks reference and context.
​
callbacks
EventHandlerMap
required
The EventHandlerMap passed to addHandler.
​
context
any
The context passed to addHandler.

​
fire

fire(name: string, data: any): void
Emits a named event synchronously, invoking all current listeners.
​
name
string
required
Event name.
​
data
any
required
Payload passed to each listener as the second argument.

​
Internal spec pipeline

Understanding the pipeline helps when writing plugins or debugging rendering issues. 
ChartSpec (user config)
  │
  ▼  [Chart only] chartTypesRegistry.get(config.type)(config)
  │
  ▼  SpecConverter.convert()  — if config is not already a GPL spec
  │
  ▼  Plot.setupPeriodData()   — resolves period scale names
  │
  GPLSpec (configGPL)
  │
  ▼  renderTo() called
  │
  ▼  SpecTransformApplyRatio + SpecTransformAutoLayout  (transformers[])
  │
  ▼  'specready' event fires with the live spec
  │
  ▼  GPL.unfoldStructure()    — expands the unit tree
  │
  ▼  SpecTransformExtractAxes + SpecTransformCalcSize  (onUnitsStructureExpandedTransformers[])
  │
  ▼  'unitsstructureexpanded' event fires
  │
  ▼  'beforerender' event fires
  │
  ▼  Grammar elements drawn via TaskRunner (async by default)
  │
  ▼  'render' event fires
Each step in transformers and onUnitsStructureExpandedTransformers receives and returns a GPLSpec. Plugins hook into this pipeline by listening to the lifecycle events or implementing onRender in the PluginObject interface.

​
Example: Plot vs Chart

import Taucharts from 'taucharts';

const data = [
  { x: 1, y: 10 },
  { x: 2, y: 40 },
  { x: 3, y: 25 },
];

// Typical usage: use Chart, not Plot
const chart = new Taucharts.Chart({
  type: 'line',
  x: 'x',
  y: 'y',
  data,
});
chart.renderTo('#container');

// Advanced usage: provide a GPL spec directly to Plot
// (requires deep knowledge of the GPL format)
const plot = new Taucharts.Plot({
  sources: {
    '/': {
      dims: {
        x: { type: 'measure' },
        y: { type: 'measure' },
      },
      data,
    },
  },
  scales: {
    x: { type: 'linear', source: '/', dim: 'x' },
    y: { type: 'linear', source: '/', dim: 'y' },
    color: { type: 'color', source: '/', dim: null },
    size: { type: 'size', source: '/', dim: null },
  },
  unit: {
    type: 'COORDS.RECT',
    x: 'x',
    y: 'y',
    units: [{ type: 'ELEMENT.LINE' }],
  },
  settings: Taucharts.api.globalSettings,
});
plot.renderTo('#container-low-level');
When extending Plot in a plugin or custom wrapper, call super.destroy() inside your own destroy() method to ensure event listeners are cleaned up by the Emitter base.

Build docs developers (and LLMs) love

Get started for freeTalk to us