Group

A Group item is a container that holds other items together on the canvas. Items inside a group move, rotate, and scale as one unit. Groups can be nested inside other groups.

Type Definition

type GroupItemType = BaseItem & {
  type: "Group"
  itemProps: {
    isPermanent: boolean
    childPositions: [
      string,
      {
        x: number
        y: number
        rotation: number
        width: number
        height: number | undefined
        fontSize?: number
        type: string
      },
    ][]
  }
}

Properties

Base Properties

Inherited from all item types. See Common Properties.

Property	Type	Description
id	string	Unique identifier.
type	"Group"	Always "Group" for this item type.
x	number	X position of the group on the canvas.
y	number	Y position of the group on the canvas.
width	number	Width of the group bounding box.
height	number	Height of the group bounding box.
rotation	number	Rotation in degrees. Optional.
opacity	number	Opacity from 0 to 1. Optional.
locked	boolean	Prevents selection and movement. Optional.
groupId	string	ID of a parent group (for nested groups). Optional.

itemProps

Property	Type	Description
isPermanent	boolean	When true, the group persists when the user clicks elsewhere. When false, clicking outside the group dissolves it back to individual items.
childPositions	[string, ChildPosition][]	Array of [childId, position] tuples storing each child's local transform relative to the group.

ChildPosition

Property	Type	Description
x	number	X offset relative to the group origin.
y	number	Y offset relative to the group origin.
rotation	number	Child's rotation relative to the group.
width	number	Child width.
height	number | undefined	Child height (undefined for items where height is derived, e.g. auto-height text).
fontSize	number	Font size — only present when the child is a Text item. Optional.
type	string	The child item's type string (e.g. "Text", "Image", "Shape").

Creating a Group

Groups are created automatically when you select multiple items and group them via the keyboard shortcut (Cmd+G) or programmatically using useGroup.

const { createGroup } = useGroup()

// Mark an existing group as permanent
createGroup(groupItem)

Ungrouping

const { unGroup } = useGroup()

// Remove the permanent flag so the group can be dissolved
unGroup(groupItem)

Use Cmd+Shift+G in the Studio to ungroup items interactively.

Notes

• A group's bounding box (x, y, width, height) is calculated from the rotated bounds of all its children at the time of creation.
• Child items store their groupId referencing the parent group's id.
• childPositions preserves each child's absolute position at group-creation time and is used to restore positions when ungrouping.
• Setting isPermanent: true keeps the group intact when the user clicks outside it. When isPermanent is false, clicking elsewhere on the canvas dissolves the group and reverts its children to individual items.

Related

• useGroup
• Item Types Overview
• Keyboard Shortcuts