Legend

Search…
Legend
The legend for F2 is determined by the color mapping. When the data mapped to color is a cat scale(for discrete ordinal (ordered) or categorical (unordered) data), a legend is generated.
How to Register Legend Plugin
F2 has modular structure provides best tree-shaking results and package size optimization. 
If you just import F2 from '@antv/f2', then it has included legend by default. But if you want a better package size optimization, you can register manually:
1
const F2 = require('@antv/f2/lib/core');
2
const Legend = require('@antv/f2/lib/plugin/legend');
3
// Method 1: Global Registeration
4
F2.Chart.plugins.register(Legend); 
5
​
6
// Or Method2: Registeration for a Chart instance
7
const chart = new F2.Chart({
8
  id: 'canvas',
9
  plugins: Legend
10
});
Copied!
Legend Configuration
Close the Legend
chart.legend(false)
Just close all legends. Sometimes there will be several legends.
chart.legend(field, false)
field: String type, the map field of the legend.
Close the legend corresponding to the field.
Configure Legend
chart.legend(field, config)
field: String, the map field of the legend.
config: Object type, configuration for the axis. The properties included are as follows:
Name
Type
Default
Description
position
String
'top'
The display position of the legend, can be set to 'top', 'right', 'bottom', 'left', defaults to 'top'.
align
String
'left'
It is used to set the alignment of the legend in the horizontal direction, when position is set to be 'top' or 'bottom'.The values that can be set are: 'left', 'center', 'right', and the default is 'left'. See demos.
verticalAlign
String
'middle'
It is used to set the alignment of the legend in the vertical direction, when position is set to 'left' and 'right'. The values that can be set are: 'top', 'middle', 'bottom', and the default is 'middle'. See demos.
itemWidth
Number | 'auto'
'auto'
It is used to set width of the legend item, defaults to 'auto', using the default layout of F2 to calculate the width. If the itemWidth is set to null, it will be calculated based on the width of the legend  itself, developers are also allowed to set the value of the itemWidth, such as itemWidth: 50
showTitle
Boolean
false
wether show the title of the legend, default to false.
titleStyle
Object
{ fontSize: 12, fill: '#fff', textAlign: 'start', textBaseline: 'top' }
Configure the style of legend title. see Canvas for more details.
offsetX
Number
0
The offset of the legend in x direction. The value unit is 'px' and the default value is 0.
offsetY
Number
0
The offset of the legend in y direction. The value unit is 'px' and the default value is 0.
titleGap
Number
12
The distance between the title and the legend items, defaults to 12(px). If the title is not displayed, it is invalid.
itemGap
Number
12
The distance between legend's items in horizontal direction, defaults to 12(px).
itemMarginBottom
Number
12
The distance in the vertical direction from the next legend item, defaults to 12(px).
wordSpace
Number
6
The distance between the marker and legend label, defaults to 6(px).
unCheckStyle
Object
{ fill: '#bfbfbf'}
Used to set the style of the marker and text in the legend item that is not selected.
itemFormatter
Function
null
Callback for formatting the text in legend. See callback.
marker
String/Function/Object
'circle'
It is used to set the marker style of the legend, defaults to 'circle'.  See custom marker for detail.
nameStyle
Object
see source​
It is used to set the text style of the legend, see Canvas for more details. Demo.
valueStyle
Object
see source​
It is used to set the text style of the legend, see Canvas for more details.Demo.
joinString
String
':'
Set the connection character for name and value in the legend item. The default is ':'.
triggerOn
String
'touchstart'
The trigger event of the legend filter behavior, the default is 'touchstart'.
selectedMode
String
'multiple'
Set the selected mode of the legend, provide two modes: 'multiple' and 'single'
clickable
Boolean
true
wether the legend is clickable, defaults to true.
onClick
Function
null
callback for clicking the legend, invalid when clickable is false. see here for detail.
custom
Boolean
false
when custom is true, users are allowed to customize legends, including the specific legends and corresponding interactions. The default value is false. See here for detail.
Legend align demos
When position is set to be 'top' or 'bottom', you can set align property:
align: 'left'
align: 'center'
align: 'right'
​​
​​
​​
​​
​​
​​
Legend verticalAlign demos
When position is set to be 'left' or 'right', you can set verticalAlign property:
verticalAlign: 'middle'
verticalAlign: 'top'
verticalAlign: 'bottom'
​​
​​
​​
​​
​​
​​
itemFormatter callback
Use this property to complete the formatted display of the legend item text.  See detailed demo.
1
chart.legend({
2
  position: 'right',
3
  itemFormatter(val) {
4
    return val + ' %';
5
  }
6
});
Copied!
Custom maker
The following describes the specific use of the marker：
 When marker is a String, F2 provides the following types：marker: 'circle' or marker: 'square'
when marker is an Object, you can configure the type of marker and its style.
1
chart.legend({
2
  marker: {
3
    symbol: 'circle', // shape of the marker
4
    radius: 5 // radius of the circle
5
  }
6
});
Copied!
When marker is a Function, you can customize the shape you need
1
chart.legend({
2
  /**
3
   * customize the shape of marker
4
   * @param  {number} x   x-axis of the marker
5
   * @param  {number} y   y-axis of the marker
6
   * @param  {number} r   radius of the marker
7
   * @param  {object} ctx context object of the canvas
8
   * @return {null}     
9
   */
10
  marker(x, y, r, ctx) {}
11
});
Copied!
The following code draws a marker shown below: 
1
chart.legend('city', {
2
  marker(x, y, r, ctx) {
3
    ctx.lineWidth = 2;
4
    ctx.strokeStyle = ctx.fillStyle;
5
    ctx.moveTo(x - r - 3, y);
6
    ctx.lineTo(x + r + 3, y);
7
    ctx.stroke();
8
    ctx.arc(x, y, r, 0, Math.PI * 2, false);
9
    ctx.fill();
10
  }
11
});
Copied!
onClick callback
See demo.
1
chart.legend({
2
 /**
3
  * callback for clicking the legend, invalid when clickable is false.
4
  * @param  {object} event obejct
5
  * @return {null}
6
  */
7
 onClick: ev => {
8
    const { clickedItem } = ev; // get the clicked legend item
9
 }
10
});
Copied!
Legend Item Interface
The Legend item implement the following interface，the image below will help you better understand:
1
{
2
  // Label that will be displayed as name
3
  name: String,
4
  
5
  // Label that will be displayed as value
6
  value: String / Number,
7
  
8
  // For marker, see Custom maker
9
  marker: String / Object / Function,
10
  
11
  // For setting the legend click style, if not set, the default is true
12
  checked: Boolean,
13
  
14
  // Fill style of the legend marker, you also can set in marker(when it is an object)
15
  fill: String
16
}
Copied!
For example, use the custom legend feature to define legend items as follows:
1
chart.legend({
2
  position: 'right',
3
  custom: true,
4
  items: [
5
    { name: 'TYPE A', value: '73.76%',  marker: { symbol: 'square', fill: '#1890FF', radius: 4 } },
6
    { name: 'TYPE B', value: '22.11%', marker: { symbol: 'square', fill: '#2FC25B', radius: 4 } },
7
    { name: 'TYPE C', value: '2.2%', marker: { symbol: 'square', fill: '#FACC14', radius: 4 } },
8
    { name: 'TYPE D', value: '1.93%', marker: { symbol: 'square', fill: '#F04864', radius: 4 } }
9
  ],
10
  nameStyle: {
11
    fill: '#808080'
12
  }, // For styling the name label
13
  valueStyle: {
14
    fill: '#333',
15
    fontWeight: 'bold' // For styling the value label
16
  }
17
});
Copied!
Custom Legend
You can use the custom legend feature to customize the display content and style of the legend, and you can also use the onClick callback to define the interaction behavior of the legend.
Below is a demo, you can click on the legend to control the display and hide of the corresponding geometry，Complete code.
1
chart.legend({
2
  custom: true,
3
  items: [
4
    { name: '个人分数', marker: 'square', fill: '#FACC14', checked: true }, 
5
    { name: '平均分数',
6
      marker: function marker(x, y, r, ctx) {
7
        ctx.lineWidth = 1;
8
        ctx.strokeStyle = ctx.fillStyle;
9
        ctx.moveTo(x - r - 3, y);
10
        ctx.lineTo(x + r + 3, y);
11
        ctx.stroke();
12
        ctx.arc(x, y, r, 0, Math.PI * 2, false);
13
        ctx.fill();
14
      },
15
      fill: '#000',
16
      checked: true
17
    }
18
  ],
19
  onClick(ev) {
20
    const item = ev.clickedItem;
21
    const name = item.get('name');
22
    const checked = item.get('checked');
23
    const children = item.get('children'); 
24
    if (checked) {
25
      const markerFill = children[0].attr('fill');
26
      const textFill = children[1].attr('fill');
27
      children[0].set('_originColor', markerFill); // 缓存 marker 原来的颜色
28
      children[1].set('_originColor', textFill); // 缓存文本原来的颜色
29
    }
30
    const geoms = chart.get('geoms');
31
    const canvas = chart.get('canvas');
32
    for (let i = 0; i < geoms.length; i++) {
33
      const geom = geoms[i];
34
      const container = geom.get('container');
35
​
36
      if (geom.getYScale().alias === name)
37
        if (!checked) {
38
          container.show();
39
          children[0].attr('fill', children[0].get('_originColor'));
40
          children[1].attr('fill', children[1].get('_originColor'));
41
        } else {
42
          container.hide();
43
          children[0].attr('fill', '#bfbfbf'); // marker 置灰
44
          children[1].attr('fill', '#bfbfbf'); // 文本置灰 置灰
45
        }
46
      item.set('checked', !checked);
47
      legendItems[findLegendItem(name)].checked = !checked;
48
    }
49
    canvas.draw();
50
  }
51
});
Copied!
More Legend Demos
Demos
​
​top-center legend​
​
​
​legend style​
​
​
​custom legend that can be clicked​
​
​
​marker​
​
​
​single mode​
​
​
​right-top legend​
​
​