Skip to main content
The Visual Map component provides visual encoding for data by mapping values to visual properties such as color, symbol size, and opacity. It comes in two types: continuous and piecewise.

​
Purpose

Visual Map enables data-driven visual encoding, allowing you to represent data magnitude through colors, sizes, or other visual channels. Based on ~/workspace/source/src/component/visualMap/VisualMapModel.ts, it supports both continuous gradients and discrete categorical mappings.

​
Types

ECharts provides two types of Visual Map components:
  1. Continuous: Maps data to a continuous color gradient or size range
  2. Piecewise: Divides data into discrete pieces with distinct visual properties

​
Basic Usage

​
Continuous Visual Map

option = {
  visualMap: {
    type: 'continuous',
    min: 0,
    max: 100,
    inRange: {
      color: ['#50a3ba', '#eac736', '#d94e5d']
    }
  },
  series: [{
    type: 'scatter',
    data: [[10, 20, 30], [15, 25, 35]]
  }]
}

​
Piecewise Visual Map

option = {
  visualMap: {
    type: 'piecewise',
    pieces: [
      {min: 0, max: 20, label: 'Low', color: '#50a3ba'},
      {min: 20, max: 40, label: 'Medium', color: '#eac736'},
      {min: 40, max: 100, label: 'High', color: '#d94e5d'}
    ]
  }
}

​
Common Configuration

​
type
'continuous' | 'piecewise'
Type of the visual map component.
​
show
boolean
default:"true"
Whether to display the visual map component.
​
min
number
default:"0"
Minimum value for the visual mapping range.
​
max
number
default:"200"
Maximum value for the visual mapping range.
​
dimension
number
Specifies which dimension of the data to map. If not specified, the last dimension is used.
visualMap: {
  dimension: 2,  // Map the third dimension (0-indexed)
  min: 0,
  max: 100
}
​
seriesIndex
number | number[] | 'all'
Specifies which series the visual map applies to. Can be a single index, array of indices, or ‘all’.
visualMap: {
  seriesIndex: [0, 2],  // Apply to first and third series
  min: 0,
  max: 100
}
​
seriesTargets
object[]
Advanced option for targeting specific dimensions in specific series.
visualMap: {
  seriesTargets: [
    {seriesIndex: 0, dimension: 2},
    {seriesId: 'sales', dimension: 1}
  ]
}
​
inRange
object
Visual properties for data within the selected range.
inRange: {
  color: ['#121122', '#d94e5d'],
  symbolSize: [10, 50],
  opacity: [0.4, 1]
}
​
outOfRange
object
Visual properties for data outside the selected range.
outOfRange: {
  color: '#ddd',
  symbolSize: 5
}
​
orient
'vertical' | 'horizontal'
default:"'vertical'"
Orientation of the visual map component.
​
inverse
boolean
default:"false"
Whether to inverse the component.
​
precision
number
default:"0"
Number of decimal places for displayed values.
​
itemWidth
number
Width of the visual map item in pixels.
​
itemHeight
number
Height of the visual map item in pixels.
​
text
string[]
Text labels for both ends of the visual map, such as ['High', 'Low'].
visualMap: {
  text: ['High', 'Low'],
  min: 0,
  max: 100
}
​
textGap
number
default:"10"
Gap between text and the visual map item.
​
formatter
string | function
Formatter for the label text. Can be a template string or function.
// Template string
formatter: '{value} units'

// Function
formatter: function(value) {
  return value.toFixed(2) + ' kg';
}

​
Position

​
left
number | string
default:"0"
Distance from the left side of the container.
​
top
number | string
Distance from the top of the container.
​
right
number | string
Distance from the right side of the container.
​
bottom
number | string
default:"0"
Distance from the bottom of the container.
​
padding
number | number[]
Padding inside the component. Can be a single number or array [top, right, bottom, left].

​
Continuous Visual Map

From ~/workspace/source/src/component/visualMap/ContinuousModel.ts, continuous visual maps provide smooth gradients.
​
range
number[]
Selected range for continuous visual map, defaults to [min, max].
visualMap: {
  type: 'continuous',
  min: 0,
  max: 100,
  range: [20, 80]  // Only show data between 20 and 80
}
​
calculable
boolean
default:"false"
Whether to show handles to allow interactive range adjustment.
​
realtime
boolean
default:"true"
Whether to update the chart in real-time while dragging handles.
​
hoverLink
boolean
default:"true"
Whether to enable hover highlighting of data related to the hovered visual map item.
​
unboundedRange
boolean
default:"true"
When range touches min or max, whether to treat it as unbounded:
  • true: range[0] <= min becomes [-Infinity, range[1]]
  • false: Range is strictly bounded
​
handleIcon
string
SVG path for the handle icon.
​
handleSize
string | number
default:"'120%'"
Size of the handle, can be a percentage of item width.
​
handleStyle
object
Style configuration for the handles.

​
Piecewise Visual Map

From ~/workspace/source/src/component/visualMap/PiecewiseModel.ts, piecewise visual maps divide data into discrete ranges.
​
pieces
object[]
Array of piece definitions. Each piece can define a range and visual properties.
pieces: [
  {min: 0, max: 20, label: 'Low', color: '#50a3ba'},
  {min: 20, max: 40, label: 'Medium', color: '#eac736'},
  {gt: 40, label: 'High', color: '#d94e5d'}
]
​
categories
string[]
Category names for categorical data mapping.
visualMap: {
  type: 'piecewise',
  categories: ['Type A', 'Type B', 'Type C'],
  inRange: {
    color: ['#d94e5d', '#eac736', '#50a3ba']
  }
}
​
splitNumber
number
default:"5"
When pieces are not specified, split the data range into this many equal pieces.
​
selected
object
Which pieces are selected. Object keys are piece indices or category names.
selected: {
  '0': true,
  '1': false,
  '2': true
}
​
selectedMode
'multiple' | 'single' | boolean
default:"'multiple'"
Selection mode:
  • 'multiple': Allow multiple pieces to be selected
  • 'single': Only one piece can be selected at a time
  • false: Disable selection
​
itemSymbol
string
default:"'roundRect'"
Symbol shape for piecewise items.
​
itemGap
number
default:"10"
Gap between items in pixels.
​
hoverLink
boolean
default:"true"
Whether to enable hover highlighting.

​
Examples

​
Heatmap with Continuous Visual Map

option = {
  visualMap: {
    type: 'continuous',
    min: 0,
    max: 100,
    calculable: true,
    orient: 'horizontal',
    left: 'center',
    bottom: '15%',
    inRange: {
      color: ['#313695', '#4575b4', '#74add1', '#abd9e9', '#e0f3f8',
              '#ffffbf', '#fee090', '#fdae61', '#f46d43', '#d73027', '#a50026']
    }
  },
  series: [{
    type: 'heatmap',
    data: [[0, 0, 50], [0, 1, 75], [1, 0, 25]]
  }]
}

​
Scatter Plot with Piecewise Visual Map

option = {
  visualMap: {
    type: 'piecewise',
    dimension: 2,
    pieces: [
      {min: 0, max: 10, label: 'Small', color: '#93CE07'},
      {min: 10, max: 30, label: 'Medium', color: '#FBDB0F'},
      {min: 30, max: 50, label: 'Large', color: '#FC7D02'},
      {min: 50, max: 100, label: 'Extra Large', color: '#FD0100'}
    ],
    orient: 'vertical',
    left: 'right',
    top: 'center'
  },
  series: [{
    type: 'scatter',
    data: [[10, 20, 15], [15, 25, 45], [20, 30, 8]]
  }]
}

​
Multiple Series with Series Targets

option = {
  visualMap: {
    type: 'continuous',
    min: 0,
    max: 100,
    seriesTargets: [
      {seriesIndex: 0, dimension: 2},  // First series, third dimension
      {seriesIndex: 1, dimension: 1}   // Second series, second dimension
    ],
    inRange: {
      color: ['#50a3ba', '#eac736', '#d94e5d']
    }
  },
  series: [
    {type: 'scatter', data: [[1, 2, 30], [3, 4, 60]]},
    {type: 'scatter', data: [[5, 70], [7, 40]]}
  ]
}

​
Implementation Details

From ~/workspace/source/src/component/visualMap/VisualMapModel.ts:179-700, the Visual Map component:
  • Dependencies: Requires series components to function
  • Visual Properties: Supports color, symbolSize, opacity, and other visual channels
  • Data Extent: Automatically calculates from specified min/max values
  • Target Selection: Can target specific series and dimensions
  • State Management: Maintains inRange and outOfRange visual states
  • Interactive: Supports selection and hover interactions

Build docs developers (and LLMs) love

Get started for freeTalk to us