Grouping elements

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.

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.

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
• Tables

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

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.

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

• addElementAtPoint

import React from "react";
import { addElementAtPoint } from "@canva/design";
import { Button, Rows } from "@canva/app-ui-kit";
import * as styles from "styles/components.css";

export function App() {
  async function handleClick() {
    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 className={styles.scrollContainer}>
      <Rows spacing="2u">
        <Button variant="primary" onClick={handleClick}>
          Add group to design
        </Button>
      </Rows>
    </div>
  );
}