---

name: chartjs-developers description: This skill should be used when the user asks "Chart.js plugin", "custom Chart.js plugin", "Chart.js plugin hooks", "Chart.js beforeDraw", "Chart.js afterDraw", "custom chart type", "extend Chart.js", "Chart.js API", "Chart.js update", "Chart.js destroy", "Chart.js methods", "Chart.js events", "Chart.js canvas", "Chart.js TypeScript", "custom scale", "Chart.js DatasetController", "Chart.js Scale", or needs help creating custom Chart.js v4.5.1 plugins, extensions, custom chart types, custom scales, or using the API.

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

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

Chart Methods

Copy// 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

Copyconst 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

Copy// 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

Copyconst 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

Copyconst 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

Copyconst 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

Update Hooks

Render Hooks

Event Hooks

Destruction Hooks

Accessing Chart Internals

Copy// 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

Copyimport { 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

Copyimport { 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

Copyconst 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

Copyconst 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 from before* hooks to cancel:

Copyconst conditionalPlugin = {
  id: 'conditional',

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

Extending Chart.js

Custom Chart Types

Extend Chart.DatasetController to create new chart types. See references/custom-chart-types.md for:

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

Custom Scales

Extend Chart.Scale to create custom axis types. See references/custom-scales.md for:

• 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 for:

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