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

> Master ECharts dataZoom for interactive zooming and panning. Learn to use inside and slider controls for intuitive data exploration and chart manipulation.

- Repository: [The Apache Software Foundation/echarts](https://github.com/apache/echarts)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/installDataZoomInside.ts) and [`installDataZoomSlider.ts`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/installCommon.ts) and operates on the normalized model state.

State mutations flow through **dataZoomAction** ([`src/component/dataZoom/dataZoomAction.ts`](https://github.com/apache/echarts/blob/main/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:

```html
<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:

```javascript
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`:

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

```

### Toolbox Integration

Enable the dataZoom toolbox button for rectangular selection zooming:

```javascript
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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/src/component/dataZoom/installDataZoomInside.ts) and [`src/component/dataZoom/InsideZoomView.ts`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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`](https://github.com/apache/echarts/blob/main/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.