Group

The group primitive is a composable container that collects child elements into a single unit. Spatial layout transforms such as rotation, scale, and translation applied to the group affect all children at once, making it easy to move or rotate composite shapes as one.

0.00s / 3.97s · F0

Props

Prop	Type	Default	Description
`children`	`React.ReactNode`	—	Required. Child elements to group
`rotation`	`number`	`0`	Rotation in degrees (applied to all children)
`rotationOrigin`	`[number, number]`	group center	Center point for rotation
`scale`	`number \| [number, number]`	`1`	Uniform or per-axis scale
`translate`	`[number, number]`	`[0, 0]`	Translation offset `[dx, dy]`
`opacity`	`number`	`1`	Opacity from 0 to 1

Group children render in their children array order. Later children paint on top.

Code Examples

Basic grouping

elements: {
  node: { id: 'node', type: 'group', children: ['node-ring', 'node-label'], props: { type: 'group' } },
  'node-ring': { id: 'node-ring', type: 'circle', parentId: 'node', props: { type: 'circle', cx: 250, cy: 130, r: 50, stroke: '$accent', fill: 'none', strokeWidth: 2 } },
  'node-label': { id: 'node-label', type: 'text', parentId: 'node', props: { type: 'text', x: 250, y: 220, content: 'Grouped together', fill: '$foreground', fontSize: 18, textAnchor: 'middle' } },
}

Group with rotation

All children rotate together around the group center:

elements: {
  badge: { id: 'badge', type: 'group', layout: { rotation: 45 }, children: ['badge-box', 'badge-dot'], props: { type: 'group' } },
}

Group with timeline reveal

Reveal all children at once by animating the group opacity:

timelines: {
  intro: {
    id: 'intro',
    duration: 30,
    tracks: [{ target: 'node', property: 'opacity', keyframes: [{ frame: 0, value: 0 }, { frame: 30, value: 1 }] }],
  },
}

Nested groups

Groups can be nested for hierarchical transforms:

elements: {
  outer: { id: 'outer', type: 'group', layout: { translate: [100, 50] }, children: ['inner', 'outer-label'], props: { type: 'group' } },
  inner: { id: 'inner', type: 'group', parentId: 'outer', layout: { rotation: 30 }, children: ['inner-box', 'inner-label'], props: { type: 'group' } },
}

Composite shape

Build reusable composite shapes by grouping primitives:

function labeledNode(id: string, x: number, y: number, label: string) {
  return {
    [id]: { id, type: 'group', layout: { translate: [x, y] }, children: [`${id}-ring`, `${id}-label`], props: { type: 'group' } },
    [`${id}-ring`]: { id: `${id}-ring`, type: 'circle', parentId: id, props: { type: 'circle', cx: 0, cy: 0, r: 30, stroke: '$accent', fill: 'none', strokeWidth: 2 } },
    [`${id}-label`]: { id: `${id}-label`, type: 'text', parentId: id, props: { type: 'text', x: 0, y: 5, content: label, fill: '$foreground', fontSize: 14, textAnchor: 'middle' } },
  };
}