Data Labels

Data Labels identify the details of data points in a data series. They are used to ensure that users can easily understand and interpret the information plotted in a chart.

In SpreadJS, you can get or set the data labels, change their position and color, and control whether to show the data labels in the chart using the dataLabels method and DataLabelPosition enumeration.

A basic image with data label configuration is shown below.

The following code sample shows how to configure data labels in a chart.

//Configure DataLabels
var dataLabels = chart.dataLabels();
dataLabels.showValue = true;
dataLabels.showSeriesName = false;
dataLabels.showCategoryName = false;
dataLabels.color = "#000000";
var dataLabelPosition = GC.Spread.Sheets.Charts.DataLabelPosition;

// This position contains many options. Different chart type applies different position values
dataLabels.position = dataLabelPosition.outsideEnd;
chart.dataLabels(dataLabels);        

You can also customize the style of data labels by setting the background color, transparency or border color, width, transparency, etc. Additionally, you can configure different styles for different series of a chart as can be observed in the below image.

The following code sample shows how to configure styles of data labels for different chart series.

// get series 0 & 1 and set it's properties
for (var i = 0; i < 2; i++) {
    var series = chart.series().get(i);
    series.dataLabels = {
        showValue: false,
        showSeriesName: true,
        showCategoryName: false,
        showPercentage: false,
        separator: ",",
        position: GC.Spread.Sheets.Charts.DataLabelPosition.Center,
        format: "#,##0;-#,##0",
        color: "white",
        backColor: "red",
        borderColor: "blue",
        borderWidth: 2
    };
    chart.series().set(i, series);
}

// get series 2 and set it's properties
var series = chart.series().get(2);
series.dataLabels = {
    showValue: false,
    showSeriesName: true,
    showCategoryName: false,
    showPercentage: true,
    separator: ",",
    position: GC.Spread.Sheets.Charts.DataLabelPosition.Center,
    format: "#,##0;-#,##0",
    color: "white",
    backColor: "skyblue",
    borderColor: "green",
    borderWidth: 2
};
chart.series().set(2, series);

Displaying Cell Range as Data Labels

You can set cell references in the data labels and display the values of the selected cell range as data labels in the charts, similar to Excel's functionality.

Note: The cell range references in data labels support a single row or column range.

• If it is a single row, the data label displays the text of each cell in order from left to right.

• If it is a single Column, the data label displays the text in order from top to bottom.

To utilize cell references in data labels, use the dataLabelsRange property of the IDataLabels interface. This property supports a static value array. Upon changing the referred cell range, the chart will refresh and update the data labels accordingly.

Using Code

The following code sample shows how to show B4 to D4 cell values as the data labels.

 // Add chart data label to display cell range reference text.
 let series = chart.series().get(0);
 series.dataLabels.showDataLabelsRange = true;
 series.dataLabels.dataLabelsRange = "Sheet1!$B$4:$D$4";
 chart.series().set(0, series);

Using Designer

To show the cell range as data labels, you can follow the steps below:

1. Right-click on the data series or chart or data labels to open the context menu.

2. Select the format option available.

3. From the dropdown, select Label Options.

   All label options are displayed under Format Data Label.

4. Under Label Contains, select the Values From Cells checkbox and click Select Range….

5. When the Data Label Range dialog box appears, select the range for which you want the cell values to display as data labels in the worksheet.

6. Once selected, the Data Label Range dialog box will display the selected range.

7. Click OK.

   The cell values will now display as data labels in your chart. If the values in these cells change, the chart labels will automatically update.

Limitations

• Cell range references do not support multiple rows and columns range.

• Setting ShowDatalabelsRange property for a single point data label is not supported.

• The dataLabelsRange property does not support custom names for referencing cells.