Groups

Groups are logical containers that combine multiple shapes into a single selectable unit. Unlike frames, groups draw nothing of their own apart from a dashed outline while the group is focused. Their geometry is the union of their children's geometries, their bounds update automatically as children change, and they clean themselves up when their contents are deleted. Groups can be nested inside other groups.

Creating groups

Use Editor#groupShapes to combine shapes into a group. Pass an array of shape IDs or shape objects, and the method creates a new group containing those shapes:

import { createShapeId } from 'tldraw'

// Group selected shapes
editor.groupShapes(editor.getSelectedShapeIds())

// Group specific shapes
editor.groupShapes([shapeId1, shapeId2, shapeId3])

// Group with options
editor.groupShapes([shapeId1, shapeId2], {
	groupId: createShapeId('my-group'), // Custom ID for the group
	select: false, // Don't select the group after creation
})

Grouping requires at least two shapes. The method does nothing if you pass fewer, and it skips locked shapes. Users can also group shapes with Ctrl+G (Cmd+G on Mac); when the only selected shape is a group, the same shortcut ungroups it.

The new group is positioned at the top-left of the combined bounds of all grouped shapes. It takes the z-index of the topmost grouped shape, so it sits where that shape was in its parent's layer stack.

Ungrouping

Use Editor#ungroupShapes to dissolve groups and release their children:

// Ungroup selected groups
editor.ungroupShapes(editor.getSelectedShapeIds())

// Ungroup specific groups
editor.ungroupShapes([groupId])

// Ungroup without selecting the released children
editor.ungroupShapes([groupId], { select: false })

Ungrouping moves children to the group's parent and preserves their page positions and rotations. Layer order is maintained: children appear where the group was in the z-stack. If you pass a mix of groups and non-groups, only the groups are ungrouped and the non-groups stay selected. Users can ungroup with Ctrl+Shift+G (Cmd+Shift+G on Mac).

Ungrouping is not recursive. If a group contains other groups, those inner groups remain intact. Ungroup them separately if needed.

Focused groups

The editor tracks a focused group that defines the current editing scope. When you're focused inside a group, you can select and manipulate the shapes within it. Without focus, clicking a shape inside a group selects the group itself, not the individual shape.

Use Editor#getFocusedGroup, Editor#getFocusedGroupId, Editor#setFocusedGroup, and Editor#popFocusedGroupId:

// Get the current focused group
const focusedGroup = editor.getFocusedGroup()

// Get the focused group ID (returns page ID if no group is focused)
const focusedId = editor.getFocusedGroupId()

// Focus a specific group
editor.setFocusedGroup(groupId)

// Exit the current focused group and select it
editor.popFocusedGroupId()

The editor manages focus automatically based on selection:

• Selecting a shape inside a group focuses that group
• Selecting shapes across multiple groups focuses their common ancestor
• Pressing Escape pops focus one level up (or back to the page)
• Pressing Enter with only groups selected selects their children
• Clearing selection keeps the current focus

Layered selection

Clicking shapes inside groups follows a layered pattern:

1. First click selects the outermost group
2. Second click focuses the group and selects the parent of the target shape (or the shape if directly inside)
3. Further clicks drill down through nested groups

This lets you work at different levels of the hierarchy without keyboard modifiers.

Nested groups

Groups can contain other groups, creating hierarchies:

// Create a nested structure
editor.select(boxA, boxB)
editor.groupShapes(editor.getSelectedShapeIds())
const innerGroupId = editor.getOnlySelectedShapeId()

editor.select(innerGroupId, boxC, boxD)
editor.groupShapes(editor.getSelectedShapeIds())
const outerGroupId = editor.getOnlySelectedShapeId()

// Result:
// outerGroup
// ├── innerGroup
// │   ├── boxA
// │   └── boxB
// ├── boxC
// └── boxD

When grouping shapes that already have different parents, the editor finds their common ancestor and creates the group there. This prevents orphaning shapes from their natural hierarchy.

Automatic cleanup

Groups maintain themselves through the ShapeUtil#onChildrenChange lifecycle hook. If you delete all children of a group, the group is removed. If a group ends up with only one child, it dissolves and reparents that child to the group's parent.

This cleanup happens immediately when children change, so you never end up with degenerate groups.

// Start with a group containing boxA and boxB
editor.deleteShapes([boxA])
// Group now has only boxB, so it auto-ungroups
// boxB is now a direct child of the page (or the group's former parent)

Bounds and transforms

Group bounds are computed from their children's geometries. The Group2d geometry class aggregates all child geometries for hit testing and bounds calculation:

// Get a group's bounds
const bounds = editor.getShapePageBounds(groupId)

// Bounds update automatically when children move
editor.updateShape({ id: childId, type: 'geo', x: newX, y: newY })
const updatedBounds = editor.getShapePageBounds(groupId)

When you transform a group (move, rotate, resize), all children transform with it. The group's position and rotation are applied to children through the standard parent-child transform composition.

Position preservation works both ways. When you group shapes, their page positions are preserved—only their parentId and local coordinates change. When you ungroup, shapes return to their original page positions even if the group was rotated.

Creating shapes inside groups

When you create new shapes while focused inside a group, those shapes become children of the focused group unless they're positioned over a container such as a frame, which takes precedence:

// Focus a group by selecting a shape inside it
editor.select(shapeInsideGroup)
// Now getFocusedGroupId() returns the group's ID

// Create a new shape - it becomes a child of the focused group
editor.createShape({
	type: 'geo',
	x: 100,
	y: 100,
	props: { w: 50, h: 50 },
})
// The new shape's parentId is the focused group

If no group is focused, new shapes are created on the current page.

Limitations

Arrows can't bind to groups. ShapeUtil#canBind returns false for group shapes, so arrows must bind to individual shapes within the group.

Groups have no visual properties. You can't style a group itself, only its children.

Both grouping and ungrouping require the select tool to be active, and do nothing in readonly mode. If you're in the middle of another interaction, the editor cancels it before running the operation.

Related examples

• Layer panel - Build a hierarchical layer panel that shows shape and group structure with visibility controls.