Custom Renderers

The built-in SVG renderer is sufficient for most charts. Supply a custom renderer when your application already owns a chart engine or requires a supported alternative backend.

The renderer draws validated chart data; Pivot Charts continues to own report linkage, saved models and queued updates. Use renderer capabilities to compare existing options before implementing another adapter.

Custom renderer contract

Interactive example

Renderers and lifecycle

Inspect the renderer's declared capabilities and the chart it creates.

1
const renderer: PivotChartRenderer = {
2
  capabilities: {
3
    supportedTypes: ['groupedColumn', 'line'],
4
    download: true,
5
    downloadFormats: ['png'],
6
    imageDataUrl: true,
7
  },
8
  create(input) {
9
    const instance = mountApplicationChart(input);
10
    return {
11
      update(nextInput) {
12
        instance.update(nextInput);
13
      },
14
      focus() {
15
        instance.focus();
16
      },
17
      async download(options) {
18
        await instance.downloadPng(options);
19
      },
20
      async getImageDataURL(options) {
21
        return instance.getPngDataUrl(options);
22
      },
23
      destroy() {
24
        instance.destroy();
25
      },
26
    };
27
  },
28
};

PivotChartRenderInput contains the chart ID, container, chart type, validated dataset, bindings, presentation, chart options, axes, series overrides, theme, locale text, and chart/preview render mode. It also supplies interaction mode, persistent selection, derived peer highlightSelections, and activation and clear callbacks. Call onNodeClick for semantic mark activation and onSelectionClear for a user clear action; the plugin dispatches these according to the interaction mode. A custom renderer must not mutate the supplied dataset or model state, or persist peer highlights as local selection.

A renderer can implement optional synchronous validate(input) preflight. Throw when the complete candidate input requests a feature the backend cannot preserve. The plugin runs this hook before renderer creation/update and native selection-filter effects; the hook must be side-effect-free. Existing renderers can omit it. Direct renderer consumers must also receive the same validation from the renderer’s own create and update methods.

Configure the renderer before creating a chart. Renderer injection is a runtime configuration, and is not serialized in the chart model. Replacing that configuration does not migrate an existing chart instance to another backend. Each chart retains its captured factory, validator, and capability contract. Changing pivotCharts.renderer applies to newly created charts. Existing chart controls, previews, updates, and exports continue using their original backend. The optional ECharts Canvas adapter uses this boundary with an explicit supported feature set.

Navigation-capable renderers receive the canonical dataset, authored navigation and viewport, and onViewportChange. Request a semantic window through that callback instead of modifying Pivot filters or the supplied dataset. Window-only updates use the chart’s update queue and do not load another provider dataset. Custom renderers must advertise capabilities.navigation: true to accept authored navigation or viewport settings. Omitting that capability preserves existing renderer integrations and rejects unsupported navigation requests.

The UI intersects the chart catalog with the existing backend’s capabilities. interactionModes and chartOptionKeys can restrict modes and option controls; omitting them uses the catalog defaults. An empty interactionModes list disables authored interaction. A backend’s validate hook remains responsible for additional option combinations and data-specific restrictions. Download and image actions are available only when the renderer advertises and implements them.

Next steps

See data and channels, lifecycle/API and the complete API.