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

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 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, 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, 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), 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 imports the install function from 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. 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:

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:

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.
• 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 for handling range selection events.
• File references: src/component/visualMapContinuous.ts, src/component/visualMapPiecewise.ts, and 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 processes these events, updating the model's range property and triggering a view refresh without requiring a full setOption call.

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