Excel.Chart class

Represents a chart object in a workbook. To learn more about the Chart object model, see Work with charts using the Excel JavaScript API.

[ API set: ExcelApi 1.1 ]

Extends
OfficeExtension.ClientObject

Properties

axes

Represents chart axes. Read-only.

[ API set: ExcelApi 1.1 ]

categoryLabelLevel

Returns or sets a ChartCategoryLabelLevel enumeration constant referring to the level of where the category labels are being sourced from. Read/Write.

[ API set: ExcelApi 1.8 ]

chartType

Represents the type of the chart. See Excel.ChartType for details.

[ API set: ExcelApi 1.7 ]

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

dataLabels

Represents the datalabels on the chart. Read-only.

[ API set: ExcelApi 1.1 ]

displayBlanksAs

Returns or sets the way that blank cells are plotted on a chart. Read/Write.

[ API set: ExcelApi 1.8 ]

format

Encapsulates the format properties for the chart area. Read-only.

[ API set: ExcelApi 1.1 ]

height

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

[ API set: ExcelApi 1.1 ]

id

The unique id of chart. Read-only.

[ API set: ExcelApi 1.7 ]

left

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

[ API set: ExcelApi 1.1 ]

legend

Represents the legend for the chart. Read-only.

[ API set: ExcelApi 1.1 ]

name

Represents the name of a chart object.

[ API set: ExcelApi 1.1 ]

pivotOptions

Encapsulates the options for a pivot chart. Read-only.

[ API set: ExcelApi 1.9 ]

plotArea

Represents the plotArea for the chart.

[ API set: ExcelApi 1.8 ]

plotBy

Returns or sets the way columns or rows are used as data series on the chart. Read/Write.

[ API set: ExcelApi 1.8 ]

plotVisibleOnly

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

[ API set: ExcelApi 1.8 ]

series

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

[ API set: ExcelApi 1.1 ]

seriesNameLevel

Returns or sets a ChartSeriesNameLevel enumeration constant referring to the level of where the series names are being sourced from. Read/Write.

[ API set: ExcelApi 1.8 ]

showAllFieldButtons

Represents whether to display all field buttons on a PivotChart.

[ API set: ExcelApi 1.7 ]

showDataLabelsOverMaximum

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

[ API set: ExcelApi 1.8 ]

style

Returns or sets the chart style for the chart. Read/Write.

[ API set: ExcelApi 1.8 ]

title

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

[ API set: ExcelApi 1.1 ]

top

Represents 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).

[ API set: ExcelApi 1.1 ]

width

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

[ API set: ExcelApi 1.1 ]

worksheet

The worksheet containing the current chart. Read-only.

[ API set: ExcelApi 1.2 ]

Methods

activate()

Activates the chart in the Excel UI.

[ API set: ExcelApi 1.9 ]

delete()

Deletes the chart object.

[ API set: ExcelApi 1.1 ]

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.

[ API set: ExcelApi 1.2 ]

getImage(width, height, fittingModeString)

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.

[ API set: ExcelApi 1.2 ]

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

setData(sourceData, seriesBy)

Resets the source data for the chart.

[ API set: ExcelApi 1.1 ]

setData(sourceData, seriesByString)

Resets the source data for the chart.

[ API set: ExcelApi 1.1 ]

setPosition(startCell, endCell)

Positions the chart relative to cells on the worksheet.

[ API set: ExcelApi 1.1 ]

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.Chart object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.ChartData) that contains shallow copies of any loaded child properties from the original object.

Events

onActivated

Occurs when the chart is activated.

[ API set: ExcelApi 1.8 ]

onDeactivated

Occurs when the chart is deactivated.

[ API set: ExcelApi 1.8 ]

Property Details

axes

Represents chart axes. Read-only.

[ API set: ExcelApi 1.1 ]

readonly axes: Excel.ChartAxes;

Property Value

categoryLabelLevel

Returns or sets a ChartCategoryLabelLevel enumeration constant referring to the level of where the category labels are being sourced from. Read/Write.

[ API set: ExcelApi 1.8 ]

categoryLabelLevel: number;

Property Value

number

chartType

Represents the type of the chart. See Excel.ChartType for details.

[ API set: ExcelApi 1.7 ]

chartType: Excel.ChartType | "Invalid" | "ColumnClustered" | "ColumnStacked" | "ColumnStacked100" | "3DColumnClustered" | "3DColumnStacked" | "3DColumnStacked100" | "BarClustered" | "BarStacked" | "BarStacked100" | "3DBarClustered" | "3DBarStacked" | "3DBarStacked100" | "LineStacked" | "LineStacked100" | "LineMarkers" | "LineMarkersStacked" | "LineMarkersStacked100" | "PieOfPie" | "PieExploded" | "3DPieExploded" | "BarOfPie" | "XYScatterSmooth" | "XYScatterSmoothNoMarkers" | "XYScatterLines" | "XYScatterLinesNoMarkers" | "AreaStacked" | "AreaStacked100" | "3DAreaStacked" | "3DAreaStacked100" | "DoughnutExploded" | "RadarMarkers" | "RadarFilled" | "Surface" | "SurfaceWireframe" | "SurfaceTopView" | "SurfaceTopViewWireframe" | "Bubble" | "Bubble3DEffect" | "StockHLC" | "StockOHLC" | "StockVHLC" | "StockVOHLC" | "CylinderColClustered" | "CylinderColStacked" | "CylinderColStacked100" | "CylinderBarClustered" | "CylinderBarStacked" | "CylinderBarStacked100" | "CylinderCol" | "ConeColClustered" | "ConeColStacked" | "ConeColStacked100" | "ConeBarClustered" | "ConeBarStacked" | "ConeBarStacked100" | "ConeCol" | "PyramidColClustered" | "PyramidColStacked" | "PyramidColStacked100" | "PyramidBarClustered" | "PyramidBarStacked" | "PyramidBarStacked100" | "PyramidCol" | "3DColumn" | "Line" | "3DLine" | "3DPie" | "Pie" | "XYScatter" | "3DArea" | "Area" | "Doughnut" | "Radar" | "Histogram" | "Boxwhisker" | "Pareto" | "RegionMap" | "Treemap" | "Waterfall" | "Sunburst" | "Funnel";

Property Value

Excel.ChartType | "Invalid" | "ColumnClustered" | "ColumnStacked" | "ColumnStacked100" | "3DColumnClustered" | "3DColumnStacked" | "3DColumnStacked100" | "BarClustered" | "BarStacked" | "BarStacked100" | "3DBarClustered" | "3DBarStacked" | "3DBarStacked100" | "LineStacked" | "LineStacked100" | "LineMarkers" | "LineMarkersStacked" | "LineMarkersStacked100" | "PieOfPie" | "PieExploded" | "3DPieExploded" | "BarOfPie" | "XYScatterSmooth" | "XYScatterSmoothNoMarkers" | "XYScatterLines" | "XYScatterLinesNoMarkers" | "AreaStacked" | "AreaStacked100" | "3DAreaStacked" | "3DAreaStacked100" | "DoughnutExploded" | "RadarMarkers" | "RadarFilled" | "Surface" | "SurfaceWireframe" | "SurfaceTopView" | "SurfaceTopViewWireframe" | "Bubble" | "Bubble3DEffect" | "StockHLC" | "StockOHLC" | "StockVHLC" | "StockVOHLC" | "CylinderColClustered" | "CylinderColStacked" | "CylinderColStacked100" | "CylinderBarClustered" | "CylinderBarStacked" | "CylinderBarStacked100" | "CylinderCol" | "ConeColClustered" | "ConeColStacked" | "ConeColStacked100" | "ConeBarClustered" | "ConeBarStacked" | "ConeBarStacked100" | "ConeCol" | "PyramidColClustered" | "PyramidColStacked" | "PyramidColStacked100" | "PyramidBarClustered" | "PyramidBarStacked" | "PyramidBarStacked100" | "PyramidCol" | "3DColumn" | "Line" | "3DLine" | "3DPie" | "Pie" | "XYScatter" | "3DArea" | "Area" | "Doughnut" | "Radar" | "Histogram" | "Boxwhisker" | "Pareto" | "RegionMap" | "Treemap" | "Waterfall" | "Sunburst" | "Funnel"

context

The request context associated with the object. This connects the add-in's process to the Office host application's process.

context: RequestContext;

Property Value

dataLabels

Represents the datalabels on the chart. Read-only.

[ API set: ExcelApi 1.1 ]

readonly dataLabels: Excel.ChartDataLabels;

Property Value

displayBlanksAs

Returns or sets the way that blank cells are plotted on a chart. Read/Write.

[ API set: ExcelApi 1.8 ]

displayBlanksAs: Excel.ChartDisplayBlanksAs | "NotPlotted" | "Zero" | "Interplotted";

Property Value

Excel.ChartDisplayBlanksAs | "NotPlotted" | "Zero" | "Interplotted"

format

Encapsulates the format properties for the chart area. Read-only.

[ API set: ExcelApi 1.1 ]

readonly format: Excel.ChartAreaFormat;

Property Value

height

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

[ API set: ExcelApi 1.1 ]

height: number;

Property Value

number

id

The unique id of chart. Read-only.

[ API set: ExcelApi 1.7 ]

readonly id: string;

Property Value

string

left

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

[ API set: ExcelApi 1.1 ]

left: number;

Property Value

number

legend

Represents the legend for the chart. Read-only.

[ API set: ExcelApi 1.1 ]

readonly legend: Excel.ChartLegend;

Property Value

name

Represents the name of a chart object.

[ API set: ExcelApi 1.1 ]

name: string;

Property Value

string

Examples

// Rename the chart to new name, resize the chart to 200 points in both height and weight. 
// Move Chart1 to 100 points to the top and left. 
Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    chart.name = "New Name";
    chart.top = 100;
    chart.left = 100;
    chart.height = 200;
    chart.width = 200;
    return ctx.sync(); 
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

pivotOptions

Encapsulates the options for a pivot chart. Read-only.

[ API set: ExcelApi 1.9 ]

readonly pivotOptions: Excel.ChartPivotOptions;

Property Value

plotArea

Represents the plotArea for the chart.

[ API set: ExcelApi 1.8 ]

readonly plotArea: Excel.ChartPlotArea;

Property Value

plotBy

Returns or sets the way columns or rows are used as data series on the chart. Read/Write.

[ API set: ExcelApi 1.8 ]

plotBy: Excel.ChartPlotBy | "Rows" | "Columns";

Property Value

Excel.ChartPlotBy | "Rows" | "Columns"

plotVisibleOnly

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

[ API set: ExcelApi 1.8 ]

plotVisibleOnly: boolean;

Property Value

boolean

series

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

[ API set: ExcelApi 1.1 ]

readonly series: Excel.ChartSeriesCollection;

Property Value

seriesNameLevel

Returns or sets a ChartSeriesNameLevel enumeration constant referring to the level of where the series names are being sourced from. Read/Write.

[ API set: ExcelApi 1.8 ]

seriesNameLevel: number;

Property Value

number

showAllFieldButtons

Represents whether to display all field buttons on a PivotChart.

[ API set: ExcelApi 1.7 ]

showAllFieldButtons: boolean;

Property Value

boolean

showDataLabelsOverMaximum

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

[ API set: ExcelApi 1.8 ]

showDataLabelsOverMaximum: boolean;

Property Value

boolean

style

Returns or sets the chart style for the chart. Read/Write.

[ API set: ExcelApi 1.8 ]

style: number;

Property Value

number

title

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

[ API set: ExcelApi 1.1 ]

readonly title: Excel.ChartTitle;

Property Value

top

Represents 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).

[ API set: ExcelApi 1.1 ]

top: number;

Property Value

number

width

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

[ API set: ExcelApi 1.1 ]

width: number;

Property Value

number

worksheet

The worksheet containing the current chart. Read-only.

[ API set: ExcelApi 1.2 ]

readonly worksheet: Excel.Worksheet;

Property Value

Method Details

activate()

Activates the chart in the Excel UI.

[ API set: ExcelApi 1.9 ]

activate(): void;

Returns

void

delete()

Deletes the chart object.

[ API set: ExcelApi 1.1 ]

delete(): void;

Returns

void

Examples

Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    chart.delete();
    return ctx.sync(); 
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

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.

[ API set: ExcelApi 1.2 ]

getImage(width?: number, height?: number, fittingMode?: Excel.ImageFittingMode): OfficeExtension.ClientResult<string>;

Parameters

width
number

(Optional) The desired width of the resulting image.

height
number

(Optional) The desired height of the resulting image.

fittingMode
Excel.ImageFittingMode

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

Returns

OfficeExtension.ClientResult<string>

Examples

Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    var image = chart.getImage();
    return ctx.sync(); 
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

getImage(width, height, fittingModeString)

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.

[ API set: ExcelApi 1.2 ]

getImage(width?: number, height?: number, fittingModeString?: "Fit" | "FitAndCenter" | "Fill"): OfficeExtension.ClientResult<string>;

Parameters

width
number

(Optional) The desired width of the resulting image.

height
number

(Optional) The desired height of the resulting image.

fittingModeString
"Fit" | "FitAndCenter" | "Fill"

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

Returns

OfficeExtension.ClientResult<string>

load(option)

Queues up a command to load the specified properties of the object. You must call "context.sync()" before reading the properties.

load(option?: Excel.Interfaces.ChartLoadOptions): Excel.Chart;

Parameters

Returns

Remarks

In addition to this signature, this method has the following signatures:

load(option?: string | string[]): Excel.Chart - Where option is a comma-delimited string or an array of strings that specify the properties to load.

load(option?: { select?: string; expand?: string; }): Excel.Chart - Where option.select is a comma-delimited string that specifies the properties to load, and options.expand is a comma-delimited string that specifies the navigation properties to load.

load(option?: { select?: string; expand?: string; top?: number; skip?: number }): Excel.Chart - Only available on collection types. It is similar to the preceding signature. Option.top specifies the maximum number of collection items that can be included in the result. Option.skip specifies the number of items that are to be skipped and not included in the result. If option.top is specified, the result set will start after skipping the specified number of items.

load(propertyNames)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNames?: string | string[]): Excel.Chart;

Parameters

propertyNames
string | string[]

A comma-delimited string or an array of strings that specify the properties to load.

Returns

Examples

// Get a chart named "Chart1"
Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    chart.load('name');
    return ctx.sync().then(function() {
            console.log(chart.name);
    });
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

load(propertyNamesAndPaths)

Queues up a command to load the specified properties of the object. You must call context.sync() before reading the properties.

load(propertyNamesAndPaths?: { select?: string; expand?: string; }): Excel.Chart;

Parameters

propertyNamesAndPaths
{ select?: string; expand?: string; }

Where propertyNamesAndPaths.select is a comma-delimited string that specifies the properties to load, and propertyNamesAndPaths.expand is a comma-delimited string that specifies the navigation properties to load.

Returns

set(properties, options)

Sets multiple properties of an object at the same time. You can pass either a plain object with the appropriate properties, or another API object of the same type.

set(properties: Interfaces.ChartUpdateData, options?: OfficeExtension.UpdateOptions): void;

Parameters

properties
Interfaces.ChartUpdateData

A JavaScript object with properties that are structured isomorphically to the properties of the object on which the method is called.

options
OfficeExtension.UpdateOptions

Provides an option to suppress errors if the properties object tries to set any read-only properties.

Returns

void

Remarks

This method has the following additional signature:

set(properties: Excel.Chart): void

set(properties)

Sets multiple properties on the object at the same time, based on an existing loaded object.

set(properties: Excel.Chart): void;

Parameters

properties
Excel.Chart

Returns

void

setData(sourceData, seriesBy)

Resets the source data for the chart.

[ API set: ExcelApi 1.1 ]

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

Parameters

sourceData
Excel.Range

The range object corresponding to the source data.

seriesBy
Excel.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 Excel.ChartSeriesBy for details.

Returns

void

setData(sourceData, seriesByString)

Resets the source data for the chart.

[ API set: ExcelApi 1.1 ]

setData(sourceData: Range, seriesByString?: "Auto" | "Columns" | "Rows"): void;

Parameters

sourceData
Excel.Range

The range object corresponding to the source data.

seriesByString
"Auto" | "Columns" | "Rows"

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 Excel.ChartSeriesBy for details.

Returns

void

Examples

// Set the sourceData to be "A1:B4" and seriesBy to be "Columns"
Excel.run(function (ctx) { 
    var chart = ctx.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
    var sourceData = "A1:B4";
    chart.setData(sourceData, "Columns");
    return ctx.sync(); 
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

setPosition(startCell, endCell)

Positions the chart relative to cells on the worksheet.

[ API set: ExcelApi 1.1 ]

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

Parameters

startCell
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
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

Excel.run(function (ctx) { 
    var sheetName = "Charts";
    var rangeSelection = "A1:B4";
    var range = ctx.workbook.worksheets.getItem(sheetName).getRange(rangeSelection);
    var sourceData = sheetName + "!" + "A1:B4";
    var chart = ctx.workbook.worksheets.getItem(sheetName).charts.add("pie", range, "auto");
    chart.width = 500;
    chart.height = 300;
    chart.setPosition("C2", null);
    return ctx.sync(); 
}).catch(function(error) {
    console.log("Error: " + error);
    if (error instanceof OfficeExtension.Error) {
        console.log("Debug info: " + JSON.stringify(error.debugInfo));
    }
});

toJSON()

Overrides the JavaScript toJSON() method in order to provide more useful output when an API object is passed to JSON.stringify(). (JSON.stringify, in turn, calls the toJSON method of the object that is passed to it.) Whereas the original Excel.Chart object is an API object, the toJSON method returns a plain JavaScript object (typed as Excel.Interfaces.ChartData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): Excel.Interfaces.ChartData;

Returns

Event Details

onActivated

Occurs when the chart is activated.

[ API set: ExcelApi 1.8 ]

readonly onActivated: OfficeExtension.EventHandlers<Excel.ChartActivatedEventArgs>;

Returns

OfficeExtension.EventHandlers<Excel.ChartActivatedEventArgs>

Examples

Excel.run(function (context){
    var pieChart = context.workbook.worksheets.getActiveWorksheet().charts.getItem("Pie");
    pieChart.onActivated.add(function (event) {
        return Excel.run((context) => {
            console.log("The pie chart is the active chart. ID: " + event.chartId);
            return context.sync();
        });
    });
    return context.sync();
});

onDeactivated

Occurs when the chart is deactivated.

[ API set: ExcelApi 1.8 ]

readonly onDeactivated: OfficeExtension.EventHandlers<Excel.ChartDeactivatedEventArgs>;

Returns

OfficeExtension.EventHandlers<Excel.ChartDeactivatedEventArgs>

Examples

Excel.run(function (context){
    var pieChart = context.workbook.worksheets.getActiveWorksheet().charts.getItem("Pie");
    pieChart.onDeactivated.add(function (event) {
        return Excel.run((context) => {
            console.log("The pie chart is NOT active.");
            return context.sync();
        });
    });
    return context.sync();
});