Documentation Index
Fetch the complete documentation index at: https://mintlify.com/apache/echarts/llms.txt
Use this file to discover all available pages before exploring further.
Migrating from v4 to v5
Apache ECharts v5.0.0 represents a major milestone with significant improvements in performance, rendering, and API design. This guide helps you upgrade from v4 to v5.Overview
ECharts v5 was released with substantial improvements while maintaining backward compatibility for most use cases. The upgrade brings enhanced rendering capabilities, better TypeScript support, and new chart types.Major Changes
Animation System
Animation Delay Callbacks
Version 5 introduced breaking changes to support both series-level and item-level delay withanimationDelay callbacks.
v4 Behavior:
Axis Changes
Axis Tick Value Formatting
The axis formatter now receives tick values directly instead of objects: Before (v4):Axis Break Support
ECharts v5 introduced axis break functionality with proper TypeScript types:Label System Updates
Label Color Inheritance
The legacycolor: 'auto' is maintained for backward compatibility but color: 'inherit' is now preferred:
Legacy (still supported):
Label Layout Properties
Label layout properties were refactored:marginrenamed toedgeDistance- New
minMarginproperty added for better layout control
Line Chart Events
Self-Type Property
Line charts now include aselfType property in trigger events to distinguish between line and area interactions:
State Management
Candlestick Non-Normal States
v5.0.0 initially removed some candlestick state support, which was later restored. Ensure you’re using v5.0.0-rc.3 or later:Deprecated Features
Legacy Grid Breaks with ECharts GL
The v4 grid implementation that worked with ECharts GL had breaking changes. If using 3D visualizations:- Upgrade to ECharts GL v2.x
- Review grid configurations
- Test 3D chart rendering thoroughly
New Features in v5
Enhanced TypeScript Support
Improved type definitions across all chart types and components:Time Axis Improvements
Custom Values with Formatter
Fixed TypeError when usingcustomValues with formatter on time axis:
Parallel Series Extent Calculation
Improved axis extent calculation after processing series extents:Tooltip Improvements
Changing tooltip configuration now properly refreshes displayed tooltips:Migration Steps
Step 1: Update Package
Step 2: Update Axis Formatters
Search for allaxisLabel.formatter functions and update parameter usage:
Step 3: Update Label Colors
Replacecolor: 'auto' with color: 'inherit':
Step 4: Review Label Margins
If usingmargin in label configuration:
Step 5: Test Animation Callbacks
If usinganimationDelay callbacks, verify they work with both series and item-level delays.
Step 6: Update Line Chart Event Handlers
If handling line chart events, utilize the newselfType property:
Common Issues
Axis Formatter Breaking
If your axis labels stop working:Label Color Not Working
If labels don’t inherit colors:Time Axis Custom Values Error
TypeError with time axis custom values should be resolved in v5.x:Performance Improvements
v5 includes significant performance enhancements:- Faster initial rendering
- Improved animation performance
- Better memory management
- Optimized large dataset handling
Resources
Getting Help
For migration assistance:- Search GitHub issues
- Email dev@echarts.apache.org
- Check the official documentation