[PowerPoint] (shapes) Add how to group and ungroup shapes (#5160)

Author: ElizabethSamuel-MSFT

docs/powerpoint/shapes.md

@@ -1,7 +1,7 @@
 ---
 title: Work with shapes using the PowerPoint JavaScript API
 description: Learn how to add, remove, and format shapes on PowerPoint slides.
-ms.date: 03/14/2023
+ms.date: 05/06/2025
 ms.localizationpriority: medium
 ---
 
@@ -102,6 +102,75 @@ await PowerPoint.run(async (context) => {
 });
 ```
 
+## Group and ungroup shapes
+
+In PowerPoint, you can group several shapes and treat them like a single shape. You can subsequently ungroup grouped shapes. To learn more about grouping objects in the PowerPoint UI, see [Group or ungroup shapes, pictures, or other objects](https://support.microsoft.com/office/a7374c35-20fe-4e0a-9637-7de7d844724b).
+
+### Group shapes
+
+To group shapes with the JavaScript API, use [ShapeCollection.addGroup](/javascript/api/powerpoint/powerpoint.shapecollection#powerpoint-powerpoint-shapecollection-addgroup-member(1)).
+
+The following example code shows how to group existing shapes of type [GeometricShape](/javascript/api/powerpoint/powerpoint.shapetype) found on the current slide.
+
+```typescript
+// Groups the geometric shapes on the current slide.
+await PowerPoint.run(async (context) => {
+    // Get the shapes on the current slide.
+    context.presentation.load("slides");
+    const slide: PowerPoint.Slide = context.presentation.getSelectedSlides().getItemAt(0);
+    slide.load("shapes");
+    await context.sync();
+
+    const shapes: PowerPoint.ShapeCollection = slide.shapes;
+    shapes.load("items/type,items/id");
+    await context.sync();
+
+    // Group the geometric shapes.
+    const shapesToGroup = shapes.items.filter((item) => item.type === PowerPoint.ShapeType.geometricShape);
+    console.log(`Number of shapes to group: ${shapesToGroup.length}`);
+    const group = shapes.addGroup(shapesToGroup);
+    group.load("id");
+    await context.sync();
+
+    console.log(`Grouped shapes. Group ID: ${group.id}`);
+});
+```
+
+### Ungroup shapes
+
+To ungroup shapes with the JavaScript API, get the [group](/javascript/api/powerpoint/powerpoint.shape#powerpoint-powerpoint-shape-group-member) property from the group's `Shape` object then call [ShapeGroup.ungroup](/javascript/api/powerpoint/powerpoint.shapegroup#powerpoint-powerpoint-shapegroup-ungroup-member(1)).
+
+The following code shows how to ungroup the first shape group found on the current slide.
+
+```typescript
+// Ungroups the first shape group on the current slide.
+await PowerPoint.run(async (context) => {
+    // Get the shapes on the current slide.
+    context.presentation.load("slides");
+    const slide: PowerPoint.Slide = context.presentation.getSelectedSlides().getItemAt(0);
+    slide.load("shapes");
+    await context.sync();
+
+    const shapes: PowerPoint.ShapeCollection = slide.shapes;
+    shapes.load("items/type,items/id");
+    await context.sync();
+
+    // Ungroup the first grouped 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;
+    }
+
+    const firstGroupId = shapeGroups[0].id;
+    const shapeGroupToUngroup = shapes.getItem(firstGroupId);
+    shapeGroupToUngroup.group.ungroup();
+    await context.sync();
+
+    console.log(`Ungrouped shapes with group ID: ${firstGroupId}`);
+});
+```
+
 ## Delete shapes
 
 Shapes are removed from the slide with the `Shape` object's `delete` method.
@@ -123,3 +192,9 @@ await PowerPoint.run(async (context) => {
     await context.sync();
 });
 ```
+
+## See also
+
+- [Work with tables using the PowerPoint JavaScript API](work-with-tables.md)
+- [Bind to shapes in a PowerPoint presentation](bind-shapes-in-presentation.md)
+- [Group or ungroup shapes, pictures, or other objects](https://support.microsoft.com/office/a7374c35-20fe-4e0a-9637-7de7d844724b)

docs/toc.yml

@@ -910,15 +910,15 @@ items:
     - name: Use document themes in your PowerPoint add-ins
       href: powerpoint/use-document-themes-in-your-powerpoint-add-ins.md
       displayName: PowerPoint
-    - name: Work with tables
-      href: powerpoint/work-with-tables.md
-      displayName: PowerPoint
     - name: Work with shapes
       href: powerpoint/shapes.md
       displayName: PowerPoint
     - name: Bind shapes to a data source
       href: powerpoint/bind-shapes-in-presentation.md
       displayName: PowerPoint
+    - name: Work with tables
+      href: powerpoint/work-with-tables.md
+      displayName: PowerPoint
 - name: Project
   items:
   - name: Project add-ins documentation