How to Use the dataZoom Component for Zooming and Panning in ECharts

The dataZoom component in ECharts enables interactive zooming and panning through two implementations—inside for gesture-based control and slider for visual UI controls—both configured via the dataZoom option array.

The dataZoom component is essential for navigating large datasets in Apache ECharts charts. Whether building responsive dashboards or detailed analytical views, this component provides seamless interaction through mouse, touch, or explicit slider controls with minimal configuration overhead.

Understanding the dataZoom Component Types

ECharts provides two distinct implementations of the dataZoom component, each suited to different interaction patterns.

inside zoom captures gestures directly on the chart canvas. It supports mouse-wheel zooming, pinch-to-zoom on mobile devices, and click-and-drag panning without displaying any visible UI controls. This type is ideal for mobile-first designs or when you want interactions to feel native to the chart surface.

slider zoom renders a dedicated draggable bar—either horizontal or vertical—within the chart grid. This provides explicit visual feedback and precise control, making it preferable for desktop analytics interfaces where users need clear navigation boundaries.

Both types share a common schema defined in DataZoomModel and extend it through InsideZoomModel and SliderZoomModel respectively.

Configuration Options and Model Architecture

The dataZoom component behavior is governed by options defined in src/component/dataZoom/InsideZoomModel.ts, which inherits from the base DataZoomModel class.

Inside Zoom Options

Inside zoom supports fine-grained control over input devices through specific boolean or string options:

• zoomOnMouseWheel – Enables zooming via scroll wheel. Set to true for always-on, or use modifier strings like "shift" to require key presses.
• moveOnMouseWheel – Allows panning with the mouse wheel. Defaults to false in InsideZoomModel but can be set to true or modifier keys like "ctrl".
• zoomLock – When set to true, disables zooming entirely and permits only panning operations.
• preventDefaultMouseMove – Prevents page scrolling while panning inside the chart area.

Default values are established using inheritDefaultOption in InsideZoomModel (lines 54-60), ensuring consistent behavior across instances.

Slider Configuration

Slider-type dataZoom shares the same core options—start, end, xAxisIndex, yAxisIndex—but adds visual styling properties for the draggable handle and background. The registration occurs in src/component/dataZoom/installDataZoomSlider.ts, which pairs the model with its corresponding view class.

Implementation Architecture

The dataZoom component follows ECharts' standard Model-View-Processor architecture, cleanly separating state management from rendering and interaction logic.

Model Registration

Component installation begins with installDataZoomInside.ts and installDataZoomSlider.ts. Both call installCommon to register the shared dataZoomProcessor and action handlers, then register their specific model-view pairs:

• InsideZoomModel extends DataZoomModel with gesture-specific options
• InsideZoomView extends DataZoomView to handle user input

This registration pattern ensures that both zoom types can coexist on the same chart and maintain synchronized state.

View and Interaction Handling

The InsideZoomView class in src/component/dataZoom/InsideZoomView.ts manages the interaction lifecycle. During the render phase, it:

1. Stores the current percentage range (start/end)
2. Instantiates a RoamController to capture mouse, touch, and wheel events
3. Registers three handlers: pan, zoom, and scrollMove

When gestures occur, these handlers compute percentage deltas based on movement direction and axis orientation using getDirectionInfo. The sliderMove utility then clamps the new range, respecting minSpan and maxSpan constraints, before dispatching a dataZoom action to update the model state.

Data Processing and Actions

The dataZoomProcessor (src/component/dataZoom/dataZoomProcessor.ts) runs before each render cycle, adjusting axis min/max values according to the current zoom percentages. This processor is registered via installCommon.ts and operates on the normalized model state.

State mutations flow through dataZoomAction (src/component/dataZoom/dataZoomAction.ts), which listens for dataZoom action dispatches and updates the model's start/end properties. This triggers a reactive view update, ensuring the chart renders the correctly zoomed data range immediately after interaction.

Practical Code Examples

Basic Inside Zoom Setup

Enable mouse-wheel zooming and panning with minimal configuration:

<div id="chart" style="height:400px;"></div>
<script src="https://cdn.jsdelivr.net/npm/echarts@latest/dist/echarts.min.js"></script>
<script>
  const chart = echarts.init(document.getElementById('chart'));

  const option = {
    tooltip: { trigger: 'axis' },
    xAxis: { type: 'category', data: ['Mon','Tue','Wed','Thu','Fri','Sat','Sun'] },
    yAxis: { type: 'value' },
    series: [{ type: 'bar', data: [120,200,150,80,70,110,130] }],
    dataZoom: [{
      type: 'inside',
      start: 0,
      end: 100,
      zoomOnMouseWheel: true,
      moveOnMouseWheel: true,
      zoomLock: false
    }]
  };

  chart.setOption(option);
</script>

Combining Slider and Inside Zoom

Use both visual and gesture controls on the same axis for maximum flexibility:

dataZoom: [
  {
    type: 'slider',
    start: 20,
    end: 80
  },
  {
    type: 'inside',
    xAxisIndex: 0,
    zoomOnMouseWheel: true,
    moveOnMouseWheel: true,
    zoomLock: false,
    start: 20,
    end: 80
  }
]

Both components reference the same underlying DataZoomModel instance, ensuring that dragging the slider updates the inside zoom state and vice versa.

Vertical Axis Zooming

Restrict zooming to the Y-axis only by specifying yAxisIndex:

dataZoom: [{
  type: 'inside',
  yAxisIndex: 0,
  start: 30,
  end: 70,
  zoomOnMouseWheel: true,
  moveOnMouseWheel: true
}]

Toolbox Integration

Enable the dataZoom toolbox button for rectangular selection zooming:

toolbox: {
  feature: {
    dataZoom: {
      yAxisIndex: false
    }
  }
}

The toolbox implementation reuses DataZoomModel and registers a special select sub-type defined in src/component/toolbox/feature/DataZoom.ts.

Summary

• The dataZoom component provides two interaction modes: inside for gesture-based control and slider for visual UI navigation.
• Configuration options like zoomOnMouseWheel, moveOnMouseWheel, and zoomLock are defined in InsideZoomModel.ts and control input handling behavior.
• The architecture separates concerns across DataZoomModel (state), InsideZoomView (interaction), dataZoomProcessor (render preparation), and dataZoomAction (state updates).
• Multiple dataZoom instances can target the same axis and automatically synchronize their percentage ranges through the shared model layer.
• File paths including src/component/dataZoom/installDataZoomInside.ts and src/component/dataZoom/InsideZoomView.ts implement the core registration and gesture handling logic.

Frequently Asked Questions

What is the difference between inside and slider dataZoom types?

The inside type captures mouse-wheel, pinch, and drag gestures directly on the chart area without visible UI elements, while the slider type renders a draggable bar interface for explicit range control. Both share the same underlying DataZoomModel but use different view implementations—InsideZoomView.ts handles gestures via RoamController, whereas the slider view manages DOM-based handles.

How do I prevent the page from scrolling when zooming inside the chart?

Set preventDefaultMouseMove: true in your inside-zoom configuration. This option, processed by the RoamController in InsideZoomView.ts, calls preventDefault() on mouse events to keep focus within the chart boundaries during panning operations.

Can I zoom only the Y-axis while keeping the X-axis static?

Yes. Specify yAxisIndex: 0 (or the appropriate axis index) and omit xAxisIndex in your dataZoom configuration. The processor in dataZoomProcessor.ts will only adjust the minimum and maximum values for the specified axis, leaving other axes at their full data extents.

Why do my slider and inside zoom controls stay synchronized?

Both controls register with the same DataZoomModel instance when targeting the same axis index. When dataZoomAction.ts processes a range change, it updates the model's start and end percentages, triggering a re-render of all views bound to that model. This ensures that dragging the slider updates the inside zoom viewport and vice versa.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}