Effect Scatter Chart

Overview

Effect scatter charts are an enhanced version of scatter charts that add dynamic visual effects, such as ripple animations, to emphasize important data points. These animated effects are particularly useful for drawing attention to specific data points or creating dynamic, eye-catching visualizations.

When to Use

Use effect scatter charts when you need to:

Highlight important or special data points with animation
Draw user attention to specific events or outliers
Create dynamic visualizations that emphasize temporal or important data
Visualize events on maps (earthquakes, weather events, etc.)
Show real-time data updates with visual emphasis
Add visual interest to scatter plots for presentations

Basic Configuration

The effect scatter chart is configured through the EffectScatterSeriesOption interface, supporting the same coordinate systems as regular scatter charts.

interface EffectScatterSeriesOption {
  type: 'effectScatter'
  coordinateSystem?: string
  showEffectOn?: 'render' | 'emphasis'
  rippleEffect?: {
    period?: number
    scale?: number
    brushType?: 'fill' | 'stroke'
    number?: number
  }
  data?: (EffectScatterDataItemOption | OptionDataValue)[]
  // ... more options
}

Complete Example

import * as echarts from 'echarts';

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

const option = {
  title: {
    text: 'Major Earthquake Locations'
  },
  tooltip: {
    trigger: 'item',
    formatter: '{b}<br/>Magnitude: {c}'
  },
  xAxis: {
    type: 'value',
    name: 'Longitude',
    min: -180,
    max: 180
  },
  yAxis: {
    type: 'value',
    name: 'Latitude',
    min: -90,
    max: 90
  },
  series: [
    {
      name: 'Earthquakes',
      type: 'effectScatter',
      coordinateSystem: 'cartesian2d',
      data: [
        { name: 'Location A', value: [120.5, 35.2, 7.5] },
        { name: 'Location B', value: [-118.3, 34.0, 6.8] },
        { name: 'Location C', value: [139.7, 35.7, 7.2] }
      ],
      symbolSize: function(val) {
        return val[2] * 4; // Size based on magnitude
      },
      showEffectOn: 'render',
      rippleEffect: {
        period: 4,
        scale: 3,
        brushType: 'stroke',
        number: 2
      },
      itemStyle: {
        color: '#f00',
        shadowBlur: 10,
        shadowColor: 'rgba(255, 0, 0, 0.5)'
      },
      emphasis: {
        scale: true
      }
    }
  ]
};

chart.setOption(option);

Key Options

showEffectOn

'render' | 'emphasis'

default:"'render'"

Controls when the ripple effect is displayed:

'render': Show effect continuously from initial render
'emphasis': Show effect only when hovering over the data point

showEffectOn: 'render'  // Continuous animation
showEffectOn: 'emphasis'  // Animation on hover only

rippleEffect

object

Configuration for the ripple animation effect.

rippleEffect: {
  period: 4,        // Duration of one ripple cycle in seconds
  scale: 2.5,       // Maximum scale of the ripple (2.5 = 250%)
  brushType: 'fill', // 'fill' or 'stroke'
  number: 3         // Number of ripples to display
}

rippleEffect.period

number

default:"4"

Duration of a single ripple animation cycle in seconds.

rippleEffect: {
  period: 2  // Faster animation (2 seconds per cycle)
}

rippleEffect.scale

number

default:"2.5"

Maximum scale of the ripple relative to the symbol size. A value of 2.5 means the ripple grows to 250% of the original symbol size.

rippleEffect: {
  scale: 4  // Larger ripple effect
}

rippleEffect.brushType

'fill' | 'stroke'

default:"'fill'"

Rendering style of the ripple:

'fill': Filled ripple circles
'stroke': Outlined ripple circles

rippleEffect: {
  brushType: 'stroke'  // Outlined ripples
}

rippleEffect.number

number

default:"3"

Number of ripple waves to display simultaneously.

rippleEffect: {
  number: 2  // Show 2 ripples at a time
}

coordinateSystem

string

default:"'cartesian2d'"

The coordinate system to use. Effect scatter charts support:

'cartesian2d': 2D rectangular coordinate system (default)
'polar': Polar coordinate system
'geo': Geographic coordinate system
'calendar': Calendar coordinate system
'singleAxis': Single axis

coordinateSystem: 'geo'  // For map visualizations

symbolSize

number | Function

default:"10"

Size of the base symbol. Can be a number or a function for dynamic sizing.

symbolSize: 20

// Dynamic sizing based on data value
symbolSize: function(data) {
  return data[2] * 5;  // Size based on third value
}

itemStyle

ItemStyleOption

Visual style of the scatter points.

itemStyle: {
  color: '#f4e925',
  shadowBlur: 10,
  shadowColor: 'rgba(244, 233, 37, 0.5)'
}

emphasis

object

Visual emphasis configuration for hover states.

emphasis: {
  focus: 'self',
  scale: true  // Scale up on hover
}

Data Format

Effect scatter chart data supports the same formats as regular scatter charts:

// Array of coordinate pairs [x, y]
data: [
  [10, 20],
  [15, 25],
  [20, 30]
]

// Array with additional values for sizing [x, y, size]
data: [
  [10, 20, 5],
  [15, 25, 8],
  [20, 30, 3]
]

// Array of data item objects
data: [
  {
    value: [10, 20],
    name: 'Point A',
    symbolSize: 15,
    rippleEffect: {
      scale: 4,
      period: 3
    }
  },
  {
    value: [15, 25],
    name: 'Point B'
  }
]

Advanced Features

Effect on Hover Only

series: [{
  type: 'effectScatter',
  showEffectOn: 'emphasis',  // Only show ripple on hover
  data: [[10, 20], [15, 25], [20, 30]],
  rippleEffect: {
    scale: 3,
    brushType: 'stroke'
  }
}]

Earthquake Visualization on Map

const option = {
  geo: {
    map: 'world',
    roam: true
  },
  series: [{
    type: 'effectScatter',
    coordinateSystem: 'geo',
    data: [
      { name: 'Tokyo', value: [139.6917, 35.6895, 7.2] },
      { name: 'San Francisco', value: [-122.4194, 37.7749, 6.8] }
    ],
    symbolSize: function(val) {
      return Math.pow(2, val[2]) * 0.5;  // Exponential sizing by magnitude
    },
    showEffectOn: 'render',
    rippleEffect: {
      period: 5,
      scale: 4,
      brushType: 'fill',
      number: 3
    },
    itemStyle: {
      color: function(params) {
        const magnitude = params.value[2];
        return magnitude > 7 ? '#d00' : '#f80';
      },
      shadowBlur: 15
    }
  }]
};

Per-Item Ripple Configuration

series: [{
  type: 'effectScatter',
  data: [
    {
      value: [10, 20],
      rippleEffect: {
        period: 2,
        scale: 5,
        brushType: 'stroke'
      }
    },
    {
      value: [15, 25],
      rippleEffect: {
        period: 6,
        scale: 3,
        brushType: 'fill'
      }
    }
  ]
}]

Real-Time Event Monitoring

let chart = echarts.init(document.getElementById('main'));
let data = [];

function addEvent(x, y, importance) {
  data.push([x, y, importance]);
  if (data.length > 50) data.shift();  // Keep last 50 events
  
  chart.setOption({
    series: [{
      type: 'effectScatter',
      data: data,
      symbolSize: function(val) { return val[2] * 10; },
      rippleEffect: {
        period: 4,
        scale: 3
      }
    }]
  });
}

// Simulate real-time events
setInterval(() => {
  addEvent(
    Math.random() * 100,
    Math.random() * 100,
    Math.random() * 5
  );
}, 2000);

Combining with Regular Scatter

series: [
  {
    name: 'Normal Points',
    type: 'scatter',
    data: [[10, 20], [15, 25], [20, 30]],
    itemStyle: { color: '#999' }
  },
  {
    name: 'Important Points',
    type: 'effectScatter',
    data: [[12, 35], [18, 22]],
    rippleEffect: {
      scale: 4,
      brushType: 'stroke'
    },
    itemStyle: { color: '#f00' }
  }
]

Performance Considerations

Limit ripple effects: Too many animated points can impact performance. Consider using showEffectOn: 'emphasis' for datasets with many points.

Reduce ripple complexity: Use fewer ripples and shorter periods for better performance:

rippleEffect: {
  number: 2,  // Fewer ripples
  period: 3   // Shorter animation
}

Filter important points: For large datasets, use effect scatter only for the most important points:
```
const importantPoints = allData.filter(d => d[2] > threshold);
```

Source Reference

The effect scatter chart implementation can be found in:

Series model: src/chart/effectScatter/EffectScatterSeries.ts:94-156
Type definitions: src/chart/effectScatter/EffectScatterSeries.ts:46-93
Default options: src/chart/effectScatter/EffectScatterSeries.ts:110-155
Ripple effect options: src/chart/effectScatter/EffectScatterSeries.ts:64,90,125-133

Basic Charts

Advanced Charts

Statistical Charts

Special Charts

Overview

When to Use

Basic Configuration

Complete Example

Key Options

Data Format

Advanced Features

Effect on Hover Only

Earthquake Visualization on Map

Per-Item Ripple Configuration

Real-Time Event Monitoring

Combining with Regular Scatter

Performance Considerations

Source Reference

Build docs developers (and LLMs) love

Basic Charts

Advanced Charts

Statistical Charts

Special Charts

Documentation Index

​Overview

​When to Use

​Basic Configuration

​Complete Example

​Key Options

​Data Format

​Advanced Features

​Effect on Hover Only

​Earthquake Visualization on Map

​Per-Item Ripple Configuration

​Real-Time Event Monitoring

​Combining with Regular Scatter

​Performance Considerations

​Source Reference

Build docs developers (and LLMs) love

Overview

When to Use

Basic Configuration

Complete Example

Key Options

Data Format

Advanced Features

Effect on Hover Only

Earthquake Visualization on Map

Per-Item Ripple Configuration

Real-Time Event Monitoring

Combining with Regular Scatter

Performance Considerations

Source Reference