Developers

Imperative Zoom/Pan API

Alongside user-driven interactions, it is also possible to imperatively interact with the chart, either to manually zoom into a selected region, or to get information about the current zoom status.

chart.pan(delta, scales?, mode = 'none'): void

Pans the current chart by the specified amount in one or more axes. The value of delta can be a number, in which case all axes are panned by the same amount, or it can be an {x, y} object to pan different amounts in the horizontal and vertical directions. The value of scales is a list of scale objects that should be panned - by default, all scales of the chart will be panned. The value of mode should be one of the Chart.js animation modes (opens new window).

chart.zoom(zoomLevel, mode = 'none'): void

Zooms the current chart by the specified amount in one more axes. The value of zoomLevel can be a number, in which case all axes are zoomed by the same amount, or it can be an {x, y} object to zoom different amounts in the horizontal and vertical directions. The value of mode should be one of the Chart.js animation modes (opens new window).

chart.zoomScale(scaleId, newRange, mode = 'none'): void

Zooms the specified scale to the range given by newRange. This is an object in the form {min, max} and represents the new bounds of that scale. The value of mode should be one of the Chart.js animation modes (opens new window).

chart.resetZoom(mode = 'none'): void

Resets the current chart bounds to the defaults that were used before any zooming or panning occurred. The value of mode should be one of the Chart.js animation modes (opens new window).

chart.getZoomLevel(): number

Returns the current zoom level. If this is the same as the chart's initial scales, the value returned will be 1.0. Otherwise, the value will be less than one if the chart has been zoomed out, and more than one if it has been zoomed in. If different axes have been zoomed by different amounts, the returned value will be the zoom level of the most zoomed out axis if any have been zoomed out, otherwise it will be the zoom level of the most zoomed-in axis.

If the chart has been panned but not zoomed, this method will still return 1.0.

chart.getInitialScaleBounds(): Record<string, {min: number, max: number}>

Returns the initial scale bounds of each scale before any zooming or panning took place. This is returned in the format of an object, e.g.

{
  x: {min: 0, max: 100},
  y1: {min: 50, max: 80},
  y2: {min: 0.1, max: 0.8}
}

chart.isZoomedOrPanned(): boolean

Returns whether the chart has been zoomed or panned - i.e. whether the initial scale of any axis is different to the one used currently.

Custom Scales

You can extend chartjs-plugin-zoom with support for custom scales (opens new window) by using the zoom plugin's zoomFunctions and panFunctions members. These objects are indexed by scale types (scales' id members) and give optional handlers for zoom and pan functionality.

import {Scale} from 'chart.js';
import zoomPlugin from 'chartjs-plugin-zoom';
class MyScale extends Scale {
  /* extensions ... */
}
MyScale.id = 'myScale';
MyScale.defaults = defaultConfigObject;
zoomPlugin.zoomFunctions.myScale = (scale, zoom, center, limits) => false;
zoomPlugin.panFunctions.myScale = (scale, delta, limits) => false;

The zoom and pan functions take the following arguments:

Name	Type	For	Description
scale	Scale	Zoom, Pan	The custom scale instance (usually derived from Chart.Scale)
zoom	number	Zoom	The zoom fraction; 1.0 is unzoomed, 0.5 means zoomed in to 50% of the original area, etc.
center	{x, y}	Zoom	Pixel coordinates of the center of the zoom operation. {x: 0, y: 0} is the upper left corner of the chart's canvas.
delta	number	Pan	Pixel amount to pan by
limits	Limits	Zoom, Pan	Zoom and pan limits (from chart options)

For examples, see chartjs-plugin-zoom's default zoomFunctions and panFunctions handling for standard Chart.js axes (opens new window).