Legend configuration

Basic Concepts of Legend

A legend is a component in data visualization charts used to explain the styles corresponding to different series or categories. In ECharts, legends help users understand the classification relationships of chart data through visual symbols (such as colors and shapes) and text labels. Legends can be arranged horizontally or vertically and support interactive behaviors like clicking to filter series.

option = {
  legend: {
    data: ['Sales', 'Inventory', 'Orders']
  },
  xAxis: { type: 'category', data: ['Q1', 'Q2', 'Q3', 'Q4'] },
  yAxis: { type: 'value' },
  series: [
    { name: 'Sales', type: 'bar', data: [120, 200, 150, 80] },
    { name: 'Inventory', type: 'bar', data: [85, 120, 135, 70] },
    { name: 'Orders', type: 'line', data: [65, 100, 120, 90] }
  ]
};

Legend Position and Layout

The top/bottom/left/right properties control the position of the legend within the container, supporting percentage and pixel values. The orient property defines the arrangement direction (horizontal/vertical), and itemGap sets the spacing between legend items.

legend: {
  orient: 'vertical',
  right: 10,
  top: 'center',
  itemGap: 20,
  data: ['Email Marketing', 'Affiliate Advertising', 'Video Ads']
}

Customizing Legend Styles

textStyle configures text styles, while itemWidth and itemHeight control the dimensions of legend markers. itemStyle defines the style of legend graphics, supporting rich text formats:

legend: {
  textStyle: {
    color: '#333',
    fontSize: 14,
    fontWeight: 'bold'
  },
  itemWidth: 25,
  itemHeight: 14,
  itemStyle: {
    borderWidth: 2,
    borderColor: '#c23531'
  }
}

Legend Interaction Features

selectedMode enables selection modes (single/multiple), and selected presets the selected state. Use the formatter function to dynamically generate text:

legend: {
  selectedMode: 'multiple',
  selected: { 'Sales': false },
  formatter: function(name) {
    return '【' + name + '】';
  }
}

Paginated Legend Configuration

When there are too many legend items, enable type: 'scroll' to implement pagination. Control the spacing of page buttons with pageButtonItemGap and set their position with pageButtonPosition:

legend: {
  type: 'scroll',
  pageIconColor: '#2f4554',
  pageIconInactiveColor: '#aaa',
  pageTextStyle: { color: 'black' },
  pageButtonItemGap: 5
}

Custom Legend Content

When defining legend items via the data array, you can individually set the style and icon for each item. Use the icon property to specify custom graphics:

legend: {
  data: [
    { 
      name: 'Search Engine',
      icon: 'path://M10,10 L20,10 L20,20 L10,20 Z',
      textStyle: { color: 'red' }
    },
    {
      name: 'Direct Access',
      icon: 'circle'
    }
  ]
}

Legend and Series Linkage

Legends are automatically linked to series data. When the series name matches the legend data, the corresponding legend item is displayed. For dynamic data scenarios, update via setOption:

myChart.setOption({
  legend: { data: newLegendData },
  series: newSeriesData
});

Special Types of Legends

For special charts like pie charts, legends can display numerical percentages. Achieve this by combining legend.formatter with callback parameters:

legend: {
  formatter: function(name) {
    const data = option.series[0].data;
    const item = data.find(item => item.name === name);
    return `${name} (${item.value}%)`;
  }
}

Legend Event Handling

Bind legend click events to implement custom interactions. ECharts provides the legendselectchanged event:

myChart.on('legendselectchanged', function(params) {
  console.log('Selected legend:', params.selected);
});