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.
If axis[].tick.maxSpacing
is provided, the axis ticks and labels will update with 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,
}
}
If a range or ratio is specified, double-click to reset will reset to the initial range or ratio specified.
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 step.
- Pan right: Pans the chart to the right by one step.
- Reset: Resets the zoom to the original level and position. Equivalent to Double-Click to Reset.
Customisation
It is possible to customise the visibility, order and grouping of buttons, as well as modifying the icon, label text and tooltip for each.
zoom: {
buttons: {
buttons: [
{
icon: 'zoom-in',
tooltip: 'Decrease Visible Range',
value: 'zoom-in',
label: 'In',
section: 'zoom'
},
{
icon: 'zoom-out',
tooltip: 'Increase Visible Range',
value: 'zoom-out',
label: 'Out',
section: 'zoom'
},
{
icon: 'pan-start',
tooltip: 'Pan to Start',
value: 'pan-start',
section: 'pan'
},
{
icon: 'pan-end',
tooltip: 'Pan to End',
value: 'pan-end',
section: 'pan'
},
{
tooltip: 'Undo all Zoom',
value: 'reset',
label: 'Reset',
section: '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.
The windowStart
and windowEnd
parameters will be undefined
if the chart does not have a time axis. They will also be undefined
on the first call to dataSource.getData()
if no axis[].min
and axis[].max
are provided on the time axis.