How to Use Groups

Grouping combines multiple elements into a single unit. When you group a box and its label, they move, scale, and animate together as one. This is essential for building complex diagrams where related elements should stay connected.

In Excalimate, groups are especially powerful because you can animate an entire group with a single set of keyframes — no need to animate each element individually.

Grouping works the same way as in Excalidraw:

• Select multiple elements — Click and drag to select, or hold Shift and click each element
• Group them — Press Ctrl+G (Windows/Linux) or Cmd+G (macOS)
• Ungroup — Select the group and press Ctrl+Shift+G or Cmd+Shift+G

You'll see a blue selection box around the entire group. Clicking any element in the group selects the whole group. Double-click to select an individual element inside.

• Move together — Drag the group and all elements maintain their relative positions
• Animate as one — Apply opacity, position, scale, and rotation keyframes to the group ID and all child elements follow
• Organize complexity — Large diagrams with dozens of elements become manageable when organized into logical groups
• Consistent sizing — Scale the entire group and all elements scale proportionally
• Cleaner timeline — One animation track per group instead of one per element

When using the MCP server with an AI assistant, elements are grouped by sharing the same groupIds array. The AI handles this automatically when you describe related elements:

// Elements share a groupId to form a group.
// The MCP server creates groups automatically:
create_animated_scene({
  elements: [
    {
      type: "rectangle",
      id: "server-box",
      x: 100, y: 100,
      width: 200, height: 120,
      groupIds: ["server-group"]
    },
    {
      type: "text",
      id: "server-label",
      x: 140, y: 140,
      text: "Server",
      groupIds: ["server-group"]
    }
  ]
})

Both the rectangle and the text share "server-group" as their group ID, so they behave as a single unit.

The real power of groups in Excalimate is animation. Target the group ID in your keyframes and every element in the group animates together:

// Animate the entire group with one keyframe set.
// All elements in the group move together:
add_keyframes_batch([
  { targetId: "server-group", property: "opacity",
    time: 0,    value: 0 },
  { targetId: "server-group", property: "opacity",
    time: 500,  value: 1, easing: "easeOut" },
  { targetId: "server-group", property: "translateY",
    time: 0,    value: -20 },
  { targetId: "server-group", property: "translateY",
    time: 500,  value: 0,  easing: "easeOutBack" },
])

This fades in and slides up the entire server component — box, label, and any other elements in the group — with just two keyframe pairs.

Excalimate supports nested groups — a group can contain other groups. This is useful for building hierarchical structures:

• Inner groups — A "Server" group with a box + label inside
• Outer groups — A "Backend" group containing multiple server groups
• Independent animation — Animate the outer group to move everything, then animate inner groups individually for detailed reveals

Elements can belong to multiple groups through the groupIds array. The innermost group ID takes priority for selection, but animations on any containing group affect all children.

• Group early — Set up groups before starting your animation timeline
• Name groups clearly — Use descriptive group IDs like "auth-service" instead of "group-1"
• One concept per group — Each group should represent a single logical component (a service, a step, a layer)
• Use groups for reveal sequences — Reveal groups one after another with create_sequence for clean, organized animations
• Checkpoint before ungrouping — Use save_checkpoint before restructuring groups so you can revert if needed