# 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
, 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).