Chart.js Developer Guide (v4.5.1)

Advanced guide for creating custom plugins, extending Chart.js, and using the API.

Chart Instance API

Creating a Chart

const chart = new Chart(ctx, {
  type: 'bar',
  data: { /* ... */ },
  options: { /* ... */ }
});

Chart Methods

// Update chart
chart.update();                      // With animation
chart.update('none');                // Without animation
chart.update('active');              // Only animate active elements

// Data manipulation
chart.data.datasets[0].data.push(newValue);
chart.data.labels.push(newLabel);
chart.update();

// Resize
chart.resize();
chart.resize(width, height);

// Reset to original state
chart.reset();

// Destroy chart instance
chart.destroy();

// Convert to image
const base64Image = chart.toBase64Image();
const base64Image = chart.toBase64Image('image/png', 1.0);

// Show/hide datasets
chart.hide(datasetIndex);
chart.show(datasetIndex);
chart.isDatasetVisible(datasetIndex);
chart.setDatasetVisibility(datasetIndex, visible);

// Toggle data visibility (pie, doughnut, polar, bar)
chart.toggleDataVisibility(index);
chart.getDataVisibility(index);

// Animation control
chart.stop();                        // Stop current animation
chart.render();                      // Redraw without updating data
chart.clear();                       // Clear canvas

// Active elements
chart.setActiveElements([{ datasetIndex: 0, index: 1 }]);

// Dataset info
chart.getVisibleDatasetCount();
chart.getSortedVisibleDatasetMetas();

// Get elements at position
const elements = chart.getElementsAtEventForMode(
  event,
  'nearest',
  { intersect: true },
  true
);

// Get dataset metadata
const meta = chart.getDatasetMeta(datasetIndex);

Creating Custom Plugins

Plugins extend Chart.js functionality through lifecycle hooks.

Basic Plugin Structure

const myPlugin = {
  id: 'myPlugin',

  // Called when plugin is installed
  install(chart, args, options) {},

  // Called when plugin is started
  start(chart, args, options) {},

  // Called when plugin is stopped
  stop(chart, args, options) {},

  // Called when plugin is uninstalled
  uninstall(chart, args, options) {},

  // Lifecycle hooks
  beforeInit(chart, args, options) {},
  afterInit(chart, args, options) {},
  beforeUpdate(chart, args, options) {},
  afterUpdate(chart, args, options) {},
  beforeDraw(chart, args, options) {},
  afterDraw(chart, args, options) {},
  beforeDatasetsDraw(chart, args, options) {},
  afterDatasetsDraw(chart, args, options) {},
  beforeDatasetDraw(chart, args, options) {},
  afterDatasetDraw(chart, args, options) {},
  beforeEvent(chart, args, options) {},
  afterEvent(chart, args, options) {},
  beforeDestroy(chart, args, options) {},
  afterDestroy(chart, args, options) {},

  // Default options
  defaults: {
    color: 'red'
  }
};

Using Plugins

// Per-chart (inline plugin)
new Chart(ctx, {
  plugins: [myPlugin],
  options: {
    plugins: {
      myPlugin: {
        color: 'blue'
      }
    }
  }
});

// Global registration
Chart.register(myPlugin);

// Disable for specific chart
options: {
  plugins: {
    myPlugin: false
  }
}

Example: Canvas Background Plugin

const canvasBackgroundPlugin = {
  id: 'canvasBackground',

  beforeDraw(chart, args, options) {
    const { ctx, chartArea: { left, top, width, height } } = chart;

    ctx.save();
    ctx.fillStyle = options.color || 'white';
    ctx.fillRect(left, top, width, height);
    ctx.restore();
  },

  defaults: {
    color: 'white'
  }
};

// Usage
new Chart(ctx, {
  plugins: [canvasBackgroundPlugin],
  options: {
    plugins: {
      canvasBackground: {
        color: '#f0f0f0'
      }
    }
  }
});

Example: Chart Area Border Plugin

const chartAreaBorderPlugin = {
  id: 'chartAreaBorder',

  beforeDraw(chart, args, options) {
    const { ctx, chartArea: { left, top, width, height } } = chart;

    ctx.save();
    ctx.strokeStyle = options.borderColor || 'black';
    ctx.lineWidth = options.borderWidth || 1;
    ctx.setLineDash(options.borderDash || []);
    ctx.strokeRect(left, top, width, height);
    ctx.restore();
  },

  defaults: {
    borderColor: 'black',
    borderWidth: 1,
    borderDash: []
  }
};

Example: Crosshair Plugin

const crosshairPlugin = {
  id: 'crosshair',

  afterDraw(chart, args, options) {
    if (chart._active && chart._active.length) {
      const activePoint = chart._active[0];
      const { ctx } = chart;
      const { x, y } = activePoint.element;
      const { top, bottom, left, right } = chart.chartArea;

      ctx.save();
      ctx.beginPath();
      ctx.setLineDash([5, 5]);
      ctx.strokeStyle = options.color || 'gray';
      ctx.lineWidth = options.width || 1;

      // Vertical line
      ctx.moveTo(x, top);
      ctx.lineTo(x, bottom);

      // Horizontal line
      ctx.moveTo(left, y);
      ctx.lineTo(right, y);

      ctx.stroke();
      ctx.restore();
    }
  }
};

Plugin Lifecycle Hooks

Initialization Hooks

beforeInit

afterInit

Update Hooks

beforeUpdate

afterUpdate

beforeLayout

afterLayout

beforeDataLimits

afterDataLimits

beforeBuildTicks

afterBuildTicks

Render Hooks

beforeRender

afterRender

beforeDraw

afterDraw

beforeDatasetsDraw

afterDatasetsDraw

beforeDatasetDraw

afterDatasetDraw

Event Hooks

beforeEvent

afterEvent

Destruction Hooks

beforeDestroy

afterDestroy

Accessing Chart Internals

// Chart instance
const chart = Chart.getChart('myChart');  // By canvas ID
const chart = Chart.getChart(canvasElement);  // By element

// Static methods
Chart.register(plugin);              // Register globally
Chart.unregister(plugin);            // Unregister globally

// Chart area bounds
const { left, top, right, bottom, width, height } = chart.chartArea;

// Canvas context
const ctx = chart.ctx;

// Scales
const xScale = chart.scales.x;
const yScale = chart.scales.y;

// Convert between pixel and data values
const xPixel = xScale.getPixelForValue(dataValue);
const xValue = xScale.getValueForPixel(pixelPosition);

// Dataset metadata
const meta = chart.getDatasetMeta(0);
const elements = meta.data;  // Array of visual elements

TypeScript Support

Basic Types

import { Chart, ChartConfiguration, ChartType } from 'chart.js';

const config: ChartConfiguration<'bar'> = {
  type: 'bar',
  data: {
    labels: ['A', 'B', 'C'],
    datasets: [{
      label: 'Dataset',
      data: [1, 2, 3]
    }]
  }
};

const chart = new Chart(canvas, config);

Custom Plugin Types

import { Plugin, ChartType } from 'chart.js';

interface MyPluginOptions {
  color: string;
  enabled: boolean;
}

const myPlugin: Plugin<ChartType, MyPluginOptions> = {
  id: 'myPlugin',
  beforeDraw(chart, args, options) {
    // options is typed as MyPluginOptions
  },
  defaults: {
    color: 'red',
    enabled: true
  }
};

// Extend Chart.js types
declare module 'chart.js' {
  interface PluginOptionsByType<TType extends ChartType> {
    myPlugin?: MyPluginOptions;
  }
}

Working with Canvas

const myPlugin = {
  id: 'customDraw',

  afterDraw(chart) {
    const { ctx, chartArea } = chart;

    ctx.save();

    // Draw custom shape
    ctx.fillStyle = 'rgba(255, 0, 0, 0.5)';
    ctx.beginPath();
    ctx.arc(
      chartArea.left + chartArea.width / 2,
      chartArea.top + chartArea.height / 2,
      50,
      0,
      Math.PI * 2
    );
    ctx.fill();

    // Draw text
    ctx.font = '16px Arial';
    ctx.fillStyle = 'black';
    ctx.textAlign = 'center';
    ctx.fillText('Custom Text', chart.width / 2, chart.height / 2);

    ctx.restore();
  }
};

Event Handling in Plugins

const eventPlugin = {
  id: 'eventHandler',

  beforeEvent(chart, args, options) {
    const event = args.event;

    if (event.type === 'click') {
      console.log('Click at:', event.x, event.y);
    }

    // Return false to stop event propagation
    // return false;
  },

  afterEvent(chart, args, options) {
    if (args.changed) {
      // Chart needs to re-render
    }
  }
};

Cancelling Plugin Execution

Return

false

before*

const conditionalPlugin = {
  id: 'conditional',

  beforeDraw(chart, args, options) {
    if (someCondition) {
      return false;  // Cancel draw
    }
  }
};

Extending Chart.js

Custom Chart Types

Extend

Chart.DatasetController

references/custom-chart-types.md

• DatasetController interface and required methods
• Extending built-in controllers (BarController, LineController, etc.)
• TypeScript typings for custom chart types

Custom Scales

Extend

Chart.Scale

references/custom-scales.md

• Scale interface and required methods
• Scale properties available during fitting
• Utility methods for pixel/value conversion

Updating Charts

Charts can be updated dynamically after creation. See

references/updating-charts.md

• Adding and removing data
• Mutating vs replacing options
• Update modes and animation control