plugins

175 notes in this subject, read out of this brain and free to use. This is page 2 of 3.

Extension publication minimum age requirement

Extensions must be at least 30 days old before they can be listed in the awesome Chart.js extensions repository.

ESM and UMD publishing for Chart.js extensions

Chart.js v3 is tree shakeable. When publishing an extension with both ESM and UMD bundles, be aware that the UMD package's global Chart object includes everything, while the ESM package exports items separately. Most exports can be mapped automatically by bundlers, but helpers require special handling.

Helpers import path differs between ESM and UMD

In UMD, helpers are accessed via Chart.helpers. In ESM, helpers are imported from 'chart.js/helpers'. For example, isNullOrUndef is available as Chart.helpers.isNullOrUndef in UMD but must be imported as: import {isNullOrUndef} from 'chart.js/helpers' in ESM.

Rollup output.globals example for Chart.js

This Rollup configuration example shows how to map Chart.js and helper imports to UMD globals: ```js module.exports = { // ... output: { globals: { 'chart.js': 'Chart', 'chart.js/helpers': 'Chart.helpers' } } }; ```

Inline plugin example

Example of defining a plugin directly in the chart plugins config: const chart = new Chart(ctx, { plugins: [{ beforeInit: function(chart, args, options) { // } }] });

Global plugin registration

Plugins can be registered globally using Chart.register() to be applied on all charts. Inline plugins cannot be registered globally.

Plugins introduced version 2.1.0

Plugins were introduced at version 2.1.0 as global plugins only. At version 2.5.0 they were extended to support per-chart plugins and options.

Plugin sharing between chart instances

A single plugin object can be shared between multiple chart instances by passing it in the plugins array when creating new charts.

Inline plugins definition

Plugins can be defined directly in the chart plugins config as inline plugins. Inline plugins are not registered and some plugins require registering and cannot be used inline.

Plugin ID naming conventions

Plugin IDs must be unique and follow npm package name conventions: cannot start with a dot or underscore, cannot contain non-URL-safe characters, cannot contain uppercase letters, and should be short but descriptive. For public plugins, check the npm registry for conflicts and prefix the package name with 'chartjs-plugin-' to appear in the Chart.js plugin registry.

Plugin options configuration location

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

Disable all plugins for specific chart

To disable all plugins for a specific chart instance, set options.plugins to false.

Plugin defaults configuration

Plugin options can have default values defined in the defaults entry of the plugin object. User-provided options in options.plugins.{plugin-id} will override these defaults.

Plugin core API lifecycle hooks

Plugins receive notifications during multiple lifecycle stages: chart initialization, chart update, scale update, rendering, event handling, and chart destroy. Most 'before*' hooks can be cancelled by returning false.

Plugin event handling args.changed flag

During event handling, if a plugin makes changes that require a re-render, it can set args.changed to true to indicate that a render is needed.

Plugin destroy hook deprecation

The destroy hook has been deprecated since Chart.js version 3.7.0. Use the afterDestroy hook instead.

TypeScript plugin typing with declaration merging

To provide TypeScript typings for a plugin, create a .d.ts file that declares the plugin options in the PluginOptionsByType interface using declaration merging on the 'chart.js' module.

Plugin sharing example

Example showing how to share a plugin object between multiple chart instances: const plugin = { /* plugin implementation */ }; const chart1 = new Chart(ctx, { plugins: [plugin] }); const chart2 = new Chart(ctx, { plugins: [plugin] });

Global plugin registration example

Example of registering a plugin globally: Chart.register({ /* plugin implementation */ });

Plugin options scoping example

Example of plugin options scoped by plugin ID: const chart = new Chart(ctx, { options: { foo: { ... }, plugins: { p1: { foo: { ... }, bar: { ... } }, p2: { foo: { ... }, bla: { ... } } } } });

Disable plugin for specific chart example

Example of disabling a global plugin for a specific chart: Chart.register({ id: 'p1', /* ... */ }); const chart = new Chart(ctx, { options: { plugins: { p1: false } } });

Plugin defaults example

Example of setting default plugin options: const plugin = { id: 'custom_canvas_background_color', beforeDraw: (chart, args, options) => { const {ctx} = chart; ctx.save(); ctx.globalCompositeOperation = 'destination-over'; ctx.fillStyle = options.color; ctx.fillRect(0, 0, chart.width, chart.height); ctx.restore(); }, defaults: { color: 'lightGreen' } };

Plugin TypeScript typing example

Example of providing TypeScript typings for a plugin: import {ChartType, Plugin} from 'chart.js'; declare module 'chart.js' { interface PluginOptionsByType<TType extends ChartType> { customCanvasBackgroundColor?: { color?: string } } }

Colors plugin default palette

The built-in Colors plugin cycles through a palette of seven Chart.js brand colors. Import and register it with: import { Colors } from 'chart.js'; Chart.register(Colors);

Colors plugin UMD default behavior

In the UMD version of Chart.js, the Colors plugin is enabled by default. You can disable it by setting the enabled option to false in the plugins.colors configuration.

Colors plugin with dynamic datasets

The colors plugin only works when you initialize the chart without any colors specified by default. To force the colors plugin to always color datasets when using dynamic datasets at runtime, set the forceOverride option to true in plugins.colors configuration.

Colors plugin disable example

This example shows how to disable the Colors plugin in the UMD version: const options = { plugins: { colors: { enabled: false } } };

Colors plugin forceOverride example

This example shows how to force the Colors plugin to always color datasets: const options = { plugins: { colors: { forceOverride: true } } };

Option resolution order for plugin options

Plugin options are resolved in this order: options.plugins[plugin.id], (options.[...plugin.additionalOptionScopes]), overrides[config.type].plugins[plugin.id], defaults.plugins[plugin.id], (defaults.[...plugin.additionalOptionScopes]). A plugin can provide an additionalOptionScopes array of paths to additionally look for its options in. For root scope, use empty string: ''.

Chart plugins in options

Plugins are configured under the plugins section in chart options. For example, legend and tooltip plugins can be configured individually. Many Chart.js features are extracted into plugins which are self-contained, separate pieces of code.

Plugin registration

Plugins can be registered by passing them in a plugins array to a specific chart instance, or globally to all charts. Plugin options are passed in the options.plugins section, keyed by the plugin id.

Plugin structure and lifecycle

A Chart.js plugin is an object with a unique id property and one or more callback functions defined at extension points. The beforeDraw callback is called before rendering the chart and has access to the chart object, canvas context, and chart area dimensions.

Available plugins

Chart.js provides the following plugins: Decimation, Filler (used to fill areas described by LineElement), Legend, SubTitle, Title, and Tooltip.

Chart.js custom plugins

Chart.js is highly customizable with custom plugins to create annotations, zoom, or drag-and-drop functionalities.

destroy plugin hook replaced with afterDestroy

In Chart.js 4.0, the destroy plugin hook has been removed and replaced with afterDestroy.

Removed config._chart and this._chart in filler plugin

In Chart.js 4.0, the fallback to config._chart for this.chart in the filler plugin has been removed, as well as the use of this._chart in the filler plugin.

Data decimation algorithms available

Chart.js provides two data decimation algorithms: 'min-max' which preserves minimum and maximum values in each segment, and 'lttb' (Largest-Triangle-Three-Buckets) which reduces points while maintaining visual shape. The LTTB algorithm accepts a samples parameter to control the target number of output data points.

Data decimation performance example

This example demonstrates using data decimation with 100,000 data points. It shows how to toggle decimation on/off and switch between 'min-max' and 'lttb' algorithms at runtime by setting chart.options.plugins.decimation properties and calling chart.update().

Data decimation plugin configuration options

The decimation plugin has the following configuration options: enabled (boolean, default false) controls whether decimation is active; algorithm (string) specifies the decimation algorithm to use, with supported values being 'min-max' and 'lttb'; samples (number) sets the target number of samples for LTTB algorithm.

Creating canvas linear gradients with color stops

Canvas linear gradients are created with ctx.createLinearGradient(x0, y0, x1, y1) and populated with color stops using gradient.addColorStop(offset, color). The offset ranges from 0 to 1, where 0 is the start point and 1 is the end point. Multiple color stops can be added to create smooth transitions between colors.

TooltipModel.getActiveElements() method

TooltipModel.getActiveElements() returns an array of elements currently active in the tooltip.

Programmatic tooltip trigger example

TooltipModel.setActiveElements() requires position parameter

TooltipModel.setActiveElements() takes two parameters: an array of active element objects (with datasetIndex and index properties) and a position object with x and y coordinates specifying where the tooltip should be displayed on the chart.

Disable tooltips with tooltip enabled false

Tooltips can be disabled by setting plugins.tooltip.enabled to false in the chart options.

Filler plugin propagate option

The filler plugin has a propagate option that can be set to false to prevent fill propagation behavior in line charts.

filler plugin drawTime option values

The filler plugin drawTime option controls when filled areas are drawn on the chart. Valid values are 'beforeDatasetDraw' (default), 'beforeDatasetsDraw', and 'beforeDraw'. The drawTime setting affects the rendering order of filled areas relative to other chart elements.

Filler plugin propagate option

The filler plugin has a propagate option that can be set to true or false to control whether fill properties propagate between datasets.

Filler plugin propagate option

The filler plugin has a propagate option that can be set to true or false. When propagate is enabled, it affects how fill areas interact between datasets in stacked configurations on radar charts.

Legend event hooks example - highlighting chart segments

Example code showing how to use legend onHover and onLeave hooks: when hovering a legend item, append '4D' (semi-transparent alpha) to all dataset colors except the hovered item's color to dim non-matching segments. On leave, remove the alpha channel to restore original colors. The legend item has an index property that identifies which dataset or data point it represents.

Legend onHover event hook

The legend plugin supports an onHover event hook that fires when the user hovers over a legend item. The hook receives three parameters: evt (the event object), item (the legend item that was hovered), and legend (the legend instance). This can be used to highlight corresponding chart elements or modify chart data based on which legend item is hovered.

Legend onLeave event hook

The legend plugin supports an onLeave event hook that fires when the user's mouse leaves a legend item. The hook receives three parameters: evt (the event object), item (the legend item that was left), and legend (the legend instance). This can be used to restore chart appearance or remove highlights after a legend item is no longer hovered.

Accessing chart from legend event hooks

Within legend event hooks, the legend instance passed as the third parameter has a chart property that provides access to the Chart.js instance. This allows you to call legend.chart.update() to re-render the chart after making programmatic changes, and access legend.chart.data.datasets to modify dataset properties.

Legend items generateLabels and legend item properties

The built-in legend label generator can be accessed via chart.options.plugins.legend.labels.generateLabels(chart). It returns an array of items where each item has properties: index, datasetIndex, text, fillStyle, strokeStyle, lineWidth, fontColor, and hidden.

HTML legend setup: disable default legend and specify container

To use an HTML legend plugin, set plugins.legend.display to false to hide the default canvas legend, and provide a containerID option to the htmlLegend plugin configuration. The container should be an empty div element with the ID matching containerID, for example <div id="legend-container"></div>.

HTML legend plugin example with item visibility toggle

This example demonstrates creating a custom HTML legend using a plugin. The plugin creates a ul element in a target div container (specified by containerID), generates legend items using the built-in legend label generator, and attaches click handlers to toggle dataset visibility. For pie and doughnut charts, it calls chart.toggleDataVisibility(item.index). For other chart types, it calls chart.setDatasetVisibility(item.datasetIndex, !chart.isDatasetVisible(item.datasetIndex)). The legend items display a colored box (styled with the item's fillStyle and strokeStyle) and text label that shows line-through text decoration when the item is hidden.

Toggle usePointStyle at runtime

The usePointStyle legend option can be toggled at runtime by modifying chart.options.plugins.legend.labels.usePointStyle and calling chart.update() to refresh the legend display.

usePointStyle legend label option

The usePointStyle option in legend.labels configuration controls whether the legend displays dataset point styles (circles, rectangles, etc.) instead of colored rectangles to identify each dataset. Set usePointStyle to true to enable point style display in the legend.

Point style legend example with rectRot

Example showing how to enable point style in the legend: a line chart dataset with pointStyle: 'rectRot', pointRadius: 5, and pointBorderColor: 'rgb(0, 0, 0)' is configured with legend.labels.usePointStyle: true so the legend displays the rotated rectangle point style instead of a colored box to identify the dataset.

Change legend position with chart.update()

To change the legend position at runtime, set chart.options.plugins.legend.position to the desired value ('top', 'right', 'bottom', or 'left'), then call chart.update() to render the change.

Legend position values

The legend position can be set to 'top', 'right', 'bottom', or 'left' via the chart.options.plugins.legend.position property. The position can be changed dynamically by updating the property and calling chart.update().

Give your agent this brain