Overview

In G2, Legend is an auxiliary element of the chart that uses color, size, and shape to distinguish different data types and is used for data filtering in charts. It can be understood as the visualization of scales corresponding to non-spatial channels (color, opacity, size, shape). G2 automatically generates different legends based on the set graphic attribute mappings and data types. When a variable corresponds to multiple graphic attributes, G2 merges the legends to achieve simplification.

The four non-spatial channels color, opacity, size, and shape automatically generate different legends when they receive parameters that are determined to be fields from the data source:

Components

Usage

There are two ways to configure legends:

First, pass a boolean to set whether to display the legend.

({
  type: 'interval',
  legend: false; // Hide all legends
})

({
  type: 'interval',
  legend: {color: false}; // Hide the legend for the color channel
})

Second, pass legendOption to configure the legend as a whole.

({
  type: 'interval',
  legend: {
    color: {},
    size: {},
  },
});

Configuration Levels

Legends can be configured at the Mark level. In G2, each mark has its own legend. If the scales corresponding to marks are synchronized, the legends are also merged.

({
  type: 'interval',
  legend: {
    color: {},
    size: {},
  },
});

Legends can also be configured at the View level. Legends have transitivity. Legends declared on a view are passed to the marks declared in children. If the mark has a legend for the corresponding channel, they are merged; otherwise, they don't affect each other.

({
  type: 'view',
  legend: {
    color: {},
    size: {},
  },
});

Configuration Options

Legends in G2 are divided into continuous legends and categorical legends. Due to the different structures of these two types of legends, their configuration options also differ.

Some configuration options are scoped to categorical legends and continuous legends: Categorical LegendContinuous Legend

orientation

optional horizontal | vertical

Legend orientation, which is the scroll direction for categorical legends. Default is horizontal.

position

optional "top" | "right" | "left" | "bottom"

Position of the legend. Default is top.

(() => {
  const positionList = ['top', 'right', 'left', 'bottom'];
  const positionMap = positionList.map((p) => {
    return {
      label: p,
      value: p,
    };
  });

  const chart = new G2.Chart();

  chart.options({
    type: 'interval',
    data: [
      { name: 'London', month: 'Jan.', rainfall: 18.9 },
      { name: 'London', month: 'Feb.', rainfall: 28.8 },
      { name: 'London', month: 'Mar.', rainfall: 39.3 },
      { name: 'London', month: 'Apr.', rainfall: 81.4 },
      { name: 'London', month: 'May', rainfall: 47 },
      { name: 'London', month: 'Jun.', rainfall: 20.3 },
      { name: 'London', month: 'Jul.', rainfall: 24 },
      { name: 'London', month: 'Aug.', rainfall: 35.6 },
      { name: 'Berlin', month: 'Jan.', rainfall: 12.4 },
      { name: 'Berlin', month: 'Feb.', rainfall: 23.2 },
      { name: 'Berlin', month: 'Mar.', rainfall: 34.5 },
      { name: 'Berlin', month: 'Apr.', rainfall: 99.7 },
      { name: 'Berlin', month: 'May', rainfall: 52.6 },
      { name: 'Berlin', month: 'Jun.', rainfall: 35.5 },
      { name: 'Berlin', month: 'Jul.', rainfall: 37.4 },
      { name: 'Berlin', month: 'Aug.', rainfall: 42.4 },
    ],
    encode: { x: 'month', y: 'rainfall', color: 'name' },
    transform: [{ type: 'dodgeX' }],
  });

  const handleSetPosition = (position) => {
    chart.options({
      legend: {
        color: {
          position,
        },
      },
    });
    chart.render(); // Re-render the chart
  };

  // Insert Position selector
  const selectorContainer = document.createElement('div');
  selectorContainer.textContent = 'Select legend position ';
  const selector = document.createElement('select');
  selector.innerHTML = positionMap.map(
    (position, index) =>
      `<option value="${position.value}" ${index === 0 ? 'selected' : ''}>${
        position.label
      }</option>`,
  );
  selector.onchange = (e) => {
    handleSetPosition(e.target.value);
  };
  selectorContainer.appendChild(selector);
  const node = chart.getContainer();
  node.insertBefore(selectorContainer, node.childNodes[0]);

  chart.render();

  return node;
})();

layout

LegendLayoutCfg optional

The Legend component supports adjusting its position in the canvas through the layout property. Currently supports basic Flex layout, with supported properties including: justifyContent, alignItems, flexDirection. LegendLayoutCfg configuration is as follows:

By configuring the legend's position and layout, we can flexibly change the legend's position.

// Configure a right-side vertically centered legend

// Step 1: Set position to right

// Step 2: When position is right, the main axis direction flexDirection defaults to column

// Step 3: To achieve vertical centering, we need center alignment in the column direction. Since column is the main axis, configure justifyContent to center
({
  legend: {
    color: {
      position: 'right',
      layout: {
        justifyContent: 'center',
      },
    },
  },
});

Try it out:

size

number optional

Size of the Legend component. Affects the component's size on the cross axis, e.g., for horizontally positioned legends, it affects the overall height. Manual configuration will cause G2's internal calculation logic to fail, requiring you to configure margin, padding, inset, etc. yourself. See Chart Layout. Not recommended unless customization is needed.

width

number optional

Width of the Legend component.

crossPadding

number optional

Distance between the Legend component and the chart. Default is 12.

order

number optional

Sort order of the Legend component during layout. Default is 1. G2's internal components all have default sort sizes. Smaller values are closer to the chart area. For example, the Title component's default sort is 2, which is further from the chart area than the Legend component's default sort of 1.

title

LegendTitleCfg optional

Legend title configuration. LegendTitleCfg configuration is as follows:

When configuring title in the Legend component, it's not configured as an object, but with title prefix plus property.

({
  legend: {
    size: {
      title: 'Legend Title',
      titleSpacing: 0,
      titleInset: 0,
      titlePosition: 't',
      titleFontSize: 16,
      titleFontFamily: 'sans-serif',
      titleFontWeight: 500,
      titleLineHeight: 20,
      titleTextAlign: 'center',
      titleTextBaseline: 'middle',
      titleFill: '#000',
      titleFillOpacity: 0.9,
      titleStroke: '#DAF5EC',
      titleStrokeOpacity: 0.9,
      titleLineWidth: 2,
      titleLineDash: [4, 8],
      titleOpacity: 1,
      titleShadowColor: '#d3d3d3',
      titleShadowBlur: 10,
      titleShadowOffsetX: 10,
      titleShadowOffsetY: 10,
      titleCursor: 'pointer',
    },
  },
});

Try it out:

cols

number optional

Applicable to Categorical Legend. Specify the number of legend items displayed per row; empty means no limit on columns.

Legend layout uses flow layout by default.

When cols is specified, grid layout is used.

colPadding

number optional

Applicable to Categorical Legend. Specify horizontal spacing between legend items. Default is 12.

rowPadding

number optional

Applicable to Categorical Legend. Specify vertical spacing between legend items. Default is 8.

maxRows

number optional

Applicable to Categorical Legend. Specify maximum number of rows for legend. Default is 3.

maxCols

number optional

Applicable to Categorical Legend. Specify maximum number of columns for legend. Default is 3.

💡 How do maxRows and maxCols affect legend layout?

maxRows and maxCols are used to limit the maximum number of rows and columns in legend layout. In the code, this is implemented through getRows = (rows) => Math.min(rows, maxRows) and getCols = (cols) => Math.min(cols, maxCols).

Potential Issues

• Vertical Layout: If maxCols is too small, it may cause single column rows to exceed maxHeight, causing overflow.

• Horizontal Layout: If maxRows is too small, some items may be truncated.

In this case, you need to appropriately adjust the chart's margin and padding to ensure the legend has enough space to display.

itemMarker

LegendItemMarkerCfg optional

Applicable to Categorical Legend. Configure legend item marker. LegendItemMarkerCfg configuration is as follows:

Available Symbols Types

Try it out:

(() => {
  // Available itemMarker shapes
  const shapeList = [
    'bowtie',
    'cross',
    'dash',
    'diamond',
    'dot',
    'hexagon',
    'hollowBowtie',
    'hollowDiamond',
    'hollowHexagon',
    'hollowPoint',
    'hollowSquare',
    'hollowTriangle',
    'hollowTriangleDown',
    'hv',
    'hvh',
    'hyphen',
    'line',
    'plus',
    'point',
    'rect',
    'smooth',
    'square',
    'tick',
    'triangleDown',
    'triangle',
    'vh',
    'vhv',
  ];
  const shapeMap = shapeList.map((p) => {
    return {
      label: p,
      value: p,
    };
  });

  const chart = new G2.Chart();

  chart.options({
    type: 'legends',
    height: 60,
    itemMarker: 'bowtie',
    scale: {
      color: {
        type: 'ordinal',
        domain: ['a', 'b'],
        range: ['steelblue', 'orange'],
      },
    },
  });

  const handleSetShape = (shape) => {
    chart.options({
      itemMarker: shape,
    });
    chart.render(); // Re-render the chart
  };

  const selectorContainer = document.createElement('div');
  selectorContainer.textContent = 'Select legend item marker shape ';
  const selector = document.createElement('select');
  selector.innerHTML = shapeMap.map(
    (shape, index) =>
      `<option value="${shape.value}" ${index === 0 ? 'selected' : ''}>${
        shape.label
      }</option>`,
  );
  selector.onchange = (e) => {
    handleSetShape(e.target.value);
  };
  selectorContainer.appendChild(selector);
  const node = chart.getContainer();
  node.insertBefore(selectorContainer, node.childNodes[0]);

  chart.render();

  return node;
})();

When configuring legend item markers in the Legend component, it's not configured as an object, but with itemMarker prefix plus property.

({
  legend: {
    color: {
      itemMarker: 'rect',
      itemMarkerSize: 20,
      itemMarkerFill: '#000',
      itemMarkerFillOpacity: 0.9,
      itemMarkerStroke: '#DAF5EC',
      itemMarkerStrokeOpacity: 0.9,
      itemMarkerLineWidth: 2,
      itemMarkerLineDash: [4, 8],
      itemMarkerOpacity: 1,
      itemMarkerShadowColor: '#d3d3d3',
      itemMarkerShadowBlur: 10,
      itemMarkerShadowOffsetX: 10,
      itemMarkerShadowOffsetY: 10,
      itemMarkerCursor: 'pointer',
    },
  },
});

itemLabel

LegendItemLabelCfg optional

Applicable to Categorical Legend. Configure legend item label. LegendItemLabelCfg configuration is as follows:

When configuring legend item labels in the Legend component, it's not configured as an object, but with itemLabel prefix plus property.

({
  legend: {
    color: {
      itemLabelText: 'Legend Item Label',
      itemLabelFontSize: 16,
      itemLabelFontFamily: 'sans-serif',
      itemLabelFontWeight: 500,
      itemLabelLineHeight: 20,
      itemLabelTextAlign: 'center',
      itemLabelTextBaseline: 'middle',
      itemLabelFill: '#000',
      itemLabelFillOpacity: 0.9,
      itemLabelStroke: '#DAF5EC',
      itemLabelStrokeOpacity: 0.9,
      itemLabelLineWidth: 2,
      itemLabelLineDash: [4, 8],
      itemLabelOpacity: 1,
      itemLabelShadowColor: '#d3d3d3',
      itemLabelShadowBlur: 10,
      itemLabelShadowOffsetX: 10,
      itemLabelShadowOffsetY: 10,
      itemLabelCursor: 'pointer',
    },
  },
});

itemValue

LegendItemValueCfg optional

Applicable to Categorical Legend. Configure legend item value. LegendItemValueCfg configuration is as follows:

When configuring legend item values in the Legend component, it's not configured as an object, but with itemValue prefix plus property.

({
  legend: {
    color: {
      itemValueText: 'Legend Item Value',
      itemValueFontSize: 16,
      itemValueFontFamily: 'sans-serif',
      itemValueFontWeight: 500,
      itemValueLineHeight: 20,
      itemValueTextAlign: 'center',
      itemValueTextBaseline: 'middle',
      itemValueFill: '#000',
      itemValueFillOpacity: 0.9,
      itemValueStroke: '#DAF5EC',
      itemValueStrokeOpacity: 0.9,
      itemValueLineWidth: 2,
      itemValueLineDash: [4, 8],
      itemValueOpacity: 1,
      itemValueShadowColor: '#d3d3d3',
      itemValueShadowBlur: 10,
      itemValueShadowOffsetX: 10,
      itemValueShadowOffsetY: 10,
      itemValueCursor: 'pointer',
    },
  },
});

itemBackground

LegendItemBackgroundCfg optional

Applicable to Categorical Legend. Configure legend item background. LegendItemBackgroundCfg configuration is as follows:

When configuring legend item background in the Legend component, it's not configured as an object, but with itemBackground prefix plus property.

({
  legend: {
    color: {
      itemBackgroundRadius: 50,
      itemBackgroundFill: '#000',
      itemBackgroundFillOpacity: 0.9,
      itemBackgroundStroke: '#DAF5EC',
      itemBackgroundStrokeOpacity: 0.9,
      itemBackgroundLineWidth: 2,
      itemBackgroundLineDash: [4, 8],
      itemBackgroundOpacity: 1,
      itemBackgroundShadowColor: '#d3d3d3',
      itemBackgroundShadowBlur: 10,
      itemBackgroundShadowOffsetX: 10,
      itemBackgroundShadowOffsetY: 10,
      itemBackgroundCursor: 'pointer',
    },
  },
});

Next, let's try combining various properties of itemMarker, itemLabel, itemValue, and itemBackground to configure a custom legend:

itemWidth

number optional

Applicable to Categorical Legend. Configure legend item width.

itemSpan

number|number[] optional

Applicable to Categorical Legend. Configure space allocation for legend item marker, label, and value. Default is [1, 1, 1].

itemSpacing

number|number[] optional

Applicable to Categorical Legend. Configure spacing between legend item marker, label, and value. Default is [8, 8].

nav

LegendNavCfg optional

Applicable to Categorical Legend. Configure legend navigator. In grid layout, page capacity = gridRow × gridCol. If the number of categorical items exceeds this capacity, pagination occurs. In flex layout, page capacity is dynamically calculated and limited by container width and height. When categorical items exceed container height or width, pagination occurs and the navigator component is displayed. LegendNavCfg configuration is as follows:

When configuring navigator properties in the Legend component, it's not configured as an object, but with nav prefix plus property.

({
  legend: {
    color: {
      navEffect: 'cubic-bezier',
      navDuration: 400,
      navOrientation: 'vertical',
      navDefaultPage: 1,
      navLoop: true,
      navPageWidth: 10,
      navPageHeight: 10,
      navControllerPadding: 10,
      navControllerSpacing: 10,

      // Configure navPageNum drawing properties
      navPageNumFontSize: 16,
      navPageNumFontFamily: 'sans-serif',
      navPageNumFontWeight: 500,
      navPageNumLineHeight: 20,
      navPageNumTextAlign: 'center',
      navPageNumTextBaseline: 'middle',
      navPageNumFill: '#000',
      navPageNumFillOpacity: 0.9,
      navPageNumStroke: '#DAF5EC',
      navPageNumStrokeOpacity: 0.9,
      navPageNumLineWidth: 2,
      navPageNumLineDash: [4, 8],
      navPageNumOpacity: 1,
      navPageNumShadowColor: '#d3d3d3',
      navPageNumShadowBlur: 10,
      navPageNumShadowOffsetX: 10,
      navPageNumShadowOffsetY: 10,
      navPageNumCursor: 'pointer',

      // Configure navButton drawing properties
      navButtonFill: '#000',
      navButtonFillOpacity: 0.9,
      navButtonStroke: '#DAF5EC',
      navButtonStrokeOpacity: 0.9,
      navButtonLineWidth: 2,
      navButtonLineDash: [4, 8],
      navButtonOpacity: 1,
      navButtonShadowColor: '#d3d3d3',
      navButtonShadowBlur: 10,
      navButtonShadowOffsetX: 10,
      navButtonShadowOffsetY: 10,
      navButtonCursor: 'pointer',
    },
  },
});

Try it out:

color

string[] | d3-interpolate optional

Applicable to Continuous Legend. Configure color band colors for continuous legend. When it's an array, colors are taken in order.

block

boolean optional

Applicable to Continuous Legend. Whether continuous legend displays by intervals. Default is false.

type

size | color optional

Applicable to Continuous Legend. Configure type of continuous legend. Default is color.

Combining block and type properties allows you to configure different styles of continuous legends. Continuous data legends have 4 styles:

• Continuous representation default

  

• Range representation block=true

  

• Size representation type='size'

  

• Size, range representation type='size' block=true

  

ribbon

LegendRibbonCfg optional

Applicable to Continuous Legend. Configure color band of continuous legend. LegendRibbonCfg configuration is as follows:

When configuring color band in the Legend component, it's not configured as an object, but with ribbon prefix plus property.

({
  legend: {
    color: {
      ribbonSize: 20,
      ribbonFill: '#000',
      ribbonFillOpacity: 0.9,
      ribbonStroke: '#DAF5EC',
      ribbonStrokeOpacity: 0.9,
      ribbonLineWidth: 2,
      ribbonLineDash: [4, 8],
      ribbonOpacity: 1,
      ribbonShadowColor: '#d3d3d3',
      ribbonShadowBlur: 10,
      ribbonShadowOffsetX: 10,
      ribbonShadowOffsetY: 10,
      ribbonCursor: 'pointer',
    },
  },
});

handle

LegendHandleCfg optional

The slider window marks the current value selection range. Through interaction with the slider window, you can select the value range in the view.

Applicable to Continuous Legend. Configure slider handle of continuous legend. LegendHandleCfg configuration is as follows:

When configuring continuous legend slider handle properties in the Legend component, it's not configured as an object, but with handle prefix plus property.

({
  legend: {
    color: {
      handle: true,
      handleLabel: true,
      slidable: true,
      range: [0, 1],
      step: 1,
      // Configure handleLabel drawing properties
      handleLabelFontSize: 16,
      handleLabelFontFamily: 'sans-serif',
      handleLabelFontWeight: 500,
      handleLabelLineHeight: 20,
      handleLabelTextAlign: 'center',
      handleLabelTextBaseline: 'middle',
      handleLabelFill: '#000',
      handleLabelFillOpacity: 0.9,
      handleLabelStroke: '#DAF5EC',
      handleLabelStrokeOpacity: 0.9,
      handleLabelLineWidth: 2,
      handleLabelLineDash: [4, 8],
      handleLabelOpacity: 1,
      handleLabelShadowColor: '#d3d3d3',
      handleLabelShadowBlur: 10,
      handleLabelShadowOffsetX: 10,
      handleLabelShadowOffsetY: 10,
      handleLabelCursor: 'pointer',

      handleIconSize: 50,
      // Configure handleIcon drawing properties
      handleIconFill: '#000',
      handleIconFillOpacity: 0.9,
      handleIconStroke: '#DAF5EC',
      handleIconStrokeOpacity: 0.9,
      handleIconLineWidth: 2,
      handleIconLineDash: [4, 8],
      handleIconOpacity: 1,
      handleIconShadowColor: '#d3d3d3',
      handleIconShadowBlur: 10,
      handleIconShadowOffsetX: 10,
      handleIconShadowOffsetY: 10,
      handleIconCursor: 'pointer',
    },
  },
});

label

LegendLabelCfg optional

Applicable to Continuous Legend. Configure labels/tick values of continuous legend. LegendLabelCfg configuration is as follows:

Tick value alignment methods

• Align to tick

• Align to range

When configuring continuous legend labels/tick values properties in the Legend component, it's not configured as an object, but with label prefix plus property.

({
  legend: {
    color: {
      label: true,
      labelFormatter: (d) => {},
      labelFilter: (datum, index, data) => {},
      labelDirection: 'positive',
      labelSpacing: 5,
      labelAlign: 'range',
      // Configure continuous legend tick value label drawing properties
      labelFontSize: 16,
      labelFontFamily: 'sans-serif',
      labelFontWeight: 500,
      labelLineHeight: 20,
      labelTextAlign: 'center',
      labelTextBaseline: 'middle',
      labelFill: '#000',
      labelFillOpacity: 0.9,
      labelStroke: '#DAF5EC',
      labelStrokeOpacity: 0.9,
      labelLineWidth: 2,
      labelLineDash: [4, 8],
      labelOpacity: 1,
      labelShadowColor: '#d3d3d3',
      labelShadowBlur: 10,
      labelShadowOffsetX: 10,
      labelShadowOffsetY: 10,
      labelCursor: 'pointer',
    },
  },
});

indicator

LegendIndicatorCfg optional

Applicable to Continuous Legend. Configure indicator of continuous legend. The indicator is a tooltip component that indicates the value at the current position during interaction with the continuous legend.

LegendIndicatorCfg configuration is as follows:

When configuring value indicator properties in the Legend component, it's not configured as an object, but with indicator prefix plus property.

({
  legend: {
    color: {
      indicator: 'true',
      indicatorFormatter: (d) => {},

      // Configure indicatorLabel drawing properties
      indicatorLabelFontSize: 16,
      indicatorLabelFontFamily: 'sans-serif',
      indicatorLabelFontWeight: 500,
      indicatorLabelLineHeight: 20,
      indicatorLabelTextAlign: 'center',
      indicatorLabelTextBaseline: 'middle',
      indicatorLabelFill: '#000',
      indicatorLabelFillOpacity: 0.9,
      indicatorLabelStroke: '#DAF5EC',
      indicatorLabelStrokeOpacity: 0.9,
      indicatorLabelLineWidth: 2,
      indicatorLabelLineDash: [4, 8],
      indicatorLabelOpacity: 1,
      indicatorLabelShadowColor: '#d3d3d3',
      indicatorLabelShadowBlur: 10,
      indicatorLabelShadowOffsetX: 10,
      indicatorLabelShadowOffsetY: 10,
      indicatorLabelCursor: 'pointer',

      // Configure indicatorBackground drawing properties
      indicatorBackgroundFill: '#000',
      indicatorBackgroundFillOpacity: 0.9,
      indicatorBackgroundStroke: '#DAF5EC',
      indicatorBackgroundStrokeOpacity: 0.9,
      indicatorBackgroundLineWidth: 2,
      indicatorBackgroundLineDash: [4, 8],
      indicatorBackgroundOpacity: 1,
      indicatorBackgroundShadowColor: '#d3d3d3',
      indicatorBackgroundShadowBlur: 10,
      indicatorBackgroundShadowOffsetX: 10,
      indicatorBackgroundShadowOffsetY: 10,
      indicatorBackgroundCursor: 'pointer',
    },
  },
});

Events

The Legend component exposes some special events for getting component interaction information.

Components appear after chart rendering, so component events should be mounted after afterrender. Here's an example:

chart.on('afterrender', () => {
  const { canvas } = chart.getContext();
  const { document } = canvas;
  document
    .querySelector('.component')
    .addEventListener('valuechange', (range) => {});
});

Examples

Default Display of Only Partial Legends on First Chart Render

There's currently no built-in API for this, so you need to manually trigger legendFilter to achieve it.

import { Chart, ChartEvent } from '@antv/g2';

const chart = new Chart({ container: 'container' });

chart.options({
  type: 'interval',
  data: [
    { genre: 'Sports', sold: 100 },
    { genre: 'Strategy', sold: 115 },
    { genre: 'Action', sold: 120 },
    { genre: 'Shooter', sold: 350 },
    { genre: 'Other', sold: 150 },
  ],
  encode: { x: 'genre', y: 'sold', color: 'genre' },
});

chart.render();

chart.on(ChartEvent.AFTER_RENDER, () => {
  chart.emit('legend:filter', {
    data: { channel: 'color', values: ['Sports', 'Strategy', 'Action'] },
  });
});

Custom Legend Item Marker (itemMarker)

In actual development, the built-in legend item markers may not meet your requirements. Don't worry, G2 provides powerful customization features.

Custom Symbol

Each symbol can be customized, mainly in three steps:

• Define symbol path.
• Register symbol.
• Use symbol.

First, let's see how to define a symbol path. A symbol path is a function that takes the starting point coordinates x, y and drawing radius, and returns a path.

import { type SymbolFactor } from '@antv/g2';

const triangle: SymbolFactor = (x, y, r) => {
  const diffY = r * Math.sin((1 / 3) * Math.PI);
  return [
    ['M', x - r, y + diffY],
    ['L', x, y - diffY],
    ['L', x + r, y + diffY],
    ['Z'],
  ];
};
triangle.style = ['fill'];

Next is registering the symbol, by calling G2.register('symbol.${symbol}', Symbol). Where symbol is the symbol name and Symbol is the defined symbol path. For example, registering a triangle symbol:

import { register } from '@antv/g2';

register('symbol.customTriangle', triangle);