Zooming axis via API / external scrollbar

The XYChart can be zoomed using built-in scrollbar controls or with a chart cursor. This tutorial will show how you can zoom the chart programatically using its API.

Zooming chart via API

The zooming of a chart happens via zooming of a particular axis.

Say we have a DateAxis as chart's X axis. To zoom the chart horizontally, we would zoom out X axis.

There are a number of ways to do that. Some of them are universal, aplicable to all axis types. Some are relative to particular axis types.

Let's look at all of them.

CategoryAxis

CategoryAxis has two built-in methods that allow setting zoom from and to specific categories:

  • zoomToIndexes(start, end) - zooms to categories using their numeric indexes.
  • zoomToCategories(start, end) - zooms to categories using their names.

E.g.:

categoryAxis.zoomToCategories("Marketing", "Human Resources");
categoryAxis.zoomToCategories("Marketing", "Human Resources");

Or we could use indexes of the respective categories:

categoryAxis.zoomToIndexes(1, 3);
categoryAxis.zoomToIndexes(1, 3);

Here's a live chart:

See the Pen amCharts 4: Zooming CategoryAxis via API by amCharts team (@amcharts) on CodePen.24419

DateAxis

Similarly, DateAxis has it's own method that zooms to specific dates:

It takes Date objects as parameters, e.g.:

dateAxis.zoomToDates(
  new Date(2018, 0, 2),
  new Date(2018, 0, 5)
);
dateAxis.zoomToDates(
  new Date(2018, 0, 2),
  new Date(2018, 0, 5)
);

See the Pen amCharts 4: Zooming DateAxis via API by amCharts team (@amcharts) on CodePen.24419

ValueAxis

ValueAxis has own method, too:

The name says it all: it will zoom ValueAxis to specific value range. E.g.:

valueAxis.zoomToValues(250, 750);
valueAxis.zoomToValues(250, 750);

See the Pen amCharts 4: Zooming ValueAxis via API by amCharts team (@amcharts) on CodePen.24419

Relative zooming

So far we've explored type-specific functions that zoom to specific ranges: categories, dates, or values.

Each and every axis in amCharts 4 can also be zoomed relatively. That is to and from percent of its whole range.

For that we do not have methods, but we have two handy properties available in all axes: start and end.

The values accepted there range from 0 (zero) which means start to 1 (one) which means the end of the axis scale.

When chart starts the axis is fully zoomed out: start = 0 and end = 1.

If we'd like to zoom the axis from, say, 25% to 75%, we'd do this:

axis.start = 0.25;
axis.end = 0.75;
axis.start = 0.25;
axis.end = 0.75;

We'll see how this can come in handy when implementing custom chart scrollbars in the last chapter of this tutorial.

To show how it works, let's create an example that has two text fields to update the axis zoom relatively:

See the Pen amCharts 4: Zooming the axis relatively via API by amCharts team (@amcharts) on CodePen.24419

Go ahead, update numbers in those text fields and see how chart zoom reacts.

Custom scrollbars

This leads us to a practical implementation: building a chart with custom scrollbars.

As an illustration, we will be using jQuery UI Slider control.

We won't get into details of how jQuery UI's Slider works. The idea is to set up its handlers that kick in after range is changed, in order to update chart axis' start and end properties.

$( function() {
  $( "#slider-range" ).slider({
    range: true,
    min: 0,
    max: 1,
    step: 0.01,
    values: [ 0, 1 ],
    slide: function( event, ui ) {
      dateAxis.start = ui.values[ 0 ];
      dateAxis.end = ui.values[ 1 ];
    }
  });
} );
$( function() {
  $( "#slider-range" ).slider({
    range: true,
    min: 0,
    max: 1,
    step: 0.01,
    values: [ 0, 1 ],
    slide: function( event, ui ) {
      dateAxis.start = ui.values[ 0 ];
      dateAxis.end = ui.values[ 1 ];
    }
  });
} );

Here's the chart in action:

See the Pen amCharts 4: Using jQuery UI Slider as a chart Scrollbar by amCharts team (@amcharts) on CodePen.24419

Related content