D3 provides a module that adds zoom and pan behaviour to an HTML or SVG element. In the following example, click and move the mouse to pan and use the mouse wheel to zoom. Touch gestures should also work:
When zoom and pan gestures (such as dragging or a pinch gesture) occur, a transform (consisting of scale and translate) is computed by D3 and passed into an event handler. The event handler typically applies the transform to chart elements.
There’s three steps to add zoom and pan behaviour to an element:
d3.zoom()to create a zoom behaviour function
- add an event handler that gets called when a zoom or pan event occurs. The event handler receives a transform which can be applied to chart elements
- attach the zoom behaviour to an element that receives the zoom and pan gestures
It’s helpful to distinguish between the HTML or SVG element that receives the zoom and pan gestures and the elements that get zoomed and panned (the elements that get transformed). It’s important that these elements are different, otherwise the panning won’t work properly.
d3.zoom() creates a zoom behaviour:
Although it’s called
d3.zoom, this module handles zoom and pan events.
A zoom behaviour is a function that adds event handlers (for drags, mouse wheel events and touch events etc.) to an element. It also has methods such as
.ondefined on it.
You can attach an event handler to your zoom behaviour by calling the
.on method. This accepts two arguments:
- the event type (
- the name of your event handler function
The event types are
'zoom'indicates a change of transform (e.g. the user has zoomed or panned).
'start'indicates the start of the zoom or pan (e.g. the user has pressed the mouse button).
'end'indicates the end of the zoom or pan (e.g. the user has released the mouse button).
handleZoom receives a single parameter
e which is an object representing the zoom event. The most useful property on this object is
transform. This is an object that represents the latest zoom transform and is typically applied to the chart element(s):
e.transformhas three properties
yspecify the translate transform and
krepresents the scale factor. It also has a
.toStringmethod which generates a string such as
"translate(38.9,-4.1) scale(1.3)". This means you can pass
You attach the zoom behaviour to an element by selecting the element and passing the zoom behaviour into the
The zoom behaviour is a function that sets up event listeners on the selected element (
svgin the above example). When zoom and pan events occur, a transform is computed and passed into the event handler (
handleZoomin the above examples).
Suppose you have an SVG element that contains a
In the following code a zoom behaviour is created using
d3.zoom() and attached to the
handleZoom is passed into the
.on method. When a zoom or pan occurs,
handleZoom gets called. This applies the transform
e.transform to the
Here’s a full example where an array of random coordinates is joined to
Use the mouse wheel and dragging, or touch gestures, to zoom and pan the circles:
Zoom and pan constraints
You can constrain the zoom and pan so that the user can only zoom and pan within specified bounds.
The zoom can be constrained using
.scaleExtent into which you pass an array
[min, max] where
min is the minimum scale factor and
max is the maximum scale factor:
You can use
.translateExtent to specify bounds
[[x0, y0], [x1, y1]] that the user can’t pan outside of:
Now you can only zoom in up to a scale factor of 5. Neither can you zoom out beyond the default scale factor of 1. In addition you cannot pan beyond the bounds of the chart:
Programmatic zoom control
You can also zoom and pan programmatically. For example you can create buttons that zoom the chart when clicked.
The zoom behaviour has the following methods for setting the zoom and pan programmatically:
|adds a given |
|sets the transform such that a given |
|multiplies the current scale factor by a given value|
|sets the scale factor to a given value|
|sets the transform to a given transform. (Use |
The above methods shouldn’t be called directly. Instead, they should be called on the element that receives the zoom and pan gestures. For example:
You can also call these methods on a transition selection, which results in nice effects:
Here’s a full example using a few of the above methods: