# Legend

Describes Legends in Data Charts is a visual aid that helps users understand each line, bar, or other data by associating them with different colors and sizes.

## Content

Legend in Data Charts is a visual aid that helps users understand what each line, bar, or other data by associating them with different colors and sizes.
Use the `ILegendOptions` interface to define the appearance and behavior of a legend in a Data Chart. It includes optional properties such as title, type, position, text style, and many more. Additionally, use the `LegendType` enumeration to specify the type of legend, such as color or size, whereas `LegendPosition` enumeration defines where the legend can be positioned in the Data Chart.
The type of symbol displayed for legend depends on the Data Chart type:

* **Square**: Used for bar, area, sunburst, pie, donut, and range charts.
* **Line**: Used for line charts without symbols.
* **Circle**: Used for XY scatter, bubble, and area charts with symbols.
* **Line with Circle**: Used for line charts with symbols.

## Legend Properties

The list below shows the key properties of the `ILegendOptions` interface.

| **Property** | **Description** | **Sample Preview** |
| -------- | ----------- | -------------- |
| @rows=2:type | Represents data through distinct colors, applicable to all chart types. Color legends appear automatically if fields are bound to the legend in chart encodings. | ![Color Legend](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/Color%20Legend.b956cc.png?width=330) |
| Represents data through varying symbol sizes, typically used in bubble charts. Size legends do not appear by default and require explicit configuration. | ![size legend](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/size%20legend.489afa.png) |
| title | Adds a descriptive title to the legend, which describes the meaning or dimension of the content represented in the legend. | ![Legend Title](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/Legend%20Title.d5e275.png) |
| position | Determines where the legend appears in the chart. <br>The available options are None (Default), Top, Bottom, Left, and Right. | ![Legend Position Top](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/Legend%20Position%20Top.646a22.png) |
| textStyle | Defines the appearance of text in the legend area. | ![Legend textStyle](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/Legend%20textStyle.e9789a.png) |
| height & width | Sets the dimensions of the legend as a percentage of the entire Data Chart, ranging from 0 to 1. | ![Legend height & width](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/Legend%20height%20%26%20width.355fd8.png) |
| hAlign | Sets horizontal alignment (hAlign) of the legend as Left, Center (Default), or Right. | ![Legend HAlignLeft](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/Legend%20HAlignLeft.2915aa.png) |
| vAlign | Sets vertical alignment (vAlign) of the legend as Top, Middle (Default), or Bottom. | ![Legend vAlignTop](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/Legend%20vAlignTop.cecbcb.png) |
| padding | Adjusts the spacing inside the legend. Default padding is: { top: 10, bottom: 10, left: 10, right: 10 }. | ![Legend padding](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/Legend%20padding.b9288b.png) |

## Using Code

The following code sample illustrates how to configure legends for a Data Chart.
Note that this sample uses the "salesTable" data mentioned on the [Create Data Charts](/spreadjs/docs/v18/features/data-charts/create-data-charts) page. Therefore, make sure you have completed the primary steps outlined on that page to set up a data chart. Once done, you can use the following codes to configure the legends. Additionally, you also have the flexibility to customize the data source according to your specific needs.

```javascript
// 1. Type
const sheet = spread.getSheet(0);
sheet.setColumnCount(30);
sheet.name("Type");
sheet.setValue(7, 0, "Color Legend");
sheet.setValue(28, 0, "The size legend will not be displayed by default");
sheet.setValue(28, 10, "If you want to display the “size” legend, you need to set the position of the legend.");
// sheet.setValue(23, 0, "Polar coordinate system");
const dataChart = sheet.dataCharts.add('data-chart', 100, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);

// As long as the color legend related fields are bound in the “encodings”,
// the color legend will be shown in the DataChart by default.
dataChart.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Salesman' },
                 color: { field: 'Salesman' },
             },
         }
     ],
});


const dataChart2 = sheet.dataCharts.add('data-chart-2', 10, 300, 400, 259, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart2.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.bubble,
             encodings: {
                 values: [
                     { field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum },
                     { field: 'Return', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }
                 ],
                 size: { field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum },
             },
         }
     ],
});

const dataChart3 = sheet.dataCharts.add('data-chart-3', 620, 300, 400, 259, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart3.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.bubble,
             encodings: {
                 values: [
                     { field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum },
                     { field: 'Return', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }
                 ],
                 size: { field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum },
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.size,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right
             }]
         }]
     }
});

// 2. Title
let sheet2 = spread.getSheet(1);
sheet2.name("Title");
sheet2.setValue(16, 0, "The Legend has title 'Product Category'");
const dataChart4 = sheet2.dataCharts.add('data-chart-4', 10, 10, 480, 300, GC.Spread.Sheets.DataCharts.DataChartType.column);

dataChart4.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 title: "Product Category",
             }]
         }]
     }
});


// 3. Position
let sheet3 = spread.getSheet(2);
sheet3.name("Position");
sheet3.setValue(13, 0, "Legend Position: Right");
sheet3.setValue(30, 0, "Legend Position: Top");
sheet3.setValue(13, 9, "Legend Position: Left");
sheet3.setValue(30, 9, "Legend Position: Bottom");

const dataChart5 = sheet3.dataCharts.add('data-chart-5', 10, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart5.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,  // Right Position
             }]
         }]
     }
});
const dataChart6 = sheet3.dataCharts.add('data-chart-6', 550, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart6.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.left, // Left Position
             }]
         }]
     }
});
const dataChart7 = sheet3.dataCharts.add('data-chart-7', 10, 350, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart7.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.top,   // Top Position
             }]
         }]
     }
});
const dataChart8 = sheet3.dataCharts.add('data-chart-8', 550, 350, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart8.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.bottom,  // Bottom Position
             }]
         }]
     }
});

// 4. Text Style
let sheet4 = spread.getSheet(3);
sheet4.name("Text Style");
sheet4.setValue(17, 0, "Legend Text Style has been changed");

const dataChart9 = sheet4.dataCharts.add('data-chart-9', 10, 10, 450, 300, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart9.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 textStyle: {
                     color: "#483f3f",
                     fontFamily: "Century",
                     fontSize: 14,
                     fontStyle: GC.Spread.Sheets.DataCharts.FontStyle.italic,
                     fontWeight: "Bold"
                 }
             }]
         }]
     }
});

// 5. Height and Width
let sheet5 = spread.getSheet(4);
sheet5.name("Height and Width");
sheet5.setValue(16, 0, "Height of the Legend: 0.5");
sheet5.setValue(16, 10, "Width of the Legend: 0.4");

const dataChart10 = sheet5.dataCharts.add('data-chart-10', 10, 10, 450, 300, GC.Spread.Sheets.DataCharts.DataChartType.column);
dataChart10.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.bottom,
                 // Set the height of the legend as a percentage of the entire DataChart.
                 height: 0.5, // Value range is 0~1.
             }]
         }]
     }
});

const dataChart11 = sheet5.dataCharts.add('data-chart-11', 600, 10, 450, 300, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart11.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 // Set the width of the legend as a percentage of the entire DataChart.
                 width: 0.4, // Value range is 0~1.
             }]
         }]
     }
});

 // 6. hAlign
 let sheet6 = spread.getSheet(5);
 sheet6.name("hAlign");
 sheet6.setValue(13, 0, "Horizonal Alignment: Left");
 sheet6.setValue(30, 0, "Horizonal Alignment: Center  (Default Value)");
 sheet6.setValue(13, 9, "Horizonal Alignment: Right");

 const dataChart12 = sheet6.dataCharts.add('data-chart-12', 10, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart12.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.bottom,
                 padding: {
                     left: 30,
                 },
                 // Set the Horizontal Alignment
                 hAlign: GC.Spread.Sheets.DataCharts.HAlign.left   // Left Position
             }]
         }]
     }
 });

 const dataChart13 = sheet6.dataCharts.add('data-chart-13', 10, 350, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart13.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.bottom,
                 padding: {
                     left: 30,
                 },
                 // Set the Horizontal Alignment
                 hAlign: GC.Spread.Sheets.DataCharts.HAlign.center   // Center Position (Default)
             }]
         }]
     }
 });

 const dataChart14 = sheet6.dataCharts.add('data-chart-14', 550, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart14.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.bottom,
                 padding: {
                     left: 30,
                 },
                 // Set the Horizontal Alignment
                 hAlign: GC.Spread.Sheets.DataCharts.HAlign.right   // Right Position
             }]
         }]
     }
 });

 // 7. vAlign
 let sheet7 = spread.getSheet(6);
 sheet7.name("vAlign");
 sheet7.setValue(13, 0, "Vertical Alignment: Top");
 sheet7.setValue(30, 0, "Vertical Alignment: Center  (Default Value)");
 sheet7.setValue(13, 9, "Vertical Alignment: Bottom");

 const dataChart15 = sheet7.dataCharts.add('data-chart-15', 10, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart15.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 padding: {
                     left: 30,
                 },
                 // Set the Vertical Alignment
                 vAlign: GC.Spread.Sheets.DataCharts.VAlign.top   // Top Position
             }]
         }]
     }
 });

 const dataChart16 = sheet7.dataCharts.add('data-chart-16', 10, 350, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart16.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 padding: {
                     left: 30,
                 },
                 // Set the Vertical Alignment
                 vAlign: GC.Spread.Sheets.DataCharts.VAlign.middle   // Middle Position (Default Value)
             }]
         }]
     }
 });

 const dataChart17 = sheet7.dataCharts.add('data-chart-17', 550, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart17.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 padding: {
                     left: 30,
                 },
                 // Set the Vertical Alignment
                 vAlign: GC.Spread.Sheets.DataCharts.VAlign.bottom   // Bottom Position
             }]
         }]
     }
 });

 // 8. Padding
 let sheet8 = spread.getSheet(7);
 sheet8.name("Padding");
 sheet8.setValue(13, 0, "Left Padding: 30");

 const dataChart18 = sheet8.dataCharts.add('data-chart-18', 10, 10, 400, 250, GC.Spread.Sheets.DataCharts.DataChartType.column);
 dataChart18.setChartConfig({
     tableName: 'Sales',
     plots: [
         {
             type: GC.Spread.Sheets.DataCharts.DataChartType.column,
             encodings: {
                 values: [{ field: 'Sales', aggregate: GC.Spread.Sheets.DataCharts.Aggregate.sum }],
                 category: { field: 'Product' },
                 color: { field: 'Product' }
             },
         }
     ],
     config: {
         plotAreas: [{
             legends: [{
                 type: GC.Spread.Sheets.DataCharts.LegendType.color,
                 position: GC.Spread.Sheets.DataCharts.LegendPosition.right,
                 padding: {
                     left: 30,
                 }
             }]
         }]
     }
 });
```