PowerPoint.Shape class

Returns an Adjustments object that contains adjustment values for all the adjustments in this shape.

readonly adjustments: PowerPoint.Adjustments;

Property Value

Remarks

[ API set: PowerPointApi BETA (PREVIEW ONLY) ]

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

Gets the creation ID of the shape. Returns null if the shape has no creation ID.

readonly creationId: string | null;

Property Value

Remarks

[ API set: PowerPointApi BETA (PREVIEW ONLY) ]

Returns a collection of custom XML parts in the shape.

readonly customXmlParts: PowerPoint.CustomXmlPartCollection;

Property Value

Remarks

[ API set: PowerPointApi 1.7 ]

Returns the fill formatting of this shape.

readonly fill: PowerPoint.ShapeFill;

Property Value

Remarks

[ API set: PowerPointApi 1.4 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Changes the selected shapes fill color to red.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  shapes.items.map((shape) => {
    shape.fill.setSolidColor("red");
  });
  await context.sync();
});

Returns the ShapeGroup associated with the shape. If the shape type isn't group, then this method returns the GeneralException error.

readonly group: PowerPoint.ShapeGroup;

Property Value

Remarks

[ API set: PowerPointApi 1.8 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/group-ungroup-shapes.yaml

await PowerPoint.run(async (context) => {
  // Ungroups the first shape group on the current slide.

  // Get the shapes on the current slide.
  context.presentation.load("slides");
  const slide: PowerPoint.Slide = context.presentation.getSelectedSlides().getItemAt(0);
  slide.load("shapes/items/type,shapes/items/id");
  await context.sync();

  const shapes: PowerPoint.ShapeCollection = slide.shapes;
  const shapeGroups = shapes.items.filter((item) => item.type === PowerPoint.ShapeType.group);
  if (shapeGroups.length === 0) {
    console.warn("No shape groups on the current slide, so nothing to ungroup.");
    return;
  }

  // Ungroup the first grouped shapes.
  const firstGroupId = shapeGroups[0].id;
  const shapeGroupToUngroup = shapes.getItem(firstGroupId);
  shapeGroupToUngroup.group.ungroup();
  await context.sync();

  console.log(`Ungrouped shapes with group ID: ${firstGroupId}`);
});

Specifies the height, in points, of the shape. Throws an InvalidArgument exception when set with a negative value.

height: number;

Property Value

Remarks

[ API set: PowerPointApi 1.4 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

Gets the unique ID of the shape.

readonly id: string;

Property Value

Remarks

[ API set: PowerPointApi 1.3 ]

The distance, in points, from the left side of the shape to the left side of the slide.

left: number;

Property Value

Remarks

[ API set: PowerPointApi 1.4 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

Returns the level of the specified shape.

• A level of 0 means the shape isn't part of a group.

• A level of 1 means the shape is part of a top-level group.

• A level greater than 1 indicates the shape is a nested group.

readonly level: number;

Property Value

Remarks

[ API set: PowerPointApi 1.8 ]

Returns the line formatting of this shape.

readonly lineFormat: PowerPoint.ShapeLineFormat;

Property Value

Remarks

[ API set: PowerPointApi 1.4 ]

Specifies the name of this shape.

name: string;

Property Value

Remarks

[ API set: PowerPointApi 1.4 ]

Returns the parent group of this shape. If the shape isn't part of a group, then this method returns the GeneralException error.

readonly parentGroup: PowerPoint.Shape;

Property Value

Remarks

[ API set: PowerPointApi 1.8 ]

Returns the properties that apply specifically to this placeholder. If the shape type isn't placeholder, then this method returns the GeneralException error.

readonly placeholderFormat: PowerPoint.PlaceholderFormat;

Property Value

Remarks

[ API set: PowerPointApi 1.8 ]

Specifies the rotation, in degrees, of the shape around the z-axis. A positive value indicates clockwise rotation, and a negative value indicates counterclockwise rotation.

rotation: number;

Property Value

Remarks

[ API set: PowerPointApi BETA (PREVIEW ONLY) ]

Returns a collection of tags in the shape.

readonly tags: PowerPoint.TagCollection;

Property Value

Remarks

[ API set: PowerPointApi 1.3 ]

Returns the PowerPoint.TextFrame object of this Shape. Throws an InvalidArgument exception if the shape doesn't support a TextFrame.

readonly textFrame: PowerPoint.TextFrame;

Property Value

Remarks

[ API set: PowerPointApi 1.4 ]

The distance, in points, from the top edge of the shape to the top edge of the slide.

top: number;

Property Value

Remarks

[ API set: PowerPointApi 1.4 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

Returns the type of this shape. See PowerPoint.ShapeType for details.

readonly type: PowerPoint.ShapeType | "Unsupported" | "Image" | "GeometricShape" | "Group" | "Line" | "Table" | "Callout" | "Chart" | "ContentApp" | "Diagram" | "Freeform" | "Graphic" | "Ink" | "Media" | "Model3D" | "Ole" | "Placeholder" | "SmartArt" | "TextBox";

Property Value

Remarks

[ API set: PowerPointApi 1.4 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-shapes-by-type.yaml

// Changes the transparency of every geometric shape in the slide.
await PowerPoint.run(async (context) => {
  // Get the type of shape for every shape in the collection.
  const shapes: PowerPoint.ShapeCollection = context.presentation.slides.getItemAt(0).shapes;
  shapes.load("type");
  await context.sync();

  // Change the shape transparency to be halfway transparent.
  shapes.items.forEach((shape) => {
    if (shape.type === PowerPoint.ShapeType.geometricShape) {
      shape.fill.transparency = 0.5;
    }
  });
  await context.sync();
});

Specifies if the shape is visible.

visible: boolean;

Property Value

Remarks

[ API set: PowerPointApi BETA (PREVIEW ONLY) ]

Specifies the width, in points, of the shape. Throws an InvalidArgument exception when set with a negative value.

width: number;

Property Value

Remarks

[ API set: PowerPointApi 1.4 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/get-set-shapes.yaml

// Arranges the selected shapes in a line from left to right.
await PowerPoint.run(async (context) => {
  const shapes: PowerPoint.ShapeScopedCollection = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();
  let maxHeight = 0;
  shapes.items.map((shape) => {
    shape.load("width,height");
  });
  await context.sync();
  shapes.items.map((shape) => {
    shape.left = currentLeft;
    shape.top = currentTop;
    currentLeft += shape.width;
    if (shape.height > maxHeight) maxHeight = shape.height;
  });
  await context.sync();
  currentLeft = 0;
  if (currentTop > slideHeight - 200) currentTop = 0;
});

Returns the z-order position of the shape, with 0 representing the bottom of the order stack. Every shape on a slide has a unique z-order, but each slide also has a unique z-order stack, so two shapes on separate slides could have the same z-order number.

readonly zOrderPosition: number;

Property Value

Remarks

[ API set: PowerPointApi 1.8 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/binding-to-shapes.yaml

async function changeZOrder(operation: PowerPoint.ShapeZOrder) {
  // Changes the z-order position of the selected shapes.
  return PowerPoint.run(async (context) => {
    const selectedShapes = context.presentation.getSelectedShapes();
    selectedShapes.load();
    await context.sync();

    if (selectedShapes.items.length === 0) {
      console.log("No shapes are selected.");
    } else {
      let direction = 1; // Start with bottom-most (lowest number).

      // Start with top-most when sending to back or bringing forward.

      switch (operation) {
        case PowerPoint.ShapeZOrder.bringForward:

        case PowerPoint.ShapeZOrder.sendToBack:
          direction = -1; // Reverse direction.

          break;
      }

      // Change the z-order position for each of the selected shapes,

      // starting with the bottom-most when bringing to front or sending backward,

      // or top-most when sending to back or bringing forward,

      // so the selected shapes retain their relative z-order positions after they're changed.

      selectedShapes.items
        .sort((a, b) => (a.zOrderPosition - b.zOrderPosition) * direction)
        .forEach((shape) => {
          try {
            const originalZOrderPosition = shape.zOrderPosition;
            shape.setZOrder(operation);

            console.log(`Changed z-order of shape ${shape.id}.`);
          } catch (err) {
            console.log(`Unable to change z-order of shape ${shape.id}. ${err.message}`);
          }
        });

      await context.sync();
    }
  });
}

Deletes the shape from the shape collection. Does nothing if the shape doesn't exist.

delete(): void;

Returns

Remarks

[ API set: PowerPointApi 1.3 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/shapes.yaml

// This function gets the collection of shapes on the first slide,
// and then iterates through them, deleting each one.
await PowerPoint.run(async (context) => {
  const slide: PowerPoint.Slide = context.presentation.slides.getItemAt(0);
  const shapes: PowerPoint.ShapeCollection = slide.shapes;

  // Load all the shapes in the collection without loading their properties.
  shapes.load("items/$none");

  await context.sync();

  shapes.items.forEach((shape) => shape.delete());

  await context.sync();
});

Renders an image of the shape.

getImageAsBase64(options?: PowerPoint.ShapeGetImageOptions): OfficeExtension.ClientResult<string>;

Parameters

Returns

A Base64-encoded string of the shape image in the specified format.

Remarks

[ API set: PowerPointApi BETA (PREVIEW ONLY) ]

Returns the parent PowerPoint.Slide object that holds this Shape. Throws an exception if this shape doesn't belong to a Slide.

getParentSlide(): PowerPoint.Slide;

Returns

Remarks

[ API set: PowerPointApi 1.5 ]

Returns the parent PowerPoint.SlideLayout object that holds this Shape. Throws an exception if this shape doesn't belong to a SlideLayout.

getParentSlideLayout(): PowerPoint.SlideLayout;

Returns

Remarks

[ API set: PowerPointApi 1.5 ]

Returns the parent PowerPoint.SlideLayout object that holds this Shape. If this shape doesn't belong to a SlideLayout, an object with an isNullObject property set to true is returned. For further information, see *OrNullObject methods and properties.

getParentSlideLayoutOrNullObject(): PowerPoint.SlideLayout;

Returns

Remarks

[ API set: PowerPointApi 1.5 ]

Returns the parent PowerPoint.SlideMaster object that holds this Shape. Throws an exception if this shape doesn't belong to a SlideMaster.

getParentSlideMaster(): PowerPoint.SlideMaster;

Returns

Remarks

[ API set: PowerPointApi 1.5 ]

Returns the parent PowerPoint.SlideMaster object that holds this Shape. If this shape doesn't belong to a SlideMaster, an object with an isNullObject property set to true is returned. For further information, see *OrNullObject methods and properties.

getParentSlideMasterOrNullObject(): PowerPoint.SlideMaster;

Returns

Remarks

[ API set: PowerPointApi 1.5 ]

Returns the parent PowerPoint.Slide object that holds this Shape. If this shape doesn't belong to a Slide, an object with an isNullObject property set to true is returned. For further information, see *OrNullObject methods and properties.

getParentSlideOrNullObject(): PowerPoint.Slide;

Returns

Remarks

[ API set: PowerPointApi 1.5 ]

Returns the Table object if this shape is a table.

getTable(): PowerPoint.Table;

Returns

Remarks

[ API set: PowerPointApi 1.8 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/add-modify-tables.yaml

// Gets the table from a shape.
await PowerPoint.run(async (context) => {
  const shapes = context.presentation.getSelectedShapes();
  const shapeCount = shapes.getCount();
  shapes.load("items");
  await context.sync();

  if (shapeCount.value > 0) {
    const shape = shapes.getItemAt(0);
    shape.load("type");
    await context.sync();

    // The shape type can indicate whether the shape is a table.
    const isTable = shape.type === PowerPoint.ShapeType.table;

    if (isTable) {
      // Get the Table object for the Shape which is a table.
      const table = shape.getTable();
      table.load();
      await context.sync();

      // Get the Table row and column count.
      console.log("Table RowCount: " + table.rowCount + " and columnCount: " + table.columnCount);
    } else console.log("Selected shape isn't table.");
  } else console.log("No shape selected.");
});

Returns the PowerPoint.TextFrame object of this Shape. If the shape doesn't support a TextFrame, an object with an isNullObject property set to true is returned. For further information, see *OrNullObject methods and properties.

getTextFrameOrNullObject(): PowerPoint.TextFrame;

Returns

Remarks

[ API set: PowerPointApi BETA (PREVIEW ONLY) ]

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

load(options?: PowerPoint.Interfaces.ShapeLoadOptions): PowerPoint.Shape;

Parameters

Returns

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[]): PowerPoint.Shape;

Parameters

Returns

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;
        }): PowerPoint.Shape;

Parameters

Returns

Sets a hyperlink on this Shape with the specified options. This will delete any existing hyperlink on this Shape.

setHyperlink(options?: PowerPoint.HyperlinkAddOptions): PowerPoint.Hyperlink;

Parameters

Returns

The newly created PowerPoint.Hyperlink object.

Remarks

[ API set: PowerPointApi BETA (PREVIEW ONLY) ]

Moves the specified shape up or down the collection's z-order, which shifts it in front of or behind other shapes.

setZOrder(position: PowerPoint.ShapeZOrder): void;

Parameters

Returns

Remarks

[ API set: PowerPointApi 1.8 ]

Examples

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/powerpoint/shapes/binding-to-shapes.yaml

async function changeZOrder(operation: PowerPoint.ShapeZOrder) {
  // Changes the z-order position of the selected shapes.
  return PowerPoint.run(async (context) => {
    const selectedShapes = context.presentation.getSelectedShapes();
    selectedShapes.load();
    await context.sync();

    if (selectedShapes.items.length === 0) {
      console.log("No shapes are selected.");
    } else {
      let direction = 1; // Start with bottom-most (lowest number).

      // Start with top-most when sending to back or bringing forward.

      switch (operation) {
        case PowerPoint.ShapeZOrder.bringForward:

        case PowerPoint.ShapeZOrder.sendToBack:
          direction = -1; // Reverse direction.

          break;
      }

      // Change the z-order position for each of the selected shapes,

      // starting with the bottom-most when bringing to front or sending backward,

      // or top-most when sending to back or bringing forward,

      // so the selected shapes retain their relative z-order positions after they're changed.

      selectedShapes.items
        .sort((a, b) => (a.zOrderPosition - b.zOrderPosition) * direction)
        .forEach((shape) => {
          try {
            const originalZOrderPosition = shape.zOrderPosition;
            shape.setZOrder(operation);

            console.log(`Changed z-order of shape ${shape.id}.`);
          } catch (err) {
            console.log(`Unable to change z-order of shape ${shape.id}. ${err.message}`);
          }
        });

      await context.sync();
    }
  });
}

Moves the specified shape up or down the collection's z-order, which shifts it in front of or behind other shapes.

setZOrder(position: "BringForward" | "BringToFront" | "SendBackward" | "SendToBack"): void;

Parameters

Returns

Remarks

[ API set: PowerPointApi 1.8 ]

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's passed to it.) Whereas the original PowerPoint.Shape object is an API object, the toJSON method returns a plain JavaScript object (typed as PowerPoint.Interfaces.ShapeData) that contains shallow copies of any loaded child properties from the original object.

toJSON(): PowerPoint.Interfaces.ShapeData;

Returns