Skip to content
amCharts 4

Handling axis zoom events via API

Any axis in amCharts 4 can be zoomed. And sometimes we need to know when that happens, as well as the range of the new zoom. This tutorial will walk through all the necessary information to make that happen.

This works a bit differently on different axis types, so we’ll explore them separately.

Catching zoom event

Section titled “Catching zoom event”

Whenever a an axis is zoomed - either via scrollbar, cursor, automatically - depending on which of the selection ends changed the following events are invoked: "startchanged" and/or "endchanged".

Please note that they might be invoked both.

All we have to do to catch such events is attach a handler function to this event.

dateAxis.events.on("startchanged", dateAxisChanged);dateAxis.events.on("endchanged", dateAxisChanged);function dateAxisChanged(ev) {  console.log("DateAxis zoomed!");}

Of course, just knowing that zoom/pan happened is not very useful in itself. We also need to know the actual range of the new selection. That’s what we’re going to look into next.

Finding start/end values

Section titled “Finding start/end values”

Finding a new selection/zoom range depends on the type of the axis. Let’s look at each axis type individually.

ValueAxis

Section titled “ValueAxis”

Finding current selection on the ValueAxis is quite easy: we just need to access its minZoomed and maxZoomed properties.

valueAxis.events.on("startchanged", valueAxisZoomed);valueAxis.events.on("endchanged", valueAxisZoomed);function valueAxisZoomed(ev) {  let start = ev.target.minZoomed;  let end = ev.target.maxZoomed;  console.log("New range: " + start + " -- " + end);}

DateAxis

Section titled “DateAxis”

DateAxis is basically ValueAxis operating in timestamps.

This is why we can use its minZoomed and maxZoomed as well: those will hold starting and ending timestamps. All we’ll need to do is to convert those into Date objects:

dateAxis.events.on("startchanged", dateAxisChanged);
dateAxis.events.on("endchanged", dateAxisChanged);
function dateAxisChanged(ev) {
  let start = new Date(ev.target.minZoomed);
  let end = new Date(ev.target.maxZoomed);
  console.log("New range: " + start + " -- " + end);
}

CategoryAxis

Section titled “CategoryAxis”

CategoryAxis is different from other types of axes in that sense that it does not operate in numeric scale, but rather static list of items (categories).

Therefore we’re going to be dealing with relative positions and indexes rather than min/max values.

A CategoryAxis has two properties we’re going to be using: start and end.

Now, those are relative “position” values, indicating position within the whole range, expressed in values from 0 (zero) to 1 (one).

For example, when the axis is fully zoomed out, start == 0 and end == 1.

If we’d zoom the axis from its middle to the end, we’d have start == 0.5 and end == 1.

Obviously, knowing relative position is not too useful: we need to know precise categories our zoomed selection starts and ends at.

For that CategoryAxis provides a handy method: getPositionLabel(position).

All we have to do to convert a “position” into “category”, is to pass it through this method:

categoryAxis.events.on("startchanged", categoryAxisZoomed);categoryAxis.events.on("endchanged", categoryAxisZoomed);function categoryAxisZoomed(ev) {  let axis = ev.target;  let start = axis.getPositionLabel(axis.start);  let end = axis.getPositionLabel(axis.end);  console.log("New range: " + start + " -- " + end);}

Examples

Section titled “Examples”

The following example implements zoom events for both ValueAxis and DateAxis (open your browser console before trying it out):

Open in CodePen

And this one deals with a CategroyAxis:

Open in CodePen