# How to Configure and Use the VisualMap Component in ECharts: Complete Guide with Examples

> Learn to configure and use the VisualMap component in ECharts. Map data to visual styles for continuous gradients or discrete categories with this complete guide.

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

---

**The VisualMap component in ECharts maps data values to visual styles using either continuous gradients or discrete piecewise categories, configured via the `visualMap` option with `type: 'continuous'` or `type: 'piecewise'`.**

Apache ECharts provides a powerful **VisualMap component** that transforms raw data values into visual properties like color, size, and opacity. This feature enables interactive data exploration by allowing users to filter and highlight specific value ranges directly on the chart. Whether you're building heatmaps, scatter plots, or choropleth maps, understanding how to configure the VisualMap component in ECharts is essential for creating intuitive data visualizations.

## VisualMap Types: Continuous vs Piecewise

ECharts implements two distinct modes for the VisualMap component, each registered automatically by the core extension loader in [`src/component/visualMap.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMap.ts) via `use(install)`.

### Continuous VisualMap

The **continuous** mode creates a gradient slider that maps a numeric range to a spectrum of visual values. According to the source code in [`src/component/visualMapContinuous.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMapContinuous.ts), this mode uses the `installVisualMapContinuous` function to register a model that handles linear interpolations between visual states. It is ideal for representing continuous data distributions such as temperature gradients, elevation maps, or density plots.

### Piecewise VisualMap

The **piecewise** mode, defined in [`src/component/visualMapPiecewise.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMapPiecewise.ts), divides data into discrete intervals or categories using the `installVisualMapPiecewise` registration. This approach works best for classified data such as risk levels (low, medium, high) or performance tiers, rendering distinct color blocks rather than a gradient slider.

## Essential Configuration Options

All VisualMap behavior is governed by `VisualMapModel` (referenced in [`src/component/visualMap/visualMapAction.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMap/visualMapAction.ts)), which parses these key configuration properties:

| Option | Description | Example |
|--------|-------------|---------|
| `type` | Mode selection: `"continuous"` or `"piecewise"` | `"continuous"` |
| `min` / `max` | Data range boundaries | `0`, `100` |
| `dimension` | Which data array index to map (0 = first column) | `2` |
| `range` | Initial selected sub-range | `[10, 80]` |
| `inRange` | Visual properties inside the range | `{color: ['#ff0000', '#00ff00']}` |
| `outOfRange` | Visual properties outside the range | `{color: '#ccc'}` |
| `calculable` | Enables draggable handles for filtering | `true` |
| `orient` | Layout direction | `"horizontal"` or `"vertical"` |
| `pieces` | Interval definitions (piecewise only) | `[{min:0, max:10, color:'#f00'}]` |

The `inRange` object supports multiple visual channels including `color`, `symbolSize`, `opacity`, `colorSaturation`, and `colorAlpha`, allowing multidimensional visual encoding.

## Internal Architecture and Source Code

Understanding the internal flow helps customize behavior beyond standard options:

1. **Registration**: [`src/component/visualMap.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMap.ts) imports the install function from [`src/component/visualMap/install.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMap/install.ts), which calls both `use(installVisualMapContinuous)` and `use(installVisualMapPiecewise)` to register the sub-components.

2. **Model Instantiation**: Each `visualMap` configuration creates a `VisualMapModel` instance that parses options and builds mapping functions. The model's `mapValueToVisual` method transforms data values into visual properties before rendering.

3. **Action Handling**: User interactions trigger actions defined in [`src/component/visualMap/visualMapAction.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMap/visualMapAction.ts). The `visualMapActionInfo` object defines the `selectDataRange` action, handled by `visualMapActionHander` to support programmatic range selection (brushing).

4. **Data Binding**: When a series specifies `visualMap: {dimension: 2}`, the series data is passed to the model's mapping function, which applies the configured visual transformations during the rendering cycle.

## Practical Implementation Examples

### Continuous VisualMap for Scatter Plots

This example maps the third data dimension to a color gradient with a draggable filter:

```javascript
const chart = echarts.init(document.getElementById('main'));

const data = Array.from({length: 200}, () => [
    Math.random() * 100,    // x
    Math.random() * 100,    // y  
    Math.random() * 500     // value (mapped to color)
]);

chart.setOption({
    xAxis: {type: 'value'},
    yAxis: {type: 'value'},
    visualMap: {
        type: 'continuous',
        dimension: 2,              // Map the 3rd column
        min: 0,
        max: 500,
        calculable: true,          // Show draggable handles
        orient: 'horizontal',
        left: 'center',
        bottom: 20,
        inRange: {
            color: ['#313695', '#74add1', '#fdae61', '#d73027']
        },
        outOfRange: {color: '#eee'},
        text: ['High', 'Low']
    },
    series: [{
        type: 'scatter',
        data: data,
        symbolSize: 12
    }]
});

```

### Piecewise VisualMap for Categorical Data

Configure discrete intervals with custom labels and multiple selection:

```javascript
visualMap: {
    type: 'piecewise',
    dimension: 0,                  // Map x-axis values
    pieces: [
        {min: 0, max: 30, color: '#ff7f0e', label: 'Low'},
        {min: 30, max: 70, color: '#2ca02c', label: 'Medium'},
        {min: 70, max: 100, color: '#1f77b4', label: 'High'}
    ],
    selectedMode: 'multiple',      // Allow multiple selections
    show: true,
    left: 'right',
    top: 'center'
}

```

This creates a legend-style interface where clicking a category toggles the visibility of its corresponding data range.

## Summary

- **The VisualMap component in ECharts** provides two modes: `continuous` for gradient mappings and `piecewise` for discrete categories, both registered via [`src/component/visualMap/install.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMap/install.ts).
- **Core configuration** requires defining `min`/`max` boundaries, the target `dimension`, and visual mappings via `inRange` and `outOfRange`.
- **Interactivity** is controlled by the `calculable` property (for draggable sliders) and `selectedMode` (for piecewise selection).
- **Internal processing** flows through `VisualMapModel` for value-to-visual translation and [`visualMapAction.ts`](https://github.com/apache/echarts/blob/main/visualMapAction.ts) for handling range selection events.
- **File references**: [`src/component/visualMapContinuous.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMapContinuous.ts), [`src/component/visualMapPiecewise.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMapPiecewise.ts), and [`src/component/visualMap/visualMapAction.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMap/visualMapAction.ts) contain the implementation details for extending functionality.

## Frequently Asked Questions

### What is the difference between continuous and piecewise VisualMap?

**Continuous VisualMap** renders a gradient slider suitable for continuous numeric data like temperature or population density, while **piecewise VisualMap** displays discrete color blocks for categorized data like risk levels or age groups. The continuous mode interpolates values between colors, whereas piecewise applies specific styles to defined intervals using the `pieces` array.

### How do I bind VisualMap to a specific data dimension?

Set the `dimension` property to the zero-based index of your data array. For example, `dimension: 2` maps the third value in each data point `[x, y, value]`. According to the `VisualMapModel` implementation, this index determines which column is passed to the `mapValueToVisual` function for styling.

### Can I use multiple VisualMap components in one chart?

Yes, ECharts supports multiple VisualMap instances by providing an array under the `visualMap` option. Each component can target different dimensions or series, allowing complex visual encodings such as mapping one dimension to color and another to symbol size simultaneously.

### How do I programmatically update the selected range?

Dispatch the `selectDataRange` action using `chart.dispatchAction()`, referencing the specific `visualMap` component by index. The action handler in [`src/component/visualMap/visualMapAction.ts`](https://github.com/apache/echarts/blob/main/src/component/visualMap/visualMapAction.ts) processes these events, updating the model's `range` property and triggering a view refresh without requiring a full `setOption` call.