React ChartsZoom

ReactAngularVueJavascript

Enterprise

AG Charts allows zooming into charts, making it easier to navigate large datasets.

To enable this feature, set zoom.enabled to true.

zoom: {
    enabled: true,
}

In the above example you can:

• Scroll in and out with the mouse wheel or trackpad.
• Click and drag to pan around the zoomed in chart.
• Click and drag an axis to zoom in or out on only that axis.
• Double click anywhere to reset the zoom.

Scrolling

This allows zooming by using the mouse wheel or trackpad, as shown in the above example and is enabled by default. To disable, use enableScrolling: false.

Anchor Point

By default, the chart will zoom while keeping the right side of the x-axis pinned. You can change this anchor point with the anchorPointX and anchorPointY properties, setting them each to one of:

• start, the left or bottom of the chart when scrolling on the x or y axis respectively,
• middle (default for y-axis), the middle of the chart,
• end (default for x-axis), the right or top of the chart when scrolling on the x or y axis respectively,
• pointer, keep the mouse pointer above the same position on the chart when zooming.

In the example below, we set the anchor point for both axes to the mouse pointer.

zoom: {
    anchorPointX: 'pointer',
    anchorPointY: 'pointer',
}

Scrolling Step

When scrolling, the chart zooms in by a single step for each movement of the scroll wheel or trackpad. By default scrollingStep is set to 0.1, or 10% of the chart each time.

In the example below, we change the step to 0.4.

zoom: {
    scrollingStep: 0.4,
}

Axes

By default, scrolling zoom is only enabled for the x axis. This can be changed by setting the axes property to x, y or xy.

In the example below, we enable zoom on both the x and y axes.

zoom: {
    axes: 'xy',
}

Panning

This is enabled by default and allows users to click and drag to move around a zoomed chart. To disable, use enablePanning: false.

If zoom by selecting is enabled, clicking and dragging will no longer pan by default. Instead the user will need to hold down a key to switch to panning mode.

This key defaults to alt but can be set with the panKey property to one of alt, ctrl, shift or meta (the command key on MacOS or start key on Windows).

In the example below, panning can only be done by holding down the shift key while clicking and dragging.

zoom: {
    panKey: 'shift',
}

Selecting

This method of zooming works by clicking and dragging a box to select an area on the chart. This is disabled by default. To enable, use enableSelecting: true.

In the example below, the user can only zoom in by selection, and can only zoom out by double-click to reset.

zoom: {
    enableAxisDragging: false,
    enablePanning: false,
    enableScrolling: false,
    enableSelecting: true,
}

Dragging an Axis

By default, a user can click and drag on any axis to change the zoom of that axis. This ignores the axes property and is enabled by default for all axes. To disable, use enableAxisDragging: false.

In the example below, we have two series, each attached to a different y-axis. Dragging one of the y-axes will zoom both of them.

Double-Click to Reset

This allows users to reset the zoom by double-clicking in an empty space in the chart area, and is enabled by default. To disable, use enableDoubleClickToReset: false.

Minimum Visible Items

The minVisibleItemsX and minVisibleItemsY options can be used to limit how far a user can zoom in to the chart, helping to prevent them from getting lost in a blank space of the chart. These options set the minimum number of items visible on each axis, for example the number of bars in a bar series or points in a line series. The default for both values is 2.

The example below demonstrates setting minVisibleItemsX to 10, preventing the user from zooming beyond showing a minimum of 10 points on the line.

zoom: {
    minVisibleItemsX: 10,
}

Range

Use the rangeX and rangeY options to set the zoom range. This can be used for when the chart first loads, or updated via the update API at runtime.

The start and end values should be of the same type as the matching axis, for example a Date object on a time axis.

zoom: {
    rangeX: {
        start: new Date('2024-08-01 00:00:00'),
        end: new Date('2024-08-30 23:59:59'),
    },
}

As an alternative to specifying the zoom in terms of range values, you can use ratioX and ratioY to specify it as a ratio of the full chart from 0 to 1.

zoom: {
    ratioX:
    {
      start: 0.8,
      end: 1,
    }
}

Navigator

The zoom functionality can be used together with the Navigator to add a visual reference to the zoom position.

Context Menu

When both the zoom and Context Menu are enabled, additional zoom actions are added into the Context Menu for zooming and panning to the clicked location.

Buttons

Zoom buttons are enabled by default. These will appear when the mouse is hovered near the bottom of a chart which has zoom enabled. To disable, use zoom.buttons.enabled: false.

Hover near the bottom of the above example to see the default zoom buttons.

• Zoom out: Zooms the chart out by one step.
• Zoom in: Zooms the chart in by one step.
• Pan left: Pans the chart to the left by one viewport width.
• Pan right: Pans the chart to the right by one viewport width.
• Reset: Resets the zoom to the original level and position. Equivalent to Double-Click to Reset.

Customisation

It is possible to customise the visibility and order of buttons, as well as modifying the icon, label text and tooltip for each.

zoom: {
    buttons: {
        buttons: [
        {
            icon: 'pan-start',
            tooltip: 'Pan to Start',
            value: 'pan-start',
        },
        {
            icon: 'zoom-in',
            tooltip: 'Decrease Visible Range',
            value: 'zoom-in',
            label: 'In',
        },
        {
            icon: 'zoom-out',
            tooltip: 'Increase Visible Range',
            value: 'zoom-out',
            label: 'Out',
        },
        {
            icon: 'pan-end',
            tooltip: 'Pan to End',
            value: 'pan-end',
        },
        {
            tooltip: 'Undo all Zoom',
            value: 'reset',
            label: 'Reset',
        },
        ],
    }
}

In the above example:

• The pan-left and pan-right buttons are not shown.
• Additional buttons are added to enable panning to the start and end of the x-axis.
• All the buttons have custom tooltip text.
• The order of the zoom-in and zoom-out buttons is swapped and they have a label as well as an icon.
• The reset button has only a label and no icon.

For more information see the API Reference section.

Asynchronous Loading

Use the dataSource option to asynchronously load in new data as the chart is zoomed.

dataSource: {
    getData: ({ windowStart, windowEnd }) => {
        return FakeServer.get(windowStart, windowEnd);
    },
}

In this example, the getData function returns both the coarse data plus additional finer grained data for the visible time window.

The data returned from the getData function should always include the coarse data set to ensure the chart knows the full extent of the data.

API Reference