ComponentDefinition

A reusable blueprint that defines the geometry and behavior of component instances in the model.

Component definitions are like templates or stamps — you define the geometry once (a chair, a tree, a window) and then place multiple instances of it throughout your model. When you edit the definition, all instances update automatically.

Every component definition has a name, a collection of entities (faces, edges, nested components), and optional behavior settings that control how instances appear (always facing camera, hole cutting, etc.). Groups in SketchUp are secretly component definitions with isGroup set to true.

Example

let model = await SketchUpApi.getActiveModel();

// Create a simple box component.
await model.performOperation(op => {
  const def = op.createDefinition('Box');
  // Add a face to the definition (top of the box).
  const faceRef = op.createFace(def, [
    [0, 0, 12], [12, 0, 12],
    [12, 12, 12], [0, 12, 12],
  ]);
  op.facePushPull(faceRef, 12, true);
  // Place an instance in the model.
  op.createInstance(
    model,
    def,
    SketchUpApi.Transformation.translation([0, 0, 0])
  );
}, 'Create box component');

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

behavior

readonly behavior: ComponentBehavior

Behavioral settings that control how instances of this definition render — whether they always face the camera, whether they’re 2D billboards, and how they scale. These settings are applied to every instance created from this definition.

See

SketchupComponentBehavior

castsShadows

readonly castsShadows: boolean

Whether this element casts shadows onto other geometry.

Inherited from

BaseDrawingElement.castsShadows

description

readonly description: string

A human-readable description of this component, like “Wooden dining chair with armrests”. Often empty for user-created components, but populated for library components from the 3D Warehouse.

guid

readonly guid: string

A globally unique identifier (GUID) for this component definition, used to track the same component across different models and saves. Formatted as a standard UUID string.

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 definition across sessions and saves.

isGroup

readonly isGroup: boolean

Whether this component definition is actually a group. Groups in SketchUp are implemented as single-instance component definitions with this flag set to true.

See

Group

isImage

readonly isImage: boolean

Whether this component definition represents an image entity. Image entities are internally stored as component definitions with a textured face.

isInternal

readonly isInternal: boolean

Whether this component definition is internal to SketchUp and hidden from the Component Browser. Examples include helper components used by native tools.

isLive

readonly isLive: boolean

Whether this component definition is a Live Component or a sub-definition of a Live Component. Live Components are parametric, data-driven components managed by SketchUp’s Live Component system.

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

The display name of this component definition, like “Chair #1” or “Window_24x36”. Can be changed by the user via the Entity Info dialog.

path

readonly path: string

The file system path where this component was originally loaded from, if it was imported from an external .skp file. Empty string for components created directly in the model.

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

type

readonly type: Component = EntityType.ComponentDefinition

Accessors

entities

Get Signature

get entities(): CallableEntities

An Entities collection containing all geometry and drawing elements inside this component definition — faces, edges, nested components, groups, etc. Use entities.get() to query them, or entities.getFaces(), entities.getEdges() for type-specific queries.

Example

let model = await SketchUpApi.getActiveModel();
let defs = await model.getDefinitions();
let entities = await defs[0].entities.get();
console.log(entities.length);
// => 6 (edges + faces in the definition)
let faces = await defs[0].entities.get({filterBy: {types:['Face']}});
console.log(faces[0].area());

Returns

CallableEntities

sketchupId

Get Signature

get sketchupId(): SketchupId

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

findClassifications()

findClassifications(schemaName): Attributes | undefined

Retrieves all classification attributes for this component definition under the given schema name. Returns an Attributes dictionary containing the full classification structure for that schema.

Parameters

Parameter	Type	Description
`schemaName`	`string`	The name of the classification schema to query, like “IFC 2x3”.

Returns

Attributes | undefined

An Attributes dictionary for the schema, or undefined if the schema isn’t applied to this component.

Since

SDK 2.35.0

findClassificationValue()

findClassificationValue(schemaName, path): AttributeValue

Retrieves a specific classification value from this component definition by its schema name and attribute path. Classifications in SketchUp are structured metadata applied to components — for example, IFC building classifications or custom schemas.

Parameters

Parameter	Type	Description
`schemaName`	`string`	The name of the classification schema to query, like “IFC 2x3”.
`path`	`string`[]	An array of keys forming the path to the desired value within the schema. For example, `["ObjectType", "Name"]` to retrieve the object type name.

Returns

AttributeValue

The attribute value at the specified path, or undefined if the path doesn’t exist.

Since

SDK 2.35.0

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

getInstances()

getInstances(): Promise<ComponentInstance[]>

Fetches all component instances placed in the model from this definition. If you’ve stamped the same component in ten different locations, this returns all ten instances. Includes instances nested inside groups and other components.

Returns

Promise<ComponentInstance[]>

A promise resolving to an array of all component instances created from this definition.

Example

let model = await SketchUpApi.getActiveModel();
let defs = await model.getDefinitions();
let instances = await defs[0].getInstances();
console.log(instances.length);
// => 3 (if there are 3 instances of this definition)
console.log(instances[0].transform.toArray());
// => [1, 0, 0, 0, ...] (transformation matrix)

Since

SDK 2.30.0

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

observeInstanceChanges()

observeInstanceChanges(callback): ObserverHandle

Starts observing changes to instances of this component definition. The callback fires whenever instances are added to or removed from the model, whether by user actions, undo/redo, or API operations. Use this to track how many instances exist, or to respond when instances are created or deleted.

Parameters

Parameter	Type	Description
`callback`	(`added`, `removedIds`, `source`) => `void`	Invoked with arrays of added instances, removed instance IDs, and the change source (user, API, undo, etc.).

Returns

ObserverHandle

An ObserverHandle with a close() method to stop observing.

Example

let model = await SketchUpApi.getActiveModel();
let defs = await model.getDefinitions();
let handle = defs[0].observeInstanceChanges(
  (added, removedIds, source) => {
    console.log(`Added: ${added.length}`);
    console.log(`Removed: ${removedIds.length}`);
  }
);
// Later, stop observing.
handle.close();

Since

SDK 2.30.0

refresh()

refresh(): Promise<ComponentDefinition>

Re-fetches this component definition from SketchUp to get its current state. Because ComponentDefinition is a snapshot, it can become stale if the definition is modified (entities added, name changed, behavior updated). Call refresh() to get an up-to-date copy.

Returns

Promise<ComponentDefinition>

A new ComponentDefinition reflecting the current state. Throws if the definition has been deleted.

Example

let model = await SketchUpApi.getActiveModel();
let defs = await model.getDefinitions();
// Later, after the user makes changes...
let freshDef = await defs[0].refresh();
console.log(freshDef.name);

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[]>

Fetches all component instances nested inside this component definition. This returns instances placed within this definition’s entities collection (nested components), not instances of this definition elsewhere in the model. For that, use getInstances.

Parameters

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

Returns

Promise<readonly ComponentInstance[]>

A promise resolving to an array of component instances.

constructionLines()

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

Fetches all construction lines inside this component definition. letruction lines are infinite guide lines used for modeling alignment.

Parameters

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

Returns

Promise<readonly ConstructionLine[]>

A promise resolving to an array of construction lines.

Since

SDK 2.7.0 Protocol 1.5.0

constructionPoints()

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

Fetches all construction points inside this component definition. letruction points are guide points used for modeling alignment.

Parameters

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

Returns

Promise<readonly ConstructionPoint[]>

A promise resolving to an array of construction points.

Since

SDK 2.7.0 Protocol 1.5.0

curves()

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

Fetches all curves (including arc curves) inside this component definition. Curves are collections of connected edges that form smooth paths, like circles, arcs, or polylines.

Parameters

Parameter	Type	Default value	Description
`filter`	`SketchupEntityFilter` \| `undefined`	`undefined`	Optional filter to apply.

Returns

Promise<readonly (ArcCurve | Curve)[]>

A promise resolving to an array of Curve and ArcCurve objects.

Since

SDK 2.23.0 Protocol 1.20.0

dimensionLinears()

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

Fetches all linear dimension entities inside this component definition. Linear dimensions measure distances between two points with annotation text.

Parameters

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

Returns

Promise<readonly DimensionLinear[]>

A promise resolving to an array of linear dimension entities.

Since

SDK 2.23.0 Protocol 1.20.0

dimensionRadials()

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

Fetches all radial dimension entities inside this component definition. Radial dimensions measure arcs and circles with annotation text.

Parameters

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

Returns

Promise<readonly DimensionRadial[]>

A promise resolving to an array of radial dimension entities.

Since

SDK 2.23.0 Protocol 1.20.0

edges()

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

Fetches all edges inside this component definition. Edges are line segments connecting vertices — this returns every edge directly contained by this definition, including both standalone edges and face boundaries.

Parameters

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

Returns

Promise<readonly Edge[]>

A promise resolving to an array of edges.

faces()

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

Fetches all faces inside this component definition. Faces are the visible surfaces in SketchUp geometry — this returns every face directly contained by this definition.

Parameters

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

Returns

Promise<readonly Face[]>

A promise resolving to an array of faces.

getActiveSectionPlane()

getActiveSectionPlane(): Promise<SectionPlane | undefined>

Fetches the currently active section plane for this component definition, if any. Only one section plane can be active at a time in a given context.

Returns

Promise<SectionPlane | undefined>

A promise resolving to the active SectionPlane, or undefined if no section plane is active.

Since

SDK 2.16.0 Protocol 1.13.0

getClassifications()

getClassifications(schemaName): Attributes | undefined

Parameters

Parameter	Type
`schemaName`	`string`

Returns

Attributes | undefined

getClassificationValue()

getClassificationValue(schemaName, path): AttributeValue

Parameters

Parameter	Type
`schemaName`	`string`
`path`	`string`[]

Returns

AttributeValue

groups()

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

Fetches all groups inside this component definition. Groups are nested entity containers — this returns only the groups directly contained by this definition.

Parameters

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

Returns

Promise<readonly Group[]>

A promise resolving to an array of groups.

images()

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

Fetches all image entities inside this component definition. Image entities are bitmap textures placed in 3D space.

Parameters

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

Returns

Promise<readonly ImageEntity[]>

A promise resolving to an array of image entities.

Since

SDK 2.21.0 Protocol 1.18.0

instances()

instances(): Promise<readonly ComponentInstance[]>

Returns

Promise<readonly ComponentInstance[]>

sectionPlanes()

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

Fetches all section planes inside this component definition. Section planes are cutting planes that slice through the model to show interior views.

Parameters

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

Returns

Promise<readonly SectionPlane[]>

A promise resolving to an array of section planes.

Since

SDK 2.16.0 Protocol 1.13.0

snaps()

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

Fetches all snaps inside this component definition. Snaps are magnetic inference points that help users align geometry while modeling.

Parameters

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

Returns

Promise<readonly Snap[]>

A promise resolving to an array of snaps.

Since

SDK 2.20.0 Protocol 1.17.0

streamInstanceChanges()

streamInstanceChanges(callback): ObserverHandle

Parameters

Parameter	Type
`callback`	(`added`, `removedIds`, `source`) => `void`

Returns

ObserverHandle

texts()

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

Fetches all text entities inside this component definition. Text entities are 2D or 3D labels with optional leader lines.

Parameters

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

Returns

Promise<readonly Text[]>

A promise resolving to an array of text entities.

Since

SDK 2.22.0 Protocol 1.19.0