Skip navigation
Skip to main content
Canva Developers logo

Grouping elements

How to organize elements into groups.

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

The user experience

A group can be moved, resized, rotated, and animated as a singular 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 addNativeElement method from the @canva/design package:

import { addNativeElement } from "@canva/design";
ts

Call the method, passing in the options shown here:

await addNativeElement({
  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,
    },
  ],
});
ts

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

Code sample

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


export function App() {
  async function handleClick() {
    // Add the group to the design
    await addNativeElement({
      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