--- title: Groups created_at: 12/25/2025 updated_at: 12/29/2025 keywords: - groups - grouping - focused group - hierarchy - nesting status: published date: 12/25/2025 readability: 9 voice: 9 completeness: 9 accuracy: 9 notes: Add API link formatting using [Editor#methodName](?) syntax. Fix blockquote formatting for examples link. --- 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: ```typescript 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](/sdk-features/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: ```typescript // 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](?): ```typescript // 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: ```typescript // 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. ```typescript // 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: ```typescript // 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: ```typescript // 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](/examples/ui/layer-panel) - Build a hierarchical layer panel that shows shape and group structure with visibility controls.