Group elements

A group element is a type of element that organizes two or more elements into a single entity. When elements are organized into groups, users can efficiently arrange related elements in a design.

Apps can use the Design Interaction capability to add group elements to a user's design.

Creating group elements

Call the addNativeElement method and pass through an object with the following properties:

• type - The type of element. This must be set to "GROUP"
• children - The elements to include within the group

The following snippet demonstrates how to create a group element that contains two embed elements:

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

All elements within a group:

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

These are the same requirements as elements that exist within an app element.

The anatomy of a group element

You can arrange elements in a group by adjusting their dimensions, positions, rotations, and the order in which they're rendered, but there's a number of nuances that you should be aware of.

Box model

You can think of a group as a box.

This box must contain at least two elements.

By default:

• The box doesn't have a width or height
• The size of the box is calculated based on the size and the spacing between the elements it contains

Dimensions

The child elements inside a group must have a width and a height. (The one exception is native text elements, which can't have a predefined height.)

When the width is defined as a number, the height can be set to "auto" (and vice versa). At runtime, Canva replaces "auto" with a value that maintains the aspect ratio of the element.

Positioning

Within a group, elements can be positioned with top and left coordinates. These coordinates are relative to the group's origin — that is, the top-left corner of the group.

The origin is determined by the groups' topmost and leftmost elements, which may or may not be the same element. For example, if the topmost element has a top position of 50 and the leftmost element has a left position of 100, then:

• The top and left coordinates of the group start from 50 and 100
• The top and left coordinates of all other elements are relative to 50 and 100

To illustrate, here's a diagram:

This can be confusing — especially if negative values are used for positions — so we recommend treating the top and left coordinates as 0 and 0, even though this isn't strictly required or enforced.

Spacing

Elements can be positioned to overlap or to have spacing between them. The size of the group then grows or shrinks to accommodate for the combined size of the elements.

When elements overlap, the ordering of the elements is determined by the order in which the elements are returned in the app element renderer callback. Elements returned later in the callback are rendered in front of elements returned earlier.

Padding

Groups do not have padding. There's always at least one element positioned against each edge of the group.

Units of measurement

Within a group, dimensions and coordinates are defined with relative units, not absolute units. This means 200 is always twice as large as 100, but these numbers don't correspond to pixel values.

The end result is that, if a design is 1920 × 1280, setting the dimensions of a group's elements to a combined size of 1920 × 1280 will not necessarily result in the group extending to the edges of the design. Instead, the group will be scaled to a sized that's calculated by Canva.

How Canva determines the absolute size of elements depends on a variety of factors that may change over time and is beyond the scope of this documentation.

The key takeaway is to never treat dimensions or coordinates within a group as absolute values.

Limitations

• App elements can't contain group elements.
• Group elements can't contain app elements.
• Group elements can't contain other group elements.
• Group elements must contain at least two elements.
• All elements within a group element must have a width and height. The one exception is text elements, which can't have a predefined height.