InstancePath

An address describing where an entity lives inside nested groups or components.

Think of it as a breadcrumb trail: “model → House group → Room group → this edge.” You’ll encounter InstancePath objects as properties on entities that track attachment — for example, DimensionLinear.startAttachedTo returns an InstancePath when a dimension is measuring geometry inside a nested container.

The leaf getter returns the final entity in the path if it’s not a container (Group, ComponentInstance, Image). If the path ends on a container, leaf is undefined.

Example

let model = await SketchUpApi.getActiveModel();

// Build nested groups: House > Room > Table
let table = null;
await model.performOperation(op => {
  const house = op.createGroup(model);
  op.groupSetName(house, 'House');
  op.createFace(house, [
    [0, 0, 0], [200, 0, 0],
    [200, 200, 0], [0, 200, 0],
  ]);
  const room = op.createGroup(house);
  op.groupSetName(room, 'Room');
  table = op.createGroup(room);
  op.groupSetName(table, 'Table');
  op.createFace(table, [
    [30, 30, 10], [50, 30, 10],
    [50, 50, 10], [30, 50, 10],
  ]);
}, 'Create nested groups');

// Attach a text label to geometry inside
// the nested table group.
let groups = await model.entities.get({
  filterBy: { types: ['Group'] },
});
let house = groups.find(
  g => g.name === 'House'
);
let rooms = await house.entities.get({
  filterBy: { types: ['Group'] },
});
let room = rooms[0];
let tables = await room.entities.get({
  filterBy: { types: ['Group'] },
});
let tbl = tables[0];
let edges = await tbl.entities.get({
  filterBy: { types: ['Edge'] },
});

await model.performOperation(op => {
  op.createText(
    model,
    'Table surface',
    {
      point: [30, 30, 10],
      instancePath: [house, room, tbl, edges[0]],
    },
    [0, 0, 30]
  );
}, 'Label the table');

// Query back — the text tracks its path
let texts = await model.entities.get({
  filterBy: { types: ['Text'] },
});
let label = texts.find(
  t => t.text === 'Table surface'
);
console.log(label.attachedTo.instancePath.length);
// => 4 (House, Room, Table, Edge)

See

Since

SDK 2.23.0

Constructor

new InstancePath(path): InstancePath

The ordered list of entities from the model root to the target entity. Each element is either a full entity object or a lightweight reference.

Parameters

Parameter	Type
`path`	(`Entity` \| `EntityRef`)[]

Returns

InstancePath

Properties

path

readonly path: (Entity | EntityRef)[]

Accessors

leaf

Get Signature

get leaf(): Entity | EntityRef | undefined

The final entity in the path, but only if it’s not a container type (Group, ComponentInstance, or Image). Returns undefined if the path is empty or if the last element is a container.

Returns

Entity | EntityRef | undefined

sketchupIds

Get Signature

get sketchupIds(): SketchupId[]

Extracts the SketchupId for each entity in the path, suitable for passing to protocol methods that expect ID arrays.

Returns

SketchupId[]

Methods

toString()

toString(): string

Returns

string