ExcelScript.Chart interface

Activates the chart in the Excel UI.

activate(): void;

Returns

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

Returns

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);
}

Deletes the chart object.

delete(): void;

Returns

Represents chart axes.

getAxes(): ChartAxes;

Returns

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

getCategoryLabelLevel(): number;

Returns

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

getChartType(): ChartType;

Returns

Represents the data labels on the chart.

getDataLabels(): ChartDataLabels;

Returns

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

getDataTable(): ChartDataTable;

Returns

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

getDisplayBlanksAs(): ChartDisplayBlanksAs;

Returns

Encapsulates the format properties for the chart area.

getFormat(): ChartAreaFormat;

Returns

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

getHeight(): number;

Returns

The unique ID of chart.

getId(): string;

Returns

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

Returns

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;
}

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

getLeft(): number;

Returns

Represents the legend for the chart.

getLegend(): ChartLegend;

Returns

Specifies the name of a chart object.

getName(): string;

Returns

Encapsulates the options for a pivot chart.

getPivotOptions(): ChartPivotOptions;

Returns

Represents the plot area for the chart.

getPlotArea(): ChartPlotArea;

Returns

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

getPlotBy(): ChartPlotBy;

Returns

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);
  }
}

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

getPlotVisibleOnly(): boolean;

Returns

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

getSeries(): ChartSeries[];

Returns

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);
  });
}

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

getSeriesNameLevel(): number;

Returns

Specifies whether to display all field buttons on a PivotChart.

getShowAllFieldButtons(): boolean;

Returns

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

Specifies the chart style for the chart.

getStyle(): number;

Returns

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

getTitle(): ChartTitle;

Returns

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

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

getWidth(): number;

Returns

The worksheet containing the current chart.

getWorksheet(): Worksheet;

Returns

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

setCategoryLabelLevel(categoryLabelLevel: number): void;

Parameters

Returns

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

setChartType(chartType: ChartType): void;

Parameters

Returns

Resets the source data for the chart.

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

Parameters

Returns

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

setDisplayBlanksAs(displayBlanksAs: ChartDisplayBlanksAs): void;

Parameters

Returns

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

setHeight(height: number): void;

Parameters

Returns

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

setLeft(left: number): void;

Parameters

Returns

Specifies the name of a chart object.

setName(name: string): void;

Parameters

Returns

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");
}

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

setPlotBy(plotBy: ChartPlotBy): void;

Parameters

Returns

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);
  }
}

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

setPlotVisibleOnly(plotVisibleOnly: boolean): void;

Parameters

Returns

Positions the chart relative to cells on the worksheet.

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

Parameters

Returns

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");
}

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

setSeriesNameLevel(seriesNameLevel: number): void;

Parameters

Returns

Specifies whether to display all field buttons on a PivotChart.

setShowAllFieldButtons(showAllFieldButtons: boolean): void;

Parameters

Returns

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.

setShowDataLabelsOverMaximum(showDataLabelsOverMaximum: boolean): void;

Parameters

Returns

Specifies the chart style for the chart.

setStyle(style: number): void;

Parameters

Returns

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

Returns

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

setWidth(width: number): void;

Parameters

Returns