Grouping Elements

Creating a group

Groups are just like any other element in Adobe Express, very much like Text or Shapes: you must create them, and append them to the page. Interestingly, as instances of the GroupNode class, they can host other nodes in their children property.

To create a Group, you can use the editor.createGroup() method.

Example

Copy
// sandbox/code.js
import { editor } from "express-document-sdk";

// Create some Text
const greeting = editor.createText();
greeting.fullContent.text = "Hiya!";
greeting.translation = { x: 100, y: 50 };

// Create some other Text
const saluto = editor.createText();
saluto.fullContent.text = "Ciao!";
saluto.translation = { x: 100, y: 150 };

// Create a Group 👈
const greetingsGroup = editor.createGroup();
greetingsGroup.translation = { x: 100, y: 100 };

// Append the Text nodes to the Group 👈
greetingsGroup.children.append(greeting, saluto);

// Append the Group to the page 👈
editor.context.insertionParent.children.append(greetingsGroup);
Copied to your clipboard
// sandbox/code.js
import { editor } from "express-document-sdk";

// Create some Text
const greeting = editor.createText();
greeting.fullContent.text = "Hiya!";
greeting.translation = { x: 100, y: 50 };

// Create some other Text
const saluto = editor.createText();
saluto.fullContent.text = "Ciao!";
saluto.translation = { x: 100, y: 150 };

// Create a Group 👈
const greetingsGroup = editor.createGroup();
greetingsGroup.translation = { x: 100, y: 100 };

// Append the Text nodes to the Group 👈
greetingsGroup.children.append(greeting, saluto);

// Append the Group to the page 👈
editor.context.insertionParent.children.append(greetingsGroup);

Nesting groups

Groups can be nested, meaning that you can have a Group inside another Group; just create the needed Group nodes and append() elements to their children property.

Example

Copy
// sandbox/code.js

// Create three different Text nodes
const greeting = editor.createText();
greeting.fullContent.text = "Hiya!";

const saluto = editor.createText();
saluto.fullContent.text = "Ciao!";

const salutation = editor.createText();
salutation.fullContent.text = "Salut!";

// Create an inner Group with the first two Text nodes
const innerGroup = editor.createGroup();
innerGroup.children.append(greeting, saluto);

// Create an outer Group with the inner Group and the third Text node
const outerGroup = editor.createGroup();
outerGroup.children.append(innerGroup, salutation);

editor.context.insertionParent.children.append(outerGroup);
Copied to your clipboard
// sandbox/code.js

// Create three different Text nodes
const greeting = editor.createText();
greeting.fullContent.text = "Hiya!";

const saluto = editor.createText();
saluto.fullContent.text = "Ciao!";

const salutation = editor.createText();
salutation.fullContent.text = "Salut!";

// Create an inner Group with the first two Text nodes
const innerGroup = editor.createGroup();
innerGroup.children.append(greeting, saluto);

// Create an outer Group with the inner Group and the third Text node
const outerGroup = editor.createGroup();
outerGroup.children.append(innerGroup, salutation);

editor.context.insertionParent.children.append(outerGroup);

This code results in the following grouping:

Copy
Outer Group
├── Inner Group
│   ├── Text Node: "Hiya!"
│   └─ Text Node: "Ciao!"
│
└── Text Node: "Salut!"
Copied to your clipboard
Outer Group
├── Inner Group
│   ├── Text Node: "Hiya!"
│   └─ Text Node: "Ciao!"
│
└── Text Node: "Salut!"

Element order

As you would intuitively expect, the order in which you append elements to a Group matters. The last element you append will be on top of the others, and the first one will be at the bottom.

As follows, a simple Square factory function creates and append a shape to the page, passing an option object with the size and color (grayscale) and offset properties. We'll be using it to test element order in a Group.

Copy
// sandbox/code.js
function squareFactory({ size, color, offset = 0 }) {
  const rectangle = editor.createRectangle();

  // Define rectangle dimensions.
  rectangle.width = size;
  rectangle.height = size;

  const insertionParent = editor.context.currentPage;
  console.log(insertionParent.width, insertionParent.height);
  rectangle.setPositionInParent(
    {
      x: insertionParent.width / 2 + offset,
      y: insertionParent.height / 2 + offset,
    },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
  );
  // Define rectangle color.
  rectangle.fill = editor.makeColorFill(
    colorUtils.fromRGB(color, color, color, 1)
  );
  return rectangle;
}
Copied to your clipboard
// sandbox/code.js
function squareFactory({ size, color, offset = 0 }) {
  const rectangle = editor.createRectangle();

  // Define rectangle dimensions.
  rectangle.width = size;
  rectangle.height = size;

  const insertionParent = editor.context.currentPage;
  console.log(insertionParent.width, insertionParent.height);
  rectangle.setPositionInParent(
    {
      x: insertionParent.width / 2 + offset,
      y: insertionParent.height / 2 + offset,
    },
    { x: rectangle.width / 2, y: rectangle.height / 2 }
  );
  // Define rectangle color.
  rectangle.fill = editor.makeColorFill(
    colorUtils.fromRGB(color, color, color, 1)
  );
  return rectangle;
}

Example: last element on top

Creating a Group with two squares; the lighter one is added last, and it will be on top of the darker one.

Copy
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const group = editor.createGroup();
group.children.append(s1, s2);

editor.context.insertionParent.children.append(group);
Copied to your clipboard
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const group = editor.createGroup();
group.children.append(s1, s2);

editor.context.insertionParent.children.append(group);

Example: re-ordering elements

It's possible to re-order the elements in the Group by using the children property and the moveAfter() or moveBefore() method.

Copy
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const group = editor.createGroup();
group.children.append(s1, s2);
// s2 is on top of s1, as it's been added last

// Moves s1 after (on top of) s2
group.children.moveAfter(s1, s2);
editor.context.insertionParent.children.append(group);
Copied to your clipboard
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const group = editor.createGroup();
group.children.append(s1, s2);
// s2 is on top of s1, as it's been added last

// Moves s1 after (on top of) s2
group.children.moveAfter(s1, s2);
editor.context.insertionParent.children.append(group);

Example: addding elements in a specific order

Similarly, it's possible to determine the elements insertion order with insertAfter() and insertBefore().

Copy
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const s3 = squareFactory({ size: 50, color: 0.9, offset: 20 });
const group = editor.createGroup();
group.children.append(s1, s2);
// s2 is on top of s1, as it's been added last

// Inserts s3 after s1 (in the middle)
group.children.insertAfter(s3, s1);
editor.context.insertionParent.children.append(group);
Copied to your clipboard
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const s3 = squareFactory({ size: 50, color: 0.9, offset: 20 });
const group = editor.createGroup();
group.children.append(s1, s2);
// s2 is on top of s1, as it's been added last

// Inserts s3 after s1 (in the middle)
group.children.insertAfter(s3, s1);
editor.context.insertionParent.children.append(group);

Moving elements out of a Group

To move an element out of one Group (the source) and into another (the target), you can use the children.append() method of the target, passing the source element you want to move. It's no different from appending a new element to a Group, you just need to reference the source element regardless of where it is.

Example

Copy
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.1 });
const s2 = squareFactory({ size: 50, color: 0.3, offset: 10 });
const s3 = squareFactory({ size: 50, color: 0.5, offset: 20 });
const s4 = squareFactory({ size: 50, color: 0.7, offset: 30 });
const s5 = squareFactory({ size: 50, color: 0.9, offset: 40 });
const group1 = editor.createGroup();
const group2 = editor.createGroup();

// Grouping elements in two different groups
group1.children.append(s1, s2, s3);
group2.children.append(s4, s5);

editor.context.insertionParent.children.append(group1);
editor.context.insertionParent.children.append(group2);

// Moves s1 into group2
group2.children.append(s1);
// 👆 target group     👆 source element
Copied to your clipboard
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.1 });
const s2 = squareFactory({ size: 50, color: 0.3, offset: 10 });
const s3 = squareFactory({ size: 50, color: 0.5, offset: 20 });
const s4 = squareFactory({ size: 50, color: 0.7, offset: 30 });
const s5 = squareFactory({ size: 50, color: 0.9, offset: 40 });
const group1 = editor.createGroup();
const group2 = editor.createGroup();

// Grouping elements in two different groups
group1.children.append(s1, s2, s3);
group2.children.append(s4, s5);

editor.context.insertionParent.children.append(group1);
editor.context.insertionParent.children.append(group2);

// Moves s1 into group2
group2.children.append(s1);
// 👆 target group     👆 source element

Removing elements

To remove an element from a Group, you can use the remove() method on the children property, which effectively also deletes the element from the document.

Example

Copy
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const s3 = squareFactory({ size: 50, color: 0.9, offset: 20 });
const group = editor.createGroup();
group.children.append(s1, s2, s3);
editor.context.insertionParent.children.append(group);

// Removes s2 from the Group and from the page!
group.children.remove(s2);
Copied to your clipboard
// sandbox/code.js
const s1 = squareFactory({ size: 50, color: 0.5 });
const s2 = squareFactory({ size: 50, color: 0.7, offset: 10 });
const s3 = squareFactory({ size: 50, color: 0.9, offset: 20 });
const group = editor.createGroup();
group.children.append(s1, s2, s3);
editor.context.insertionParent.children.append(group);

// Removes s2 from the Group and from the page!
group.children.remove(s2);

Last updated 2/24/2025

Was this helpful?

Yes

No