Groups

Your AI assistant uses these tools to group elements together so they move and resize as a unit, or ungroup them when you need to edit individually.

Grouping is useful when multiple elements form a visual unit — like a title bar with an accent line and body text. Once grouped, moving or resizing one element affects all members of the group.

Grouping Elements Together

When you ask to “group these elements” or your assistant wants to lock related elements together, it uses element_group. All elements must be on the same slide and not already in a group.

Parameters

What It Returns

• groupId — the group's ID (use this to ungroup later)
• memberCount — number of elements in the group
• slideId, slideNumber — which slide the group is on

Example

element_group({
  deckId: "deck_abc123",
  elementIds: ["elem_001", "elem_002", "elem_003"]
})

// Response:
// {
//   groupId: "group_xyz789",
//   memberCount: 3,
//   slideId: "slide_002",
//   slideNumber: 2
// }

Example — Custom Group ID

// Use a custom group ID for easier reference
element_group({
  deckId: "deck_abc123",
  elementIds: ["elem_title", "elem_accent", "elem_body"],
  groupId: "header-group"
})

Creating Pre-Grouped Elements

Instead of creating elements and then grouping them in a second step, your assistant can pass a shared groupId to element_bulk_create to create them already grouped:

// Create pre-grouped elements in one call
element_bulk_create({
  deckId: "deck_abc123",
  slideId: "slide_002",
  elements: [
    {
      elementType: "shape",
      shapeType: "rectangle",
      x: 60, y: 40,
      width: 500, height: 80,
      fillColor: "#1C2833",
      text: "Revenue",
      fontSize: 36,
      textColor: "#FFFFFF",
      role: "title",
      groupId: "header-block"
    },
    {
      elementType: "line",
      startX: 60, startY: 130,
      endX: 400, endY: 130,
      strokeColor: "#5EA8A7",
      strokeWidth: 3,
      groupId: "header-block"
    }
  ]
})

// Both elements are created already grouped under "header-block"

Ungrouping Elements

When you need to edit grouped elements independently, your assistant uses element_ungroup to dissolve the group. All elements become independent again but stay in their current positions.

Parameters

What It Returns

• success — whether the ungroup succeeded
• ungroupedCount — number of elements that were freed
• slideId, slideNumber — which slide the elements are on

Example

element_ungroup({
  deckId: "deck_abc123",
  groupId: "group_xyz789"
})

// Response:
// {
//   success: true,
//   groupId: "group_xyz789",
//   ungroupedCount: 3,
//   slideId: "slide_002",
//   slideNumber: 2
// }

Constraints

• Minimum 2 elements — you can't group a single element
• Same slide — all elements must be on the same slide
• Not already grouped — elements can only belong to one group at a time. Ungroup first if you need to regroup

Related

• Element Operations — Create elements with a shared groupId via element_bulk_create
• Slide Operations — Use slide_get to find group IDs on a slide
• Design Techniques — Visual design patterns that benefit from grouping