Group

A container that collects geometry into a single, movable unit.

Groups let you organize edges, faces, and other entities so they can be selected, moved, copied, and edited as one object. Unlike component instances, each group is unique — editing one group never affects another. Groups are ideal for temporary or one-off clusters of geometry that don’t need to be reused across the model.

When the user double-clicks a group in SketchUp, they enter its “edit context” and can modify the geometry inside. From the API, you can read a group’s entities using group.entities.get() or create new geometry inside a group during an operation with methods like createFace(groupRef, ...).

Example

let model = await SketchUpApi.getActiveModel();
let { Transformation } = SketchUpApi;

// Create a group with a simple box inside.
await model.performOperation(op => {
  const g = op.createGroup(model);
  // Floor
  op.createFace(g, [
    [0,0,0], [48,0,0], [48,48,0], [0,48,0]
  ]);
  // Back wall
  op.createFace(g, [
    [0,0,0], [0,0,24], [48,0,24], [48,0,0]
  ]);
  op.groupSetName(g, 'Simple Box');
  op.drawingElementsApplyTransformation(
    g, Transformation.translation([100, 50, 0])
  );
}, 'Create named group');

// Query it back and inspect its properties.
let groups = await model.entities.get({
  filterBy: { types: ['Group'] }
});
let box = groups[0];
console.log(box.name);
// => Simple Box
console.log(box.transform.origin.toArray());
// => [100, 50, 0]
let entities = await box.entities.get();
console.log(entities.length);
// => 2 (two faces)

See

Extends

BaseDrawingElement

Properties

attributes

readonly attributes: Attributes

The attribute dictionaries attached to this element. Attributes store custom key-value metadata that extensions can read and write.

Inherited from

BaseDrawingElement.attributes

castsShadows

readonly castsShadows: boolean

Whether this element casts shadows onto other geometry.

Inherited from

BaseDrawingElement.castsShadows

definitionId

readonly definitionId: number

The persistent ID of the underlying component definition that stores this group’s geometry. Every group is backed by a hidden definition.

description

readonly description: string | undefined

A longer text description of this group. Not commonly used — most groups rely on name alone. May be undefined.

gluedToId

readonly gluedToId: SketchupId | undefined

If this group is glued to a face (like a window on a wall), this is the ID of the entity it’s glued to. Most groups are not glued, so this is typically undefined.

guid

readonly guid: string | undefined

A globally unique identifier for this group, persisted across file saves. Useful for linking groups to external data sources. May be undefined.

hidden

readonly hidden: boolean

Whether this element is hidden. Hidden elements don’t appear in the viewport unless the user enables “View > Hidden Geometry.”

Inherited from

BaseDrawingElement.hidden

id

readonly id: number

The persistent ID that uniquely identifies this group instance.

locked

readonly locked: boolean

Whether this group is locked, preventing the user from selecting or editing it in the SketchUp UI. Locked groups can still be queried and modified via the API.

materialRef

readonly materialRef: MaterialRef | undefined

A reference to the material applied to this element, if any. Call getMaterial() to fetch the full Material object with color and texture data.

Inherited from

BaseDrawingElement.materialRef

name

readonly name: string | undefined

The display name assigned to this group, like “Box” or “Wall Assembly”. May be undefined if the group was never named.

receivesShadows

readonly receivesShadows: boolean

Whether this element receives shadows cast by other geometry.

Inherited from

BaseDrawingElement.receivesShadows

tagRef

readonly tagRef: TagRef | undefined

A reference to the tag (formerly “layer”) assigned to this element. Call getTag() to fetch the full Tag object.

Inherited from

BaseDrawingElement.tagRef

transform

readonly transform: Transformation

The transformation matrix that positions and orients this group in 3D space. Encodes translation, rotation, and scale relative to the parent context.

type

readonly type: Group = EntityType.Group

Accessors

definition

Get Signature

get definition(): ComponentDefinitionRef

A reference to the hidden component definition that stores this group’s geometry. Every group is backed by a unique definition, but this is an implementation detail — you typically won’t need to access it directly. Use entities to read or modify the group’s contents instead.

Since

SDK 2.17.0

Returns

ComponentDefinitionRef

entities

Get Signature

get entities(): CallableEntities

The entities collection for this group. Use entities.get() to query faces, edges, nested groups, and other geometry inside this group. You can also call specialized methods like entities.getCurves() or entities.getActiveSectionPlane().

Example

let model = await SketchUpApi.getActiveModel();
let groups = await model.entities.get({
  filterBy: { types: ['Group'] },
});
let group = groups[0];

// Get all faces inside the group
let faces = await group.entities.get({
  filterBy: { types: ['Face'] }
});
console.log(faces.length);

Returns

CallableEntities

sketchupId

Get Signature

get sketchupId(): SketchupId

JS API identifier for this group. Pass it to API methods that accept a sketchupId.

Returns

SketchupId

Overrides

BaseDrawingElement.sketchupId

typeName

Get Signature

get typeName(): string

Returns a named variant of the type field.

Since

SDK 2.35.0

Returns

string

Methods

getBounds()

getBounds(): Promise<BoundingBox>

Fetches the axis-aligned bounding box for this element from SketchUp.

Returns

Promise<BoundingBox>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let box = await element.getBounds();
console.log(box.min.x, box.min.y, box.min.z);
console.log(box.max.x, box.max.y, box.max.z);

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getBounds

getMaterial()

getMaterial(): Promise<Material | undefined>

Fetches the material applied to this element. Returns undefined if the element uses the default material.

Returns

Promise<Material | undefined>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let mat = await element.getMaterial();
if (mat) {
  console.log(mat.name, mat.color.toHex());
}

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getMaterial

getTag()

getTag(): Promise<Tag | undefined>

Fetches the tag assigned to this element. Most elements have a tag — even those on the default “Untagged” tag. Returns undefined only if the tag reference is missing.

Returns

Promise<Tag | undefined>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let tag = await element.getTag();
if (tag) {
  console.log(tag.name);
}

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getTag

refresh()

refresh(): Promise<Group>

Re-fetches this group from SketchUp to get its current state. Because Group is a snapshot, it can become stale if the model changes (for example, if the user moves or renames the group). Call refresh() to get an up-to-date copy.

Returns

Promise<Group>

A new Group reflecting the current model state. Throws if the group has been deleted.

Example

let model = await SketchUpApi.getActiveModel();
let groups = await model.entities.get({
  filterBy: { types: ['Group'] },
});
// Later, after the user makes changes...
let fresh = await groups[0].refresh();
console.log(fresh.name, fresh.locked);

toString()

toString(): string

Returns a string representation of an object.

Returns

string

Show Deprecated

Deprecated

materialId

readonly materialId: number | undefined

Inherited from

BaseDrawingElement.materialId

tagId

readonly tagId: number | undefined

Inherited from

BaseDrawingElement.tagId

bounds

Get Signature

get bounds(): Promise<BoundingBox>

Returns

Promise<BoundingBox>

Inherited from

BaseDrawingElement.bounds

componentInstances()

componentInstances(filter?): Promise<readonly ComponentInstance[]>

Query to find the componentInstances for this group

Parameters

Parameter	Type	Default value
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`

Returns

Promise<readonly ComponentInstance[]>

a promise containing a snapshot of the componentInstances for this group

constructionLines()

constructionLines(filter?): Promise<readonly ConstructionLine[]>

Query to find the constructionLines for this group

Parameters

Parameter	Type	Default value
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`

Returns

Promise<readonly ConstructionLine[]>

a promise containing a snapshot of the constructionLines for this group

Since

SDK 2.7.0 Protocol 1.5.0

constructionPoints()

constructionPoints(filter?): Promise<readonly ConstructionPoint[]>

Query to find the constructionPoints for this group

Parameters

Parameter	Type	Default value
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`

Returns

Promise<readonly ConstructionPoint[]>

a promise containing a snapshot of the constructionPoints for this group

Since

SDK 2.7.0 Protocol 1.5.0

curves()

curves(filter?): Promise<readonly (ArcCurve | Curve)[]>

Gets the curves for this group

Parameters

Parameter	Type	Default value	Description
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`	optional filter to apply to the list of curves

Returns

Promise<readonly (ArcCurve | Curve)[]>

Since

SDK 2.23.0 Protocol 1.20.0

dimensionLinears()

dimensionLinears(filter?): Promise<readonly DimensionLinear[]>

Query to find the dimension linear entities for this group

Parameters

Parameter	Type	Default value	Description
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`	optional additional filtering to apply

Returns

Promise<readonly DimensionLinear[]>

a promise containing a snapshot of the dimension linear entities for this group

Since

SDK 2.23.0 Protocol 1.20.0

dimensionRadials()

dimensionRadials(filter?): Promise<readonly DimensionRadial[]>

Query to find the dimension radial entities for this group

Parameters

Parameter	Type	Default value	Description
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`	optional additional filtering to apply

Returns

Promise<readonly DimensionRadial[]>

a promise containing a snapshot of the dimension radial entities for this group

Since

SDK 2.23.0 Protocol 1.20.0

edges()

edges(filter?): Promise<readonly Edge[]>

Query to find the edges for this group

Parameters

Parameter	Type	Default value
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`

Returns

Promise<readonly Edge[]>

a promise containing a snapshot of the edges for this group

faces()

faces(filter?): Promise<readonly Face[]>

Query to find the faces for this group

Parameters

Parameter	Type	Default value
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`

Returns

Promise<readonly Face[]>

a promise containing a snapshot of the faces for this group

getActiveSectionPlane()

getActiveSectionPlane(): Promise<SectionPlane | undefined>

Gets the active section plane for the given entities container.

Returns

Promise<SectionPlane | undefined>

A promise resolving to the SectionPlaneRef or undefined if none is active

Since

SDK 2.16.0 Protocol 1.13.0

groups()

groups(filter?): Promise<readonly Group[]>

Query to find the groups for this group

Parameters

Parameter	Type	Default value
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`

Returns

Promise<readonly Group[]>

a promise containing a snapshot of the groups for this group

images()

images(filter?): Promise<readonly ImageEntity[]>

Query to find the images for this group

Parameters

Parameter	Type	Default value	Description
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`	optional additional filtering to apply

Returns

Promise<readonly ImageEntity[]>

a promise containing a snapshot of the images for this group

Since

SDK 2.21.0 Protocol 1.18.0

sectionPlanes()

sectionPlanes(filter?): Promise<readonly SectionPlane[]>

Query to find the sectionPlanes for this group

Parameters

Parameter	Type	Default value
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`

Returns

Promise<readonly SectionPlane[]>

a promise containing a snapshot of the sectionPlanes for this group

Since

SDK 2.16.0 Protocol 1.13.0

snaps()

snaps(filter?): Promise<readonly Snap[]>

Query to find the snaps for this group

Parameters

Parameter	Type	Default value
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`

Returns

Promise<readonly Snap[]>

a promise containing a snapshot of the snaps for this group

Since

SDK 2.20.0 Protocol 1.17.0

texts()

texts(filter?): Promise<readonly Text[]>

Query to find the texts for this group

Parameters

Parameter	Type	Default value
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`

Returns

Promise<readonly Text[]>

a promise containing a snapshot of the texts for this group

Since

SDK 2.22.0 Protocol 1.19.0