excel.chart.yml

### YamlMime:TSType
name: Excel.Chart
uid: 'excel!Excel.Chart:class'
package: excel!
fullName: Excel.Chart
summary: >-
  Represents a chart object in a workbook. To learn more about the chart object model, see [Work with charts using the
  Excel JavaScript API](https://learn.microsoft.com/office/dev/add-ins/excel/excel-add-ins-charts)<!-- -->.
remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
isPreview: false
isDeprecated: false
type: class
properties:
  - name: axes
    uid: 'excel!Excel.Chart#axes:member'
    package: excel!
    fullName: axes
    summary: Represents chart axes.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly axes: Excel.ChartAxes;'
      return:
        type: '<xref uid="excel!Excel.ChartAxes:class" />'
  - name: context
    uid: 'excel!Excel.Chart#context:member'
    package: excel!
    fullName: context
    summary: >-
      The request context associated with the object. This connects the add-in's process to the Office host
      application's process.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'context: RequestContext;'
      return:
        type: '<xref uid="excel!Excel.RequestContext:class" />'
  - name: dataLabels
    uid: 'excel!Excel.Chart#dataLabels:member'
    package: excel!
    fullName: dataLabels
    summary: Represents the data labels on the chart.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly dataLabels: Excel.ChartDataLabels;'
      return:
        type: '<xref uid="excel!Excel.ChartDataLabels:class" />'
  - name: format
    uid: 'excel!Excel.Chart#format:member'
    package: excel!
    fullName: format
    summary: Encapsulates the format properties for the chart area.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly format: Excel.ChartAreaFormat;'
      return:
        type: '<xref uid="excel!Excel.ChartAreaFormat:class" />'
  - name: height
    uid: 'excel!Excel.Chart#height:member'
    package: excel!
    fullName: height
    summary: 'Specifies the height, in points, of the chart object.'
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'height: number;'
      return:
        type: number
  - name: left
    uid: 'excel!Excel.Chart#left:member'
    package: excel!
    fullName: left
    summary: 'The distance, in points, from the left side of the chart to the worksheet origin.'
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'left: number;'
      return:
        type: number
  - name: legend
    uid: 'excel!Excel.Chart#legend:member'
    package: excel!
    fullName: legend
    summary: Represents the legend for the chart.
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // Set to show legend of Chart1 and make it on top of the chart.
      await Excel.run(async (context) => { 
          const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
          chart.legend.visible = true;
          chart.legend.position = "Top"; 
          chart.legend.overlay = false; 
          await context.sync()
          
          console.log("Legend Shown ");
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly legend: Excel.ChartLegend;'
      return:
        type: '<xref uid="excel!Excel.ChartLegend:class" />'
  - name: name
    uid: 'excel!Excel.Chart#name:member'
    package: excel!
    fullName: name
    summary: Specifies the name of a chart object.
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // 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.
      await Excel.run(async (context) => { 
          const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
          chart.name = "New Name";
          chart.top = 100;
          chart.left = 100;
          chart.height = 200;
          chart.width = 200;
          await context.sync(); 
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'name: string;'
      return:
        type: string
  - name: series
    uid: 'excel!Excel.Chart#series:member'
    package: excel!
    fullName: series
    summary: Represents either a single series or collection of series in the chart.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly series: Excel.ChartSeriesCollection;'
      return:
        type: '<xref uid="excel!Excel.ChartSeriesCollection:class" />'
  - name: title
    uid: 'excel!Excel.Chart#title:member'
    package: excel!
    fullName: title
    summary: >-
      Represents the title of the specified chart, including the text, visibility, position, and formatting of the
      title.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly title: Excel.ChartTitle;'
      return:
        type: '<xref uid="excel!Excel.ChartTitle:class" />'
  - name: top
    uid: 'excel!Excel.Chart#top:member'
    package: excel!
    fullName: top
    summary: >-
      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).
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'top: number;'
      return:
        type: number
  - name: width
    uid: 'excel!Excel.Chart#width:member'
    package: excel!
    fullName: width
    summary: 'Specifies the width, in points, of the chart object.'
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'width: number;'
      return:
        type: number
  - name: worksheet
    uid: 'excel!Excel.Chart#worksheet:member'
    package: excel!
    fullName: worksheet
    summary: The worksheet containing the current chart.
    remarks: '\[ [API set: ExcelApi 1.2](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'readonly worksheet: Excel.Worksheet;'
      return:
        type: '<xref uid="excel!Excel.Worksheet:class" />'
methods:
  - name: delete()
    uid: 'excel!Excel.Chart#delete:member(1)'
    package: excel!
    fullName: delete()
    summary: Deletes the chart object.
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => { 
          const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
          chart.delete();
          await context.sync(); 
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'delete(): void;'
      return:
        type: void
        description: ''
  - name: 'getImage(width, height, fittingMode)'
    uid: 'excel!Excel.Chart#getImage:member(1)'
    package: excel!
    fullName: 'getImage(width, height, fittingMode)'
    summary: >-
      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.
    remarks: |-
      \[ [API set: ExcelApi 1.2](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => { 
          const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
          const image = chart.getImage();
          await context.sync(); 
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        getImage(width?: number, height?: number, fittingMode?: Excel.ImageFittingMode):
        OfficeExtension.ClientResult<string>;
      parameters:
        - id: width
          description: Optional. The desired width of the resulting image.
          type: number
        - id: height
          description: Optional. The desired height of the resulting image.
          type: number
        - id: fittingMode
          description: Optional. The method used to scale the chart to the specified dimensions (if both height and width are set).
          type: '<xref uid="excel!Excel.ImageFittingMode:enum" />'
      return:
        type: '<xref uid="office!OfficeExtension.ClientResult:class" />&lt;string&gt;'
        description: ''
  - name: 'getImage(width, height, fittingModeString)'
    uid: 'excel!Excel.Chart#getImage:member(2)'
    package: excel!
    fullName: 'getImage(width, height, fittingModeString)'
    summary: >-
      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.
    remarks: '\[ [API set: ExcelApi 1.2](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: >-
        getImage(width?: number, height?: number, fittingModeString?: "Fit" | "FitAndCenter" | "Fill"):
        OfficeExtension.ClientResult<string>;
      parameters:
        - id: width
          description: Optional. The desired width of the resulting image.
          type: number
        - id: height
          description: Optional. The desired height of the resulting image.
          type: number
        - id: fittingModeString
          description: Optional. The method used to scale the chart to the specified dimensions (if both height and width are set).
          type: '"Fit" | "FitAndCenter" | "Fill"'
      return:
        type: '<xref uid="office!OfficeExtension.ClientResult:class" />&lt;string&gt;'
        description: ''
  - name: load(options)
    uid: 'excel!Excel.Chart#load:member(1)'
    package: excel!
    fullName: load(options)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'load(options?: Excel.Interfaces.ChartLoadOptions): Excel.Chart;'
      parameters:
        - id: options
          description: Provides options for which properties of the object to load.
          type: '<xref uid="excel!Excel.Interfaces.ChartLoadOptions:interface" />'
      return:
        type: '<xref uid="excel!Excel.Chart:class" />'
        description: ''
  - name: load(propertyNames)
    uid: 'excel!Excel.Chart#load:member(2)'
    package: excel!
    fullName: load(propertyNames)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'load(propertyNames?: string | string[]): Excel.Chart;'
      parameters:
        - id: propertyNames
          description: A comma-delimited string or an array of strings that specify the properties to load.
          type: 'string | string[]'
      return:
        type: '<xref uid="excel!Excel.Chart:class" />'
        description: |-


          #### Examples

          ```TypeScript
          // Get a chart named "Chart1".
          await Excel.run(async (context) => { 
              const chart = context.workbook.worksheets.getItem("Sheet1").charts.getItem("Chart1");    
              chart.load('name');
              await context.sync();

              console.log(chart.name);
          });
          ```
  - name: load(propertyNamesAndPaths)
    uid: 'excel!Excel.Chart#load:member(3)'
    package: excel!
    fullName: load(propertyNamesAndPaths)
    summary: >-
      Queues up a command to load the specified properties of the object. You must call `context.sync()` before reading
      the properties.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: |-
        load(propertyNamesAndPaths?: {
                    select?: string;
                    expand?: string;
                }): Excel.Chart;
      parameters:
        - id: propertyNamesAndPaths
          description: >-
            `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.
          type: |-
            {
                        select?: string;
                        expand?: string;
                    }
      return:
        type: '<xref uid="excel!Excel.Chart:class" />'
        description: ''
  - name: 'set(properties, options)'
    uid: 'excel!Excel.Chart#set:member(1)'
    package: excel!
    fullName: 'set(properties, options)'
    summary: >-
      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.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'set(properties: Interfaces.ChartUpdateData, options?: OfficeExtension.UpdateOptions): void;'
      parameters:
        - id: properties
          description: >-
            A JavaScript object with properties that are structured isomorphically to the properties of the object on
            which the method is called.
          type: '<xref uid="excel!Excel.Interfaces.ChartUpdateData:interface" />'
        - id: options
          description: Provides an option to suppress errors if the properties object tries to set any read-only properties.
          type: '<xref uid="office!OfficeExtension.UpdateOptions:interface" />'
      return:
        type: void
        description: ''
  - name: set(properties)
    uid: 'excel!Excel.Chart#set:member(2)'
    package: excel!
    fullName: set(properties)
    summary: 'Sets multiple properties on the object at the same time, based on an existing loaded object.'
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'set(properties: Excel.Chart): void;'
      parameters:
        - id: properties
          description: ''
          type: '<xref uid="excel!Excel.Chart:class" />'
      return:
        type: void
        description: ''
  - name: 'setData(sourceData, seriesBy)'
    uid: 'excel!Excel.Chart#setData:member(1)'
    package: excel!
    fullName: 'setData(sourceData, seriesBy)'
    summary: Resets the source data for the chart.
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      // Set the sourceData to be the range at "A1:B4" and seriesBy to be "Columns".
      await Excel.run(async (context) => {
          const sheet = context.workbook.worksheets.getItem("Sheet1");
          const chart = sheet.charts.getItem("Chart1");
          const sourceData = sheet.getRange("A1:B4");
          chart.setData(sourceData, "Columns");
          await context.sync();
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'setData(sourceData: Range, seriesBy?: Excel.ChartSeriesBy): void;'
      parameters:
        - id: sourceData
          description: The range object corresponding to the source data.
          type: '<xref uid="excel!Excel.Range:class" />'
        - id: seriesBy
          description: >-
            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.
          type: '<xref uid="excel!Excel.ChartSeriesBy:enum" />'
      return:
        type: void
        description: ''
  - name: 'setData(sourceData, seriesByString)'
    uid: 'excel!Excel.Chart#setData:member(2)'
    package: excel!
    fullName: 'setData(sourceData, seriesByString)'
    summary: Resets the source data for the chart.
    remarks: '\[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]'
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'setData(sourceData: Range, seriesByString?: "Auto" | "Columns" | "Rows"): void;'
      parameters:
        - id: sourceData
          description: The range object corresponding to the source data.
          type: '<xref uid="excel!Excel.Range:class" />'
        - id: seriesByString
          description: >-
            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.
          type: '"Auto" | "Columns" | "Rows"'
      return:
        type: void
        description: ''
  - name: 'setPosition(startCell, endCell)'
    uid: 'excel!Excel.Chart#setPosition:member(1)'
    package: excel!
    fullName: 'setPosition(startCell, endCell)'
    summary: Positions the chart relative to cells on the worksheet.
    remarks: |-
      \[ [API set: ExcelApi 1.1](/javascript/api/requirement-sets/excel/excel-api-requirement-sets) \]

      #### Examples

      ```TypeScript
      await Excel.run(async (context) => { 
          const sheetName = "Charts";
          const rangeSelection = "A1:B4";
          const range = context.workbook.worksheets.getItem(sheetName).getRange(rangeSelection);
          const sourceData = sheetName + "!" + "A1:B4";
          const chart = context.workbook.worksheets.getItem(sheetName).charts.add("pie", range, "auto");
          chart.width = 500;
          chart.height = 300;
          chart.setPosition("C2", null);
          await context.sync(); 
      });
      ```
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'setPosition(startCell: Range | string, endCell?: Range | string): void;'
      parameters:
        - id: startCell
          description: >-
            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.
          type: '<xref uid="excel!Excel.Range:class" /> | string'
        - id: endCell
          description: >-
            Optional. The end cell. If specified, the chart's width and height will be set to fully cover up this
            cell/range.
          type: '<xref uid="excel!Excel.Range:class" /> | string'
      return:
        type: void
        description: ''
  - name: toJSON()
    uid: 'excel!Excel.Chart#toJSON:member(1)'
    package: excel!
    fullName: toJSON()
    summary: >-
      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.
    remarks: ''
    isPreview: false
    isDeprecated: false
    syntax:
      content: 'toJSON(): Excel.Interfaces.ChartData;'
      return:
        type: '<xref uid="excel!Excel.Interfaces.ChartData:interface" />'
        description: ''
extends: '<xref uid="office!OfficeExtension.ClientObject:class" />'