Grouping elements

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:

• Embeds
• Images
• Shapes
• Text
• Videos

The following types of elements cannot be organized into groups:

• App elements
• Groups

How to create groups

Import the addNativeElement method from the @canva/design package:

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

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,
    },
  ],
});

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

• addNativeElement

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>
  );
}