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.

Chart extends Plot and is the primary entry point for creating Taucharts visualizations. Pass a ChartSpec configuration object to the constructor and Taucharts automatically detects the chart type, sets up dimension metadata, and converts the config into a lower-level GPL spec before rendering. For most use cases you should use Chart rather than Plot directly.

​
Constructor

new Taucharts.Chart(config: ChartSpec)
Creates a new chart instance. The chart is not rendered until you call renderTo. When config.autoResize is true (the default), the instance is added to Chart.winAware and will resize automatically when the browser window resizes.
​
config
ChartSpec
required
Configuration object that defines the chart type, data, encodings, and settings. See ChartSpec for the full field reference.

​
Static property

​
Chart.winAware
Chart[]
Array of all chart instances that have autoResize enabled. Each instance in this array is resized automatically via requestAnimationFrame when a window resize event fires. Instances are removed from the array when destroy() is called.

​
Methods

​
renderTo

renderTo(targetOrSelector: Element | string, size?: PlotSize): void
Renders the chart into a DOM element. Call this once after constructing the chart, or again after updateConfig if you need to move the chart to a different container.
​
targetOrSelector
Element | string
required
The container element, or a CSS selector string that resolves to one. Throws if the element is not found.
​
size
PlotSize
Optional explicit width and/or height in pixels. When omitted the chart measures the container and fills it.

​
getSVG

getSVG(): SVGSVGElement
Returns the rendered <svg> element. Returns null before renderTo has been called or when the data source is empty.

​
addFilter

addFilter(filter: any): number
Adds a data filter that is applied before rendering. Returns a numeric filter ID you can pass to removeFilter later.
​
filter
object
required
Filter descriptor object. At minimum provide a predicate function (row) => boolean. You can also set tag (string, for grouping) and src (string, data source key, defaults to '/').

​
removeFilter

removeFilter(id: number): this
Removes the filter with the given ID. Returns the chart instance for chaining. Does not re-render automatically; call refresh() afterwards if needed.
​
id
number
required
The filter ID returned by addFilter.

​
refresh

refresh(): void
Re-renders the chart in its current container with the current data and config. Equivalent to calling renderTo with the same target and size as the last render.

​
updateConfig

updateConfig(config: ChartSpec): void
Replaces the current chart configuration and immediately re-renders. Resets all filters.
​
config
ChartSpec
required
New configuration object. See ChartSpec for all available fields.

​
resize

resize(size?: PlotSize): void
Resizes the chart. Passing an explicit size overrides the automatic container measurement. Passing no arguments re-measures the container.
​
size
PlotSize
Optional explicit dimensions. Omit to let the chart measure its container.

​
getLayout

getLayout(): PlotLayout
Returns the PlotLayout object containing all layout DOM elements. Useful for plugins that need to insert content into the chart’s header, footer, or sidebars.

​
destroy

destroy(): void
Tears down the chart: removes all grammar nodes, removes the SVG and layout elements from the DOM, cancels any in-progress async rendering, removes the instance from Chart.winAware, and calls super.destroy() to clean up all event listeners.
After destroy() the instance must not be reused. Create a new Chart instance if you need to render again.

​
Event system

Chart inherits the Emitter interface from Plot. All four methods below are available on every chart instance.

​
on

on(name: string, callback: EventCallback, context?: any): EventHandlerMap
Subscribes to a named event. Returns an EventHandlerMap that can be passed to removeHandler for bulk unsubscription.
​
name
string
required
Event name. See lifecycle events below for the list of built-in events.
​
callback
EventCallback
required
Function called when the event fires. Signature: (sender: Emitter, data: any) => void.
​
context
any
Optional this context for the callback.

​
addHandler

addHandler(callbacks: EventHandlerMap, context?: any): void
Subscribes multiple event handlers at once using an object map of { eventName: callback } pairs.
​
callbacks
EventHandlerMap
required
Object whose keys are event names and values are EventCallback functions.
​
context
any
Optional this context applied to all callbacks in the map.

​
removeHandler

removeHandler(callbacks: EventHandlerMap, context?: any): void
Unsubscribes handlers that were registered with addHandler. Pass the same map and context that were used when subscribing.
​
callbacks
EventHandlerMap
required
The same EventHandlerMap object passed to addHandler.
​
context
any
The same context passed to addHandler.

​
fire

fire(name: string, data: any): void
Emits a named event, invoking all registered listeners. Primarily used internally and by plugins, but you can use it to trigger custom events on chart instances.
​
name
string
required
Event name to emit.
​
data
any
required
Payload passed as the second argument to all listeners.

​
Lifecycle events

These events fire automatically during the render pipeline. Subscribe with chart.on(name, callback).
EventCallback signatureWhen it fires
'beforerender'(chart, svg: SVGSVGElement)After the SVG element is created but before grammar elements are drawn
'render'(chart, svg: SVGSVGElement)After all grammar elements have finished drawing
'specready'(chart, spec: GPLSpec)After the live GPL spec has been built and transforms applied
'unitsstructureexpanded'(chart, spec: GPLSpec)After the unit tree has been fully expanded, before drawing begins
'renderingtimeout'(chart, timeout: number)When async rendering exceeds settings.renderingTimeout
'renderingerror'(chart, error: Error)When settings.handleRenderingErrors is true and rendering throws
'elementclick'(chart, event: PointerEvent)User clicks a chart element
'elementmouseover'(chart, event: PointerEvent)Pointer enters a chart element
'elementmouseout'(chart, event: PointerEvent)Pointer leaves a chart element
'unitdraw'(chart, unit: GrammarElement)Each grammar unit finishes drawing

​
PlotSize interface

​
width
number
Optional explicit width in pixels.
​
height
number
Optional explicit height in pixels.

​
PlotLayout interface

The object returned by getLayout(). All properties are HTMLDivElement references.
​
layout
HTMLDivElement
The outermost container element that is appended to the target.
​
header
HTMLDivElement
Area above the chart canvas. Contains the render-progress bar.
​
content
HTMLDivElement
The scrollable area that holds the rendered SVG element.
​
contentContainer
HTMLDivElement
Wrapper around content used for scrollbar size compensation.
​
leftSidebar
HTMLDivElement
Column to the left of the chart canvas. Plugins such as legend may insert content here.
​
rightSidebar
HTMLDivElement
Column to the right of the chart canvas.
​
rightSidebarContainer
HTMLDivElement
Scrollable wrapper for rightSidebar.
​
footer
HTMLDivElement
Area below the chart canvas.

​
Example

import Taucharts from 'taucharts';

const data = [
  { month: 'Jan', revenue: 4200, region: 'North' },
  { month: 'Feb', revenue: 3800, region: 'North' },
  { month: 'Jan', revenue: 5100, region: 'South' },
  { month: 'Feb', revenue: 4900, region: 'South' },
];

const chart = new Taucharts.Chart({
  type: 'bar',
  x: 'month',
  y: 'revenue',
  color: 'region',
  data,
  guide: {
    y: { label: 'Revenue (USD)' },
    showGridLines: 'y',
  },
  settings: {
    animationSpeed: 300,
  },
});

// Render into the container
chart.renderTo('#chart-container');

// Listen for render completion
chart.on('render', (sender, svg) => {
  console.log('Chart rendered, SVG dimensions:', svg.getBoundingClientRect());
});

// Add a filter to exclude rows with zero revenue
const filterId = chart.addFilter({
  tag: 'nonzero',
  predicate: (row) => row.revenue > 0,
});

// Apply updated data without rebuilding the whole config
chart.refresh();

// Later: remove the filter
chart.removeFilter(filterId);
chart.refresh();

// Access layout elements (e.g. to insert a custom title)
const { header } = chart.getLayout();
header.insertAdjacentHTML('afterbegin', '<h2 class="chart-title">Monthly Revenue</h2>');

// Clean up when done
chart.destroy();
Set autoResize: true in your config (it is the default) to have the chart resize automatically with the browser window. You can inspect Chart.winAware to see all currently active auto-resizing instances.

Build docs developers (and LLMs) love

Get started for freeTalk to us