ExcelScript.Chart interface

Reference

Package:: ExcelScript

Represents a chart object in a workbook.

Methods

activate()	Activates the chart in the Excel UI.
addChartSeries(name, index)	Add a new series to the collection. The new added series is not visible until values, x-axis values, or bubble sizes for it are set (depending on chart type).
delete()	Deletes the chart object.
getAxes()	Represents chart axes.
getCategoryLabelLevel()	Specifies a chart category label level enumeration constant, referring to the level of the source category labels.
getChartType()	Specifies the type of the chart. See `ExcelScript.ChartType` for details.
getDataLabels()	Represents the data labels on the chart.
getDataTable()	Gets the data table on the chart. If the chart doesn't allow a data table, then this method returns `undefined`.
getDisplayBlanksAs()	Specifies the way that blank cells are plotted on a chart.
getFormat()	Encapsulates the format properties for the chart area.
getHeight()	Specifies the height, in points, of the chart object.
getId()	The unique ID of chart.
getImage(width, height, fittingMode)	Renders the chart as a base64-encoded image by scaling the chart to fit the specified dimensions. The aspect ratio is preserved as part of the resizing.
getLeft()	The distance, in points, from the left side of the chart to the worksheet origin.
getLegend()	Represents the legend for the chart.
getName()	Specifies the name of a chart object.
getPivotOptions()	Encapsulates the options for a pivot chart.
getPlotArea()	Represents the plot area for the chart.
getPlotBy()	Specifies the way columns or rows are used as data series on the chart.
getPlotVisibleOnly()	True if only visible cells are plotted. False if both visible and hidden cells are plotted.
getSeries()	Represents either a single series or collection of series in the chart.
getSeriesNameLevel()	Specifies a chart series name level enumeration constant, referring to the level of the source series names.
getShowAllFieldButtons()	Specifies whether to display all field buttons on a PivotChart.
getShowDataLabelsOverMaximum()	Specifies whether to show the data labels when the value is greater than the maximum value on the value axis. If the value axis becomes smaller than the size of the data points, you can use this property to set whether to show the data labels. This property applies to 2-D charts only.
getStyle()	Specifies the chart style for the chart.
getTitle()	Represents the title of the specified chart, including the text, visibility, position, and formatting of the title.
getTop()	Specifies the distance, in points, from the top edge of the object to the top of row 1 (on a worksheet) or the top of the chart area (on a chart).
getWidth()	Specifies the width, in points, of the chart object.
getWorksheet()	The worksheet containing the current chart.
setCategoryLabelLevel(categoryLabelLevel)	Specifies a chart category label level enumeration constant, referring to the level of the source category labels.
setChartType(chartType)	Specifies the type of the chart. See `ExcelScript.ChartType` for details.
setData(sourceData, seriesBy)	Resets the source data for the chart.
setDisplayBlanksAs(displayBlanksAs)	Specifies the way that blank cells are plotted on a chart.
setHeight(height)	Specifies the height, in points, of the chart object.
setLeft(left)	The distance, in points, from the left side of the chart to the worksheet origin.
setName(name)	Specifies the name of a chart object.
setPlotBy(plotBy)	Specifies the way columns or rows are used as data series on the chart.
setPlotVisibleOnly(plotVisibleOnly)	True if only visible cells are plotted. False if both visible and hidden cells are plotted.
setPosition(startCell, endCell)	Positions the chart relative to cells on the worksheet.
setSeriesNameLevel(seriesNameLevel)	Specifies a chart series name level enumeration constant, referring to the level of the source series names.
setShowAllFieldButtons(showAllFieldButtons)	Specifies whether to display all field buttons on a PivotChart.
setShowDataLabelsOverMaximum(showDataLabelsOverMaximum)	Specifies whether to show the data labels when the value is greater than the maximum value on the value axis. If the value axis becomes smaller than the size of the data points, you can use this property to set whether to show the data labels. This property applies to 2-D charts only.
setStyle(style)	Specifies the chart style for the chart.
setTop(top)	Specifies the distance, in points, from the top edge of the object to the top of row 1 (on a worksheet) or the top of the chart area (on a chart).
setWidth(width)	Specifies the width, in points, of the chart object.

Method Details

activate()

Activates the chart in the Excel UI.

activate(): void;

Returns

void

addChartSeries(name, index)

Add a new series to the collection. The new added series is not visible until values, x-axis values, or bubble sizes for it are set (depending on chart type).

addChartSeries(name?: string, index?: number): ChartSeries;

Parameters

name: string

Optional. Name of the series.

index: number

Optional. Index value of the series to be added. Zero-indexed.

Returns

ExcelScript.ChartSeries

Examples

/**
 * This sample produces a line chart with two series.
 * The chart assumes data in A1:E5 that looks like this:
 * Product Qtr1 Qtr2 Qtr3 Qtr4
 * Frames 5000 7000 6544 4377
 * Saddles 400 323 276 651
 */
function main(workbook: ExcelScript.Workbook) {
  // Establish the ranges to use.
  const sheet = workbook.getActiveWorksheet();
  const headerRange = sheet.getRange("A1:E1");
  const firstSeriesRange = sheet.getRange("A2:E2");
  const secondSeriesRange = sheet.getRange("A3:E3");

  // Create the chart.
  const lineChart = sheet.addChart(ExcelScript.ChartType.line, headerRange);

  // Add the first chart series.
  const firstSeries = lineChart.addChartSeries();
  firstSeries.setXAxisValues(headerRange);
  firstSeries.setValues(firstSeriesRange);

  // Add the second chart series.
  const secondSeries = lineChart.addChartSeries();
  secondSeries.setXAxisValues(headerRange);
  secondSeries.setValues(secondSeriesRange);
}

delete()

Deletes the chart object.

delete(): void;

Returns

void

getAxes()

Represents chart axes.

getAxes(): ChartAxes;

Returns

ExcelScript.ChartAxes

getCategoryLabelLevel()

Specifies a chart category label level enumeration constant, referring to the level of the source category labels.

getCategoryLabelLevel(): number;

Returns

number

getChartType()

Specifies the type of the chart. See ExcelScript.ChartType for details.

getChartType(): ChartType;

Returns

ExcelScript.ChartType

getDataLabels()

Represents the data labels on the chart.

getDataLabels(): ChartDataLabels;

Returns

ExcelScript.ChartDataLabels

getDataTable()

Gets the data table on the chart. If the chart doesn't allow a data table, then this method returns undefined.

getDataTable(): ChartDataTable;

Returns

ExcelScript.ChartDataTable

getDisplayBlanksAs()

Specifies the way that blank cells are plotted on a chart.

getDisplayBlanksAs(): ChartDisplayBlanksAs;

Returns

ExcelScript.ChartDisplayBlanksAs

getFormat()

Encapsulates the format properties for the chart area.

getFormat(): ChartAreaFormat;

Returns

ExcelScript.ChartAreaFormat

getHeight()

Specifies the height, in points, of the chart object.

getHeight(): number;

Returns

number

getId()

The unique ID of chart.

getId(): string;

Returns

string

getImage(width, height, fittingMode)

Renders the chart as a base64-encoded image by scaling the chart to fit the specified dimensions. The aspect ratio is preserved as part of the resizing.

getImage(
            width?: number,
            height?: number,
            fittingMode?: ImageFittingMode
        ): string;

Parameters

width: number

Optional. The desired width of the resulting image.

height: number

Optional. The desired height of the resulting image.

fittingMode: ExcelScript.ImageFittingMode

Optional. The method used to scale the chart to the specified dimensions (if both height and width are set).

Returns

string

Examples

/**
 * This script returns an image of the first chart in the first worksheet.
 * That image is 600x400 pixels and the chart will be 
 * stretched to fill those dimensions.
 * The returned image can be used in a Power Automate flow.
 */
function main(workbook: ExcelScript.Workbook): string {
  // Get the first chart in the first worksheet.
  const firstSheet = workbook.getFirstWorksheet();
  const firstChart = firstSheet.getCharts()[0];

  // Get an image of the chart as a base64-encoded string.
  const base64String = firstChart.getImage(
    600, /* Width */
    400, /* Height */
    ExcelScript.ImageFittingMode.fill /* Fill to match the dimensions. */
  );

  return base64String;
}

getLeft()

The distance, in points, from the left side of the chart to the worksheet origin.

getLeft(): number;

Returns

number

getLegend()

Represents the legend for the chart.

getLegend(): ChartLegend;

Returns

ExcelScript.ChartLegend

getName()

Specifies the name of a chart object.

getName(): string;

Returns

string

getPivotOptions()

Encapsulates the options for a pivot chart.

getPivotOptions(): ChartPivotOptions;

Returns

ExcelScript.ChartPivotOptions

getPlotArea()

Represents the plot area for the chart.

getPlotArea(): ChartPlotArea;

Returns

ExcelScript.ChartPlotArea

getPlotBy()

Specifies the way columns or rows are used as data series on the chart.

getPlotBy(): ChartPlotBy;

Returns

ExcelScript.ChartPlotBy

Examples

/**
 * This sample performs the "Switch Row/Column" action on a chart named "ColumnClusteredChart".
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get an existing chart named "ColumnClusteredChart".
  let columnClusteredChart = selectedSheet.getChart("ColumnClusteredChart");
  
  // Switch the row and column for the chart's data source.
  if (columnClusteredChart.getPlotBy() === ExcelScript.ChartPlotBy.columns) {
    // If the chart is grouped by columns, switch it to rows.
    columnClusteredChart.setPlotBy(ExcelScript.ChartPlotBy.rows);
  } else {
    // If the chart is grouped by rows, switch it to columns.
    columnClusteredChart.setPlotBy(ExcelScript.ChartPlotBy.columns);
  }
}

getPlotVisibleOnly()

True if only visible cells are plotted. False if both visible and hidden cells are plotted.

getPlotVisibleOnly(): boolean;

Returns

boolean

getSeries()

Represents either a single series or collection of series in the chart.

getSeries(): ChartSeries[];

Returns

ExcelScript.ChartSeries[]

Examples

/**
 * This sample sets the overlap of the columns in a chart named "ColumnClusteredChart".
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get an existing chart named "ColumnClusteredChart".
  let chart = selectedSheet.getChart("ColumnClusteredChart");

  // Set the overlap of every column of each series within a category.
  let seriesList = chart.getSeries();
  seriesList.forEach((series) => {
    // An overlap of 25 means the columns have 25% of their length overlapping with the adjacent columns in the same category.
    series.setOverlap(25);
  });
}

getSeriesNameLevel()

Specifies a chart series name level enumeration constant, referring to the level of the source series names.

getSeriesNameLevel(): number;

Returns

number

getShowAllFieldButtons()

Specifies whether to display all field buttons on a PivotChart.

getShowAllFieldButtons(): boolean;

Returns

boolean

getShowDataLabelsOverMaximum()

Specifies whether to show the data labels when the value is greater than the maximum value on the value axis. If the value axis becomes smaller than the size of the data points, you can use this property to set whether to show the data labels. This property applies to 2-D charts only.

getShowDataLabelsOverMaximum(): boolean;

Returns

boolean

getStyle()

Specifies the chart style for the chart.

getStyle(): number;

Returns

number

getTitle()

Represents the title of the specified chart, including the text, visibility, position, and formatting of the title.

getTitle(): ChartTitle;

Returns

ExcelScript.ChartTitle

getTop()

Specifies the distance, in points, from the top edge of the object to the top of row 1 (on a worksheet) or the top of the chart area (on a chart).

getTop(): number;

Returns

number

getWidth()

Specifies the width, in points, of the chart object.

getWidth(): number;

Returns

number

getWorksheet()

The worksheet containing the current chart.

getWorksheet(): Worksheet;

Returns

ExcelScript.Worksheet

setCategoryLabelLevel(categoryLabelLevel)

Specifies a chart category label level enumeration constant, referring to the level of the source category labels.

setCategoryLabelLevel(categoryLabelLevel: number): void;

Parameters

categoryLabelLevel: number

Returns

void

setChartType(chartType)

Specifies the type of the chart. See ExcelScript.ChartType for details.

setChartType(chartType: ChartType): void;

Parameters

chartType: ExcelScript.ChartType

Returns

void

setData(sourceData, seriesBy)

Resets the source data for the chart.

setData(sourceData: Range, seriesBy?: ChartSeriesBy): void;

Parameters

sourceData: ExcelScript.Range

The range object corresponding to the source data.

seriesBy: ExcelScript.ChartSeriesBy

Specifies the way columns or rows are used as data series on the chart. Can be one of the following: Auto (default), Rows, and Columns. See ExcelScript.ChartSeriesBy for details.

Returns

void

setDisplayBlanksAs(displayBlanksAs)

Specifies the way that blank cells are plotted on a chart.

setDisplayBlanksAs(displayBlanksAs: ChartDisplayBlanksAs): void;

Parameters

displayBlanksAs: ExcelScript.ChartDisplayBlanksAs

Returns

void

setHeight(height)

Specifies the height, in points, of the chart object.

setHeight(height: number): void;

Parameters

height: number

Returns

void

setLeft(left)

The distance, in points, from the left side of the chart to the worksheet origin.

setLeft(left: number): void;

Parameters

left: number

Returns

void

setName(name)

Specifies the name of a chart object.

setName(name: string): void;

Parameters

name: string

Returns

void

Examples

/**
 * This sample creates a column-clustered chart based on the current worksheet's data.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get the data range.
  let range = selectedSheet.getUsedRange();

  // Insert a chart using the data on the current worksheet.
  let chart = selectedSheet.addChart(ExcelScript.ChartType.columnClustered, range);

  // Name the chart for easy access in other scripts.
  chart.setName("ColumnChart");
}

setPlotBy(plotBy)

Specifies the way columns or rows are used as data series on the chart.

setPlotBy(plotBy: ChartPlotBy): void;

Parameters

plotBy: ExcelScript.ChartPlotBy

Returns

void

Examples

/**
 * This sample performs the "Switch Row/Column" action on a chart named "ColumnClusteredChart".
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();

  // Get an existing chart named "ColumnClusteredChart".
  let columnClusteredChart = selectedSheet.getChart("ColumnClusteredChart");
  
  // Switch the row and column for the chart's data source.
  if (columnClusteredChart.getPlotBy() === ExcelScript.ChartPlotBy.columns) {
    // If the chart is grouped by columns, switch it to rows.
    columnClusteredChart.setPlotBy(ExcelScript.ChartPlotBy.rows);
  } else {
    // If the chart is grouped by rows, switch it to columns.
    columnClusteredChart.setPlotBy(ExcelScript.ChartPlotBy.columns);
  }
}

setPlotVisibleOnly(plotVisibleOnly)

True if only visible cells are plotted. False if both visible and hidden cells are plotted.

setPlotVisibleOnly(plotVisibleOnly: boolean): void;

Parameters

plotVisibleOnly: boolean

Returns

void

setPosition(startCell, endCell)

Positions the chart relative to cells on the worksheet.

setPosition(startCell: Range | string, endCell?: Range | string): void;

Parameters

startCell: ExcelScript.Range | string

The start cell. This is where the chart will be moved to. The start cell is the top-left or top-right cell, depending on the user's right-to-left display settings.

endCell: ExcelScript.Range | string

Optional. The end cell. If specified, the chart's width and height will be set to fully cover up this cell/range.

Returns

void

Examples

/**
 * This sample moves an existing chart to a specific place on the worksheet.
 */
function main(workbook: ExcelScript.Workbook) {
  // Get the current worksheet.
  let selectedSheet = workbook.getActiveWorksheet();
  
  // Get an existing chart named "ColumnChart".
  let chart = selectedSheet.getChart("ColumnChart");

  // Place the chart over the range "F1:L13".
  chart.setPosition("F1", "L13");
}

setSeriesNameLevel(seriesNameLevel)

Specifies a chart series name level enumeration constant, referring to the level of the source series names.

setSeriesNameLevel(seriesNameLevel: number): void;

Parameters

seriesNameLevel: number

Returns

void

setShowAllFieldButtons(showAllFieldButtons)

Specifies whether to display all field buttons on a PivotChart.

setShowAllFieldButtons(showAllFieldButtons: boolean): void;

Parameters

showAllFieldButtons: boolean

Returns

void

setShowDataLabelsOverMaximum(showDataLabelsOverMaximum)

setShowDataLabelsOverMaximum(showDataLabelsOverMaximum: boolean): void;

Parameters

showDataLabelsOverMaximum: boolean

Returns

void

setStyle(style)

Specifies the chart style for the chart.

setStyle(style: number): void;

Parameters

style: number

Returns

void

setTop(top)

Specifies the distance, in points, from the top edge of the object to the top of row 1 (on a worksheet) or the top of the chart area (on a chart).

setTop(top: number): void;

Parameters

top: number

Returns

void

setWidth(width)

Specifies the width, in points, of the chart object.

setWidth(width: number): void;

Parameters

width: number

Returns

void