Plugins

Plugins are the most efficient way to customize or change the default behavior of a chart. They have been introduced at version 2.1.0 (global plugins only) and extended at version 2.5.0 (per chart plugins and options).

Using plugins

Plugins can be shared between chart instances:

  1. var plugin = { /* plugin implementation */ };
  3. // chart1 and chart2 use "plugin"
  4. var chart1 = new Chart(ctx, {
  5.     plugins: [plugin]
  6. });
  8. var chart2 = new Chart(ctx, {
  9.     plugins: [plugin]
  10. });
  12. // chart3 doesn't use "plugin"
  13. var chart3 = new Chart(ctx, {});

Plugins can also be defined directly in the chart plugins config (a.k.a. inline plugins):

  1. var chart = new Chart(ctx, {
  2.     plugins: [{
  3.         beforeInit: function(chart, options) {
  4.             //..
  5.         }
  6.     }]
  7. });

However, this approach is not ideal when the customization needs to apply to many charts.

Global plugins

Plugins can be registered globally to be applied on all charts (a.k.a. global plugins):

  1. Chart.plugins.register({
  2.     // plugin implementation
  3. });

Note: inline plugins can’t be registered globally.

Configuration

Plugin ID

Plugins must define a unique id in order to be configurable.

This id should follow the npm package name convention:

  • can’t start with a dot or an underscore
  • can’t contain any non-URL-safe characters
  • can’t contain uppercase letters
  • should be something short, but also reasonably descriptive

If a plugin is intended to be released publicly, you may want to check the registry to see if there’s something by that name already. Note that in this case, the package name should be prefixed by chartjs-plugin- to appear in Chart.js plugin registry.

Plugin options

Plugin options are located under the options.plugins config and are scoped by the plugin ID: options.plugins.{plugin-id}.

  1. var chart = new Chart(ctx, {
  2.     options: {
  3.         foo: { ... },           // chart 'foo' option
  4.         plugins: {
  5.             p1: {
  6.                 foo: { ... },   // p1 plugin 'foo' option
  7.                 bar: { ... }
  8.             },
  9.             p2: {
  10.                 foo: { ... },   // p2 plugin 'foo' option
  11.                 bla: { ... }
  12.             }
  13.         }
  14.     }
  15. });

Disable plugins

To disable a global plugin for a specific chart instance, the plugin options must be set to false:

  1. Chart.plugins.register({
  2.     id: 'p1',
  3.     // ...
  4. });
  6. var chart = new Chart(ctx, {
  7.     options: {
  8.         plugins: {
  9.             p1: false   // disable plugin 'p1' for this instance
  10.         }
  11.     }
  12. });

Plugin Core API

Available hooks (as of version 2.7):

  • beforeInit
  • afterInit
  • beforeUpdate (cancellable)
  • afterUpdate
  • beforeLayout (cancellable)
  • afterLayout
  • beforeDatasetsUpdate (cancellable)
  • afterDatasetsUpdate
  • beforeDatasetUpdate (cancellable)
  • afterDatasetUpdate
  • beforeRender (cancellable)
  • afterRender
  • beforeDraw (cancellable)
  • afterDraw
  • beforeDatasetsDraw (cancellable)
  • afterDatasetsDraw
  • beforeDatasetDraw (cancellable)
  • afterDatasetDraw
  • beforeEvent (cancellable)
  • afterEvent
  • resize
  • destroy