Group

What a group does

A group is a structural layer that owns a hierarchy of other layers. It has no geometry of its own; its visible result comes from its descendants.

Use a group when several layers should share a coordinate space, timing window, opacity, effect, mask, clip, blend mode or 3D context.

The hierarchy is represented by layer records. A child points to its parent with parentLayerId; a group does not contain a children array.

{
  "id": "hero-group",
  "type": "group",
  "parentLayerId": null,
  "order": 0,
  "frame": { "width": 1080, "height": 600 },
  "transform": {
    "translate": { "x": 540, "y": 300, "z": 0 },
    "rotate": { "x": 0, "y": 0, "z": 0 },
    "scale": { "x": 1, "y": 1, "z": 1 },
    "anchor": { "x": 540, "y": 300, "z": 0 },
    "skew": { "x": 0, "y": 0 }
  },
  "opacity": 1,
  "timing": { "start": 0, "duration": 5000 }
}

Parent and child layers

Every layer has a parentLayerId and an order:

parentLayerId: null places the layer at the composition root;
a group id in parentLayerId makes the layer a direct child of that group;
a child layer keeps its own frame and local transform;
order controls paint order among siblings, with higher values appearing later;
a group may contain shapes, paths, text, images, videos, audio-linked visual layers and nested groups.

The parent id must refer to an existing group. A layer cannot be its own parent, and parent relationships cannot form a cycle.

Complete nested example

This example places a card and its title inside a nested group. The title and card use local coordinates; the two group transforms move the complete hierarchy.

{
  "layers": [
    {
      "id": "scene",
      "type": "group",
      "parentLayerId": null,
      "order": 0,
      "frame": { "width": 1080, "height": 1080 },
      "transform": {
        "translate": { "x": 0, "y": 0, "z": 0 },
        "rotate": { "x": 0, "y": 0, "z": 0 },
        "scale": { "x": 1, "y": 1, "z": 1 },
        "anchor": { "x": 0, "y": 0, "z": 0 },
        "skew": { "x": 0, "y": 0 }
      },
      "opacity": 1,
      "timing": { "start": 0, "duration": 5000 }
    },
    {
      "id": "card-content",
      "type": "group",
      "parentLayerId": "scene",
      "order": 0,
      "frame": { "width": 720, "height": 420 },
      "transform": {
        "translate": { "x": 540, "y": 540, "z": 0 },
        "rotate": { "x": 0, "y": 0, "z": -4 },
        "scale": { "x": 1, "y": 1, "z": 1 },
        "anchor": { "x": 360, "y": 210, "z": 0 },
        "skew": { "x": 0, "y": 0 }
      },
      "opacity": 1,
      "timing": { "start": 0, "duration": 5000 },
      "composite": { "blendMode": "normal", "isolation": "auto" }
    },
    {
      "id": "card-background",
      "type": "shape",
      "parentLayerId": "card-content",
      "order": 0,
      "frame": { "width": 720, "height": 420 },
      "transform": {
        "translate": { "x": 0, "y": 0, "z": 0 },
        "rotate": { "x": 0, "y": 0, "z": 0 },
        "scale": { "x": 1, "y": 1, "z": 1 },
        "anchor": { "x": 0, "y": 0, "z": 0 },
        "skew": { "x": 0, "y": 0 }
      },
      "opacity": 1,
      "timing": { "start": 0, "duration": 5000 },
      "payload": { "shape": "rectangle", "cornerRadius": 28 },
      "style": { "fill": "#102A43" }
    }
  ]
}

Shared group properties

Group properties apply to the group boundary and, where applicable, its complete descendant tree.

Property	Purpose
`frame`	Defines the group's local width and height.
`transform`	Moves, rotates, scales, anchors or skews the group coordinate space.
`opacity`	Controls the opacity of the composed group result.
`enabled` / `visibility`	Enables, hides or collapses the group and its descendants.
`composite`	Sets blend mode and optional isolation for the group result.
`effects`	Applies documented effects to the group subtree as a unit.
`clipPath`, `mask`, `maskLayers`	Limits the visible coverage of the group.
`filter` / `backdropEffects`	Applies a documented filter or backdrop effect.
`timing`	Defines when the group is active on the composition timeline.
`tracks`	Animates supported group properties over time.
`render3d`	Defines a local flat or preserved 3D context for descendants.

Only add properties that are needed. A simple container normally needs just the common layer fields, while a group with effects or perspective can opt into the corresponding documented fields.

Parent transform and local coordinates

The group transform is composed with each child transform. Children keep their local frame and local transform semantics, so a child should normally be authored relative to its group rather than with final composition coordinates.

For a nested hierarchy, the local relationship is read from the inside out: a leaf layer uses its own transform, then inherits each parent group's coordinate space. This makes it possible to move or animate a complete scene without rewriting every child.

Timing and animation

The group's timing controls the group's active window. A child can have its own timing inside that hierarchy, but for predictable authoring keep child content within the period in which its parent is active.

Animate a group when the whole hierarchy should move together. Typical track paths include:

{
  "tracks": [
    { "path": "transform.translate.x", "keyframes": [{ "time": 0, "value": 240 }, { "time": 1000, "value": 540 }] },
    { "path": "transform.rotate.z", "keyframes": [{ "time": 0, "value": -4 }, { "time": 1000, "value": 0 }] },
    { "path": "opacity", "keyframes": [{ "time": 0, "value": 0 }, { "time": 500, "value": 1 }] }
  ]
}

Use the documented value type for each path. Animate a child instead when only one element should change.

Compositing, masks and effects

Group-level visual properties define the scope of an operation:

group opacity affects the combined group result;
composite.blendMode blends the group result with surrounding content;
composite.isolation keeps group blending within its declared boundary;
effects, filter, clipPath and mask apply to the group scope when declared there;
a child-level property affects only that child.

Put a property on the smallest layer that should own its effect. Put it on the group when the same operation must cover all descendants.

3D group context

Use render3d only when descendants need an explicit 3D relationship:

{
  "render3d": {
    "transformStyle": "preserve-3d",
    "perspective": {
      "distance": 800,
      "origin": { "x": 360, "y": 210 }
    }
  }
}

flat keeps descendants in a flattened group context. preserve-3d keeps their 3D relationship. Perspective distance must be positive, and origin uses the group's local coordinates.

Common mistakes

Mistake	Why it causes a problem	Better approach
Adding `children` to a group	Hierarchy is represented by layer records, not an embedded child array.	Set each child's `parentLayerId`.
Using a missing parent id	The hierarchy cannot be resolved.	Declare the group first and verify every reference.
Reusing an id	References become ambiguous.	Use unique ids across all layers.
Creating a parent cycle	A layer cannot be both an ancestor and a descendant of itself.	Keep the parent chain acyclic.
Giving every child world coordinates	Moving the group becomes difficult and can apply a transform twice.	Author child frames and transforms in the parent's local space.
Putting a group effect on one child	The effect will not cover the other descendants.	Move it to the group when the whole subtree is the target.
Using the same sibling order	Paint order becomes ambiguous.	Assign intentional, unique order values among siblings.

AI checklist

When an AI creates a group, it should:

Decide which layers must move, appear, disappear or receive effects together.
Create one unique group id and give it the common layer fields.
Set every direct child's parentLayerId to that group id.
Author child coordinates in the group's local space.
Use distinct sibling order values.
Keep timing and animation paths within the documented ranges.
Check that parent links resolve and contain no cycles.

Boundary

Group is a container and coordinate scope. High-level component behavior, responsive layout rules and reusable template logic are not group fields; express their final authoring result with documented layers, groups and properties.