ComponentInstance

A placed copy of a component definition in the model.

When you place a component in SketchUp (like a chair, a tree, or a door), you’re creating a ComponentInstance. Each instance references a ComponentDefinition and has its own position, rotation, and scale (captured in the transform property). You can place the same definition many times — each placement is a separate instance.

ComponentInstance is a snapshot of the instance at the time it was queried. If the user moves or edits the instance in SketchUp, call refresh to get the updated state.

Example

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

// Create a component and place two instances.
await model.performOperation(op => {
  const defRef = op.createDefinition('Square');
  op.createFace(defRef, [
    [0, 0, 0], [24, 0, 0],
    [24, 24, 0], [0, 24, 0],
  ]);
  op.createInstance(
    model, defRef, Transformation.translation([0, 0, 0])
  );
  op.createInstance(
    model, defRef,
    Transformation.translation([36, 0, 0])
  );
}, 'Place two squares');

// Query back the instances.
let instances = await model.entities.get({
  filterBy: { types: ['ComponentInstance'] },
});
console.log(instances.length);
// => 2
console.log(instances[0].definitionId);
// => (numeric definition ID)

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 ComponentDefinition this instance references. Use the definition getter to fetch a ref you can resolve to the full definition object.

gluedToId

readonly gluedToId: SketchupId | undefined

A reference to the face this instance is glued to, if any. Some components (like sconces or windows) are designed to stick to faces. Returns undefined if the instance isn’t glued.

guid

readonly guid: string | undefined

A globally unique identifier for this instance. GUIDs persist across file saves and can be used to track instances even when they’re copied to other models. May be undefined for older models or instances created before SketchUp 2017.

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 component instance within the model. Persists across file saves.

locked

readonly locked: boolean

Whether this instance is locked. When locked, the user cannot move, scale, or delete the instance from the SketchUp UI.

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

An optional display name for this instance, like “Chair #1”. Most instances don’t have names — this is undefined unless explicitly set by the user or an extension.

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, rotates, and scales this instance in 3D space. Combines translation, rotation, and scaling into a single 4x4 matrix.

type

readonly type: ComponentInstance = EntityType.ComponentInstance

Accessors

definition

Get Signature

get definition(): ComponentDefinitionRef

Returns a lightweight reference to the ComponentDefinition this instance is a copy of. Resolve it with model.findEntity(ref) to get the full definition object.

Example

let model = await SketchUpApi.getActiveModel();
let instances = await model.entities.get({
  filterBy: { types: ['ComponentInstance'] },
});
let defRef = instances[0].definition;
let def = await model.findEntity(defRef);
console.log(def.name);

Since

SDK 2.17.0

Returns

ComponentDefinitionRef

sketchupId

Get Signature

get sketchupId(): SketchupId

JS API identifier for this component instance. 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<ComponentInstance>

Re-fetches this component instance from SketchUp to get its current state. Because ComponentInstance is a snapshot, it can become stale if the user moves or edits the instance. Call refresh() to get an up-to-date copy.

Returns

Promise<ComponentInstance>

A new ComponentInstance reflecting the current model state. Throws if the instance has been deleted.

Example

let model = await SketchUpApi.getActiveModel();
let instances = await model.entities.get({
  filterBy: { types: ['ComponentInstance'] },
});
// Sometime after the user changes the component...
let fresh = await instances[0].refresh();

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