In Canva, a design's elements can be organized into groups. The elements in these groups can then be manipulated as a single unit, which is more convenient when working on complex designs.

The user experience

A group can be moved, resized, rotated, and animated as a single unit.

For fine-grained control, users can select and edit any of the individual elements in a group — for example, to apply effects to a specific image.

Users have the option of locking a group. When a group is locked, it can't be ungrouped, and its elements can't be edited. If a group is not locked, it can be ungrouped into its individual elements.

What can be grouped?

The following types of elements can be organized into groups:

The following types of elements cannot be organized into groups:

How to create groups

Step 1: Enable the required permissions

In the Developer Portal, enable the canva:design:content:write permission. In the future, the Apps SDK will throw an error if the required permissions are not enabled. To learn more, see Configuring permissions.

Step 2: Add the group to the design

Import the addElementAtPoint method (or addElementAtCursor, depending on the current context) from the @canva/design package:

import { addElementAtPoint } from "@canva/design";

Call the method, passing in the options shown here:

await addElementAtPoint({
  type: "group",
  children: [
    {
      type: "embed",
      url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
      width: 100,
      height: 100,
      top: 0,
      left: 0,
    },
    {
      type: "embed",
      url: "https://www.youtube.com/watch?v=o-YBDTqX_ZU",
      width: 100,
      height: 100,
      top: 0,
      left: 100,
    },
  ],
});

The children property should contain the elements to include in the group. The elements will render in the order they appear — that is, later elements will render in front of earlier elements.

Each object in the children array:

Must have a width and a height
Must have top and left coordinates
Can have a rotation, in degrees

The one exception is text elements, which don't require a width and can't have a height.

To learn more about how to position elements within a group, see Positioning elements.

Known limitations

Groups must contain at least two elements.
Apps can't create locked groups.

API reference

addElementAtPoint

Code sample

import React from "react";
import { addElementAtPoint } from "@canva/design";

export function App() {
  async function handleClick() {
    // Add the group to the design
    await addElementAtPoint({
      type: "group",
      children: [
        {
          type: "embed",
          url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
          width: 100,
          height: 100,
          top: 0,
          left: 0,
        },
        {
          type: "embed",
          url: "https://www.youtube.com/watch?v=o-YBDTqX_ZU",
          width: 100,
          height: 100,
          top: 0,
          left: 100,
        },
      ],
    });
  }

  return (
    <div>
      <button onClick={handleClick}>Add group to design</button>
    </div>
  );
}

tsx