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.

Taucharts plugins are plain objects that implement a small set of lifecycle methods. When you pass a plugin in the plugins array of your chart config, Taucharts calls those methods at well-defined points during initialization and rendering. This architecture lets you add custom UI, intercept and modify the chart spec, subscribe to pointer events, and clean up resources when the chart is destroyed — all without touching Taucharts internals.

​
The PluginObject interface

A plugin object can implement any combination of three lifecycle hooks: 
const myPlugin = {
  // Called once when the plugin is initialized with the chart instance.
  // Use this to subscribe to events and store a reference to the chart.
  init(chart) {},

  // Called when the chart is destroyed.
  // Use this to remove event listeners and release any held resources.
  destroy() {},

  // Called after every render completes.
  // Use this to read the rendered SVG and add or update overlay elements.
  onRender() {}
};
All three methods are optional. A valid plugin object can implement just one of them.

​
Registering a plugin

Use Taucharts.api.plugins.add(name, factory) to register a named plugin factory. The factory is a function that accepts a settings object and returns a PluginObject. Once registered, the plugin can be retrieved by name with Taucharts.api.plugins.get(name). 
// Register
Taucharts.api.plugins.add('my-plugin', function (settings) {
  return {
    init(chart) { /* ... */ },
    destroy() { /* ... */ },
    onRender() { /* ... */ }
  };
});

// Use in a chart config
var chart = new Taucharts.Chart({
  type: 'line',
  x: 'Date',
  y: 'Effort',
  data: [...],
  plugins: [
    Taucharts.api.plugins.get('my-plugin')({ /* settings */ })
  ]
});
Each plugin name must be unique. Calling plugins.add with a name that is already registered throws an error.

​
Plugin factory pattern

The recommended pattern is a factory function that closes over the settings parameter and returns a fresh plugin object each time it is called. This ensures each chart instance has its own isolated plugin state. 
function highlightPlugin(settings) {
  settings = Object.assign({ color: 'orange' }, settings);

  var chartRef = null;

  return {
    init(chart) {
      chartRef = chart;
    },
    destroy() {
      chartRef = null;
    },
    onRender() {
      var svg = chartRef.getSVG();
      // manipulate svg using settings.color
    }
  };
}

Taucharts.api.plugins.add('highlight', highlightPlugin);

​
Subscribing to chart events

Inside init(chart), use chart.on(eventName, callback) to subscribe to chart lifecycle events. The callback receives the chart instance as its first argument and event-specific data as the second.
EventFires whenSecond argument
'render'After the chart finishes renderingThe rendered SVGSVGElement
'beforerender'Before the draw phase beginsThe rendered SVGSVGElement
'specready'The GPL spec has been created and transformed by ApplyRatio and AutoLayoutThe live GPLSpec object
'unitsstructureexpanded'The unit structure has been fully unfolded and axes extractedThe final GPLSpec object
init(chart) {
  chart.on('specready', (chart, spec) => {
    // Inspect or mutate the GPL spec before drawing begins.
    console.log(spec.sources, spec.scales);
  });

  chart.on('unitsstructureexpanded', (chart, spec) => {
    // React after the unit tree is fully expanded.
  });

  chart.on('beforerender', (chart, svg) => {
    // Prepare overlay elements before any grammar elements draw.
  });

  chart.on('render', (chart, svg) => {
    // Post-process the completed SVG.
  });
}

​
Accessing the chart layout

chart.getLayout() returns a PlotLayout object containing references to the HTML elements that make up the chart shell. Use these to inject custom UI such as sidebars, headers, or footers without creating conflicting DOM nodes. 
init(chart) {
  const layout = chart.getLayout();
  // layout.layout          — the outermost chart div
  // layout.header          — header area above the chart
  // layout.content         — the SVG content area
  // layout.contentContainer — container wrapping content and sidebars
  // layout.leftSidebar     — left sidebar panel div
  // layout.rightSidebar    — right sidebar panel div
  // layout.footer          — footer area below the chart

  const badge = document.createElement('div');
  badge.className = 'my-plugin__badge';
  badge.textContent = 'Custom header';
  layout.header.appendChild(badge);
}

​
Using PluginsSDK utilities

Taucharts.api.pluginsSDK exposes a set of utilities for working with specs and units inside plugin callbacks.
Wraps a raw spec unit node in a helper object that provides convenience accessors. Useful when you need to inspect or modify a single unit inside an event callback.
const unitHelper = Taucharts.api.pluginsSDK.unit(rawUnit);
Wraps a GPL spec in a helper object for easier traversal and modification.
const specHelper = Taucharts.api.pluginsSDK.spec(liveSpec);
Walks every node in the spec unit tree in a depth-first order, calling iterator(node, parentNode) for each one. Use this to find or modify nodes without writing your own traversal.
Taucharts.api.pluginsSDK.traverseSpec(spec, (node, parent) => {
  if (node.type === 'ELEMENT.POINT') {
    node.guide = node.guide || {};
    node.guide.size = { min: 4, max: 16 };
  }
});
Returns a map of dimension names to format info objects ({ label, format, nullAlias, tickLabel }). Useful for formatting data values consistently with how the chart already displays them.
const info = Taucharts.api.pluginsSDK.extractFieldsFormatInfo(spec);
const formatted = info['Effort'].format(someValue);
Merges custom formatter definitions with the formatters already derived from the spec. Accepts the same formatter shape used by the tooltip and crosshair plugins.
const formatters = Taucharts.api.pluginsSDK.getFieldFormatters(spec, {
  'Effort': { label: 'Hours', format: (x) => x + 'h' }
});
Searches the unit tree starting from node, returning the first node for which predicate returns true.
const pointUnit = Taucharts.api.pluginsSDK.depthFirstSearch(
  spec.unit,
  (node) => node.type === 'ELEMENT.POINT'
);

​
Full working example

The following plugin adds a small label in the chart header showing the number of data points, and removes it when the chart is destroyed. 
Taucharts.api.plugins.add('data-count', function (settings) {
  var chartRef = null;
  var labelEl = null;

  return {
    init(chart) {
      chartRef = chart;

      const layout = chart.getLayout();
      labelEl = document.createElement('div');
      labelEl.className = 'data-count-label';
      layout.header.appendChild(labelEl);

      chart.on('render', () => {
        // Re-read data count after every render.
        const spec = chart.getSpec ? chart.getSpec() : null;
        const count = spec ? spec.sources['/'].data.length : '?';
        labelEl.textContent = `${count} data points`;
      });
    },

    destroy() {
      if (labelEl && labelEl.parentNode) {
        labelEl.parentNode.removeChild(labelEl);
      }
      labelEl = null;
      chartRef = null;
    },

    onRender() {
      // Called automatically after every render.
      // Additional post-render work can go here.
    }
  };
});

// Use the plugin:
var chart = new Taucharts.Chart({
  type: 'bar',
  x: 'team',
  y: 'effort',
  data: [{ team: 'Alpha', effort: 40 }, { team: 'Beta', effort: 55 }],
  plugins: [
    Taucharts.api.plugins.get('data-count')()
  ]
});
chart.renderTo('#chart');
Store event handler references returned by chart.on() if you need to unsubscribe selectively. The destroy() hook is the right place to call chart.removeHandler() and clean up any DOM nodes your plugin created.

Build docs developers (and LLMs) love

Get started for freeTalk to us