Skip to main content
The Brush component enables users to select data ranges by drawing selection areas directly on the chart, supporting multiple selection shapes and interaction modes.

​
Purpose

Based on the source implementation in ~/workspace/source/src/component/brush/BrushModel.ts, the brush component:
  • Allows interactive selection of data regions
  • Supports multiple brush types: rectangle, polygon, line
  • Provides visual feedback for selected and unselected data
  • Enables linked brushing across multiple charts
  • Supports single or multiple selection areas
  • Can be used with toolbox for brush mode activation

​
Basic Usage

option = {
  brush: {
    toolbox: ['rect', 'polygon', 'clear'],
    xAxisIndex: 0
  },
  xAxis: { type: 'category', data: ['A', 'B', 'C', 'D', 'E'] },
  yAxis: { type: 'value' },
  series: [{
    type: 'scatter',
    data: [[0, 10], [1, 20], [2, 15], [3, 25], [4, 18]]
  }]
};

​
Rectangle Brush

option = {
  brush: {
    brushType: 'rect',
    brushMode: 'single',
    transformable: true
  },
  xAxis: { type: 'value' },
  yAxis: { type: 'value' },
  series: [{
    type: 'scatter',
    data: [[10, 20], [15, 25], [20, 30], [25, 35]]
  }]
};

​
Multiple Selection Mode

option = {
  brush: {
    brushType: 'rect',
    brushMode: 'multiple',
    brushStyle: {
      borderWidth: 1,
      color: 'rgba(120, 140, 180, 0.3)',
      borderColor: 'rgba(120, 140, 180, 0.8)'
    },
    removeOnClick: true
  },
  series: [{
    type: 'scatter',
    data: [[1, 2], [2, 3], [3, 4], [4, 5]]
  }]
};

​
Visual Encoding for Selection

option = {
  brush: {
    brushType: 'rect',
    inBrush: {
      opacity: 1,
      liftZ: 5
    },
    outOfBrush: {
      color: '#ddd',
      opacity: 0.4
    }
  },
  series: [{
    type: 'scatter',
    data: [[10, 20], [15, 25], [20, 30]],
    itemStyle: { color: '#c23531' }
  }]
};

​
Linked Brushing

option = {
  brush: {
    brushLink: 'all',  // Link all series
    brushMode: 'single'
  },
  series: [
    {
      type: 'scatter',
      data: [[1, 2], [2, 3], [3, 4]]
    },
    {
      type: 'scatter',
      data: [[5, 6], [6, 7], [7, 8]]
    }
  ]
};

​
Configuration Options

From ~/workspace/source/src/component/brush/BrushModel.ts:

​
Brush Type and Mode

​
brushType
'rect' | 'polygon' | 'lineX' | 'lineY'
default:"'rect'"
Type of brush shape:
  • 'rect': Rectangle selection
  • 'polygon': Polygon selection (click to add points, double-click to complete)
  • 'lineX': Horizontal line selection
  • 'lineY': Vertical line selection
From BrushModel.ts:138.
​
brushMode
'single' | 'multiple'
default:"'single'"
Selection mode:
  • 'single': Only one brush area allowed
  • 'multiple': Multiple brush areas can coexist
From BrushModel.ts:139.
​
transformable
boolean
default:"true"
Whether brush areas can be transformed (moved, resized) after creation.From BrushModel.ts:140.
​
removeOnClick
boolean
default:"true"
Whether to remove brush area on click when it’s already selected.From BrushModel.ts:148.

​
Target Configuration

​
seriesIndex
number | number[] | 'all' | 'none'
default:"'all'"
Indices of series to apply brush to:
  • 'all': Apply to all series
  • 'none' / null / undefined: No series
  • Number or array: Specific series indices
From BrushModel.ts:137.
​
xAxisIndex
number | number[]
X-axis indices for coordinate-based brushing.
​
yAxisIndex
number | number[]
Y-axis indices for coordinate-based brushing.
​
geoIndex
number | number[]
Geo component indices for geographic brushing.

​
Brush Styling

​
brushStyle
object
Style configuration for brush selection areas. From BrushModel.ts:141-145:
brushStyle: {
  borderWidth: 1,
  color: tokens.color.backgroundTint,
  borderColor: tokens.color.borderTint
}
​
brushStyle.borderWidth
number
default:"1"
Width of brush area border.
​
brushStyle.color
ZRColor
default:"tokens.color.backgroundTint"
Fill color of brush selection area. From BrushModel.ts:143.
​
brushStyle.borderColor
ZRColor
default:"tokens.color.borderTint"
Border color of brush selection area. From BrushModel.ts:144.

​
Visual Encoding

​
inBrush
object
Visual properties for data items inside brush selection.Default includes liftZ: 5 to elevate selected items. From BrushModel.ts:183-191:
inBrush: {
  opacity: 1,
  liftZ: 5,
  color: '#c23531'
}
​
outOfBrush
object
Visual properties for data items outside brush selection.Default color from BrushModel.ts:150 and initialization at BrushModel.ts:185:
outOfBrush: {
  color: tokens.color.disabled,
  opacity: 0.4
}

​
Throttling

​
throttleType
'fixRate' | 'debounce'
default:"'fixRate'"
Throttle type for brush events:
  • 'fixRate': Fixed rate throttling
  • 'debounce': Debounced updates
Only valid in the first brush component. From BrushModel.ts:146.
​
throttleDelay
number
default:"0"
Throttle delay in milliseconds. 0 means every event is triggered.From BrushModel.ts:147.

​
Linked Brushing

​
brushLink
number[] | 'all' | 'none'
Series indices to link together for coordinated brushing:
  • 'all': All series are linked
  • 'none' / null / undefined: No linking
  • Array: Specific series indices to link
When series are linked, brushing one will highlight corresponding data in others.From BrushModel.ts:100.

​
Toolbox Integration

​
toolbox
array
Brush types to show in toolbox:
toolbox: ['rect', 'polygon', 'lineX', 'lineY', 'keep', 'clear']
Where:
  • 'rect', 'polygon', 'lineX', 'lineY': Brush type buttons
  • 'keep': Keep selection mode
  • 'clear': Clear all selections
From BrushModel.ts:96.

​
Z-Index

​
z
number
default:"10000"
Z-index for brush components. High value ensures brush appears above other elements.From BrushModel.ts:149.

​
Brush Areas

The brush component maintains an internal array of brush areas (from BrushModel.ts:156). Each area includes:
  • brushType: Shape of the selection
  • range: Selected range in pixel/data coordinates
  • panelId: ID of the coordinate system panel
  • Styling properties inherited from brush options

​
Methods

The BrushModel provides methods for programmatic control:

​
setAreas(areas)

Set brush selection areas programmatically. From BrushModel.ts:197-215: 
myChart.dispatchAction({
  type: 'brush',
  areas: [
    {
      brushType: 'rect',
      coordRange: [[10, 20], [30, 40]],
      xAxisIndex: 0
    }
  ]
});

​
setBrushOption(brushOption)

Set current brush painting options. From BrushModel.ts:220-223.

​
Events

Brush component triggers events that can be listened to: 
myChart.on('brushSelected', function(params) {
  console.log('Brush areas:', params.areas);
  console.log('Selected data:', params.batch);
});

myChart.on('brushEnd', function(params) {
  console.log('Brush completed');
});

​
Advanced Example: Multi-Chart Linked Brushing

option = {
  brush: {
    brushLink: [0, 1],
    brushType: 'rect',
    brushMode: 'single',
    transformable: true,
    brushStyle: {
      borderWidth: 2,
      color: 'rgba(120, 140, 180, 0.2)',
      borderColor: 'rgba(120, 140, 180, 0.8)'
    },
    inBrush: {
      opacity: 1,
      liftZ: 5
    },
    outOfBrush: {
      color: '#ddd',
      opacity: 0.3
    },
    throttleType: 'fixRate',
    throttleDelay: 0,
    removeOnClick: true,
    z: 10000
  },
  grid: [
    { left: '5%', right: '50%', top: '10%', height: '35%' },
    { left: '5%', right: '50%', top: '55%', height: '35%' }
  ],
  xAxis: [
    { type: 'value', gridIndex: 0 },
    { type: 'value', gridIndex: 1 }
  ],
  yAxis: [
    { type: 'value', gridIndex: 0 },
    { type: 'value', gridIndex: 1 }
  ],
  series: [
    {
      type: 'scatter',
      xAxisIndex: 0,
      yAxisIndex: 0,
      data: [[10, 20], [15, 25], [20, 30], [25, 35]],
      itemStyle: { color: '#c23531' }
    },
    {
      type: 'scatter',
      xAxisIndex: 1,
      yAxisIndex: 1,
      data: [[10, 20], [15, 25], [20, 30], [25, 35]],
      itemStyle: { color: '#2f4554' }
    }
  ]
};

myChart.on('brushSelected', function(params) {
  const selected = params.batch[0].selected;
  console.log('Selected data indices:', selected);
});

​
Use Cases

  1. Data Exploration: Select and highlight specific data ranges for detailed analysis
  2. Outlier Detection: Identify and select outlier data points
  3. Cross-Filtering: Link multiple charts to filter data across visualizations
  4. Region Selection: Select geographic regions on map charts
  5. Time Range Selection: Select time periods on time-series charts

Build docs developers (and LLMs) love

Get started for freeTalk to us