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 | undefined, max: number | undefined}>

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.getZoomedScaleBounds(): Record<string, {min: number, max: number}>

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

{
  x: {min: 25, max: 75},
  y1: {min: 60, max: 90},
  y2: undefined
}

Scale IDs that have not been zoomed will be undefined within the returned object.

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.

chart.isZoomingOrPanning(): boolean

Returns whether the user is currently in the middle of a drag operation or pan operation.

Custom Scales

You can extend chartjs-plugin-zoom with support for custom scales (opens new window) by using the zoom plugin's zoomFunctions, zoomRectFunctions, 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.zoomRectFunctions.myScale = (scale, from, to, limits) => false;
zoomPlugin.panFunctions.myScale = (scale, delta, limits) => false;
// zoomRectFunctions can normally be omitted, since zooming by specific pixel
// coordinates rarely needs special handling.

The zoom, zoomRect, 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.
from	number	ZoomRect	Pixel coordinate of the start of the zoomRect operation.
to	number	ZoomRect	Pixel coordinate of the end of the zoomRect operation.
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, zoomRectFunctions, and panFunctions handling for standard Chart.js axes (opens new window).