Operation

The SketchUp JavaScript API is currently a labs feature.
Signup as a developer and try it out.

The mutation API for SketchUp models — every geometry change, material assignment, and entity modification happens through methods on this class.

You receive a SketchupOperation inside the callback passed to model.performOperation(). The operation batches your instructions and sends them to SketchUp efficiently. Most methods are synchronous (they queue instructions without waiting), but you can call await on queries mid-operation to read back geometry created earlier in the same callback.

Operation refs (like FaceRef, EdgeRef, MaterialRef) are lightweight handles returned by create methods. They’re only valid within the operation callback that created them. To read an entity’s properties outside the operation, call entityForRef(ref) to fetch the full entity object before the callback ends.

Outside the scope of performOperation, the operation is closed and methods will throw errors.

Example

let model = await SketchUpApi.getActiveModel();

// Create a rectangle, then extrude it.
await model.performOperation(op => {
  // Create a material
  const red = op.createMaterial('RedBrick');
  op.materialSetColor(
    red, new SketchUpApi.Color(200, 50, 50)
  );

  // Create a face
  const faceRef = op.createFace(model, [
    [0, 0, 0], [100, 0, 0],
    [100, 100, 0], [0, 100, 0],
  ]);

  // Apply material and extrude
  op.drawingElementSetMaterial(faceRef, red);
  op.facePushPull(faceRef, 50);
}, 'Create red box');

See

• Model.performOperation
• Model.startOperation
• OperationOptions

ArcCurve

createArc()

createArc(container, center, xaxis, normal, radius, startAngle, endAngle, numSegments?): ArcCurveAndComponents

Creates an arc of a circle on the container.

Because SketchUp intersects and deduplicates edges, multiple curves may result from a single call. This method returns a reference to the curve associated with the first edge. Use Model.findCurvesForEdges to find all curves produced by this instruction.

Parameters

Parameter	Type	Description
container	EntitiesContainer | EntitiesContainerRef	The container to create the arc on.
center	Point3Like	The center point of the arc.
xaxis	Vector3Like	The direction of the xaxis, the angles are taken from this axis.
normal	Vector3Like	The normal of the arc.
radius	number	The radius of the arc in inches.
startAngle	number	Start angle for the arc, in radians.
endAngle	number	End angle for the arc, in radians.
numSegments?	number	the number of segments of the arc (by default 24).

Returns

ArcCurveAndComponents

An arc and any edges created

Example

let model = await SketchUpApi.getActiveModel();
let arc = await model.performOperation(op => {
  const arcAndEdges = op.createArc(op.model,
    [0, 0, 0], [1, 0, 0], [0, 0, 1],
    50, 0, Math.PI
  );
  return op.entityForRef(arcAndEdges.curve);
}, 'Create arc');
console.log(arc);

Since

SDK 2.30.0 Protocol 1.20.0

See

ArcCurve for code examples

---

createCircle()

createCircle(container, center, normal, radius, numSegments?): ArcCurveAndComponents

Creates a full circle on the container. Because SketchUp intersects and deduplicates edges, multiple curves may result from a single call. This method returns a reference to the curve associated with the first edge. Use Model.findCurvesForEdges to find all curves produced by this instruction.

Parameters

Parameter	Type	Default value	Description
container	EntitiesContainer | EntitiesContainerRef	undefined	The container to create the circle on.
center	Point3Like	undefined	The center point of the circle.
normal	Vector3Like	undefined	The normal vector (perpendicular to the circle plane).
radius	number	undefined	The radius in inches.
numSegments	number	24	The number of edge segments (default 24).

Returns

ArcCurveAndComponents

An arc curve and any edges created.

Example

let model = await SketchUpApi.getActiveModel();
let circle = await model.performOperation(op => {
  const circleAndEdges = op.createCircle(
    op.model, [0, 0, 0], [0, 0, 1], 75
  );
  return op.entityForRef(circleAndEdges.curve);
}, 'Create circle');
console.log(circle);

Since

SDK 2.30.0 Protocol 1.20.0

See

ArcCurve for code examples

---

createNgon()

createNgon(container, center, normal, radius, numSegments?): ArcCurveAndComponents

Creates an n-gon (regular polygon) on the container — similar to createCircle but also creates a face bounded by the edges.

Because SketchUp intersects and deduplicates edges, multiple curves may result from a single call. This method returns a reference to the curve associated with the first edge. Use Model.findCurvesForEdges to find all curves produced by this instruction.

Parameters

Parameter	Type	Default value	Description
container	EntitiesContainer | EntitiesContainerRef	undefined	The container to create the n-gon on.
center	Point3Like	undefined	The center point.
normal	Vector3Like	undefined	The normal vector (perpendicular to the polygon plane).
radius	number	undefined	The radius in inches.
numSegments	number	24	The number of sides (default 24).

Returns

ArcCurveAndComponents

An arc curve and any edges created.

Example

let model = await SketchUpApi.getActiveModel();
let hexagon = await model.performOperation(op => {
  const ngonAndEdges = op.createNgon(
    op.model, [0, 0, 0], [0, 0, 1], 50, 6
  );
  return op.entityForRef(ngonAndEdges.curve);
}, 'Create hexagon');
console.log(hexagon);

Since

SDK 2.30.0 Protocol 1.20.0

See

ArcCurve for code examples

---

curveMoveVertices()

curveMoveVertices(curve, newPoints): void

Moves the vertices of the curve to new positions. The number of points must exactly match the number of vertices in the curve, otherwise SketchUp will throw an error.

Parameters

Parameter	Type	Description
curve	ArcCurve | Curve | ArcCurveRef | CurveRef	the curve
newPoints	Point3Like[]	the new positions for each vertex

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let curve = await model.performOperation(op => {
  const curveAndEdges = op.createCurve(op.model, [
    [0, 0, 0], [50, 25, 0], [100, 0, 0]
  ]);
  op.curveMoveVertices(curveAndEdges.curve, [
    [0, 0, 0], [50, 50, 0], [100, 0, 0]
  ]);
  return op.entityForRef(curveAndEdges.curve);
}, 'Move curve vertices');
console.log(curve.vertices.map(v => v.y));
// => [0, 50, 0]

Since

SDK 2.23.0 Protocol 1.20.0

ComponentDefinition

createDefinition()

createDefinition(name): ComponentDefinitionRef

Creates a new component definition with the given name. If the name already exists, SketchUp appends a randomized suffix to make it unique.

The returned ref is only valid within this operation. To access the definition after the operation ends, convert it with entityForRef(defRef).

Parameters

Parameter	Type	Description
name	string	the name of the component

Returns

ComponentDefinitionRef

reference to the created component definition

Example

let model = await SketchUpApi.getActiveModel();
let def = await model.performOperation(op => {
  const defRef = op.createDefinition('MyComponent');
  op.createFace(defRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  return op.entityForRef(defRef);
}, 'Create definition');
console.log(def);

See

ComponentDefinition for code examples

Since

SDK 2.30.0

---

definitionAddClassification()

definitionAddClassification(ref, schemaName, schemaType): void

Assigns a classification type from a loaded schema (like IFC) to a component. Once classified, the component carries metadata that other tools (BIM software, exporters) can read. Load schemas first with modelLoadSchemaFromUrl.

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component or component reference
schemaName	string	the name of the loaded classification schema
schemaType	string	the type within that schema to assign

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Load IFC schema, skipping if already loaded
  const schemas = await model.getClassifications();
  const isLoaded = schemas.some(
    s => s.name === 'IFC 2x3'
  );
  if (!isLoaded) {
    const url = 'https://cdn.habitat.sketchup.com/' +
      'classifications/schemas/IFC2x3.skc';
    await op.modelLoadSchemaFromUrl(url);
  }
  // Create component with geometry
  const defRef = op.createDefinition('DoorComp');
  await op.createBuilder((builder) => {
    // Vertical door-shaped rectangle (X/Z plane)
    builder.createFace([
      [0, 0, 0], [36, 0, 0],
      [36, 0, 80], [0, 0, 80]
    ]);
  }).build(defRef);
  // Add classification
  op.definitionAddClassification(
    defRef, 'IFC 2x3', 'IfcDoor'
  );
}, 'Add IFC classification');

Since

SDK 2.30.0 Protocol 1.3.0

---

definitionRemoveClassification()

definitionRemoveClassification(ref, schemaName, schemaType): void

Removes a previously assigned classification from a component, stripping the associated schema metadata. Useful when the component’s type changes or the classification was assigned in error.

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component or component reference
schemaName	string	the name of the classification schema
schemaType	string	the type to remove

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Load IFC schema, skipping if already loaded
  const schemas = await model.getClassifications();
  const isLoaded = schemas.some(
    s => s.name === 'IFC 2x3'
  );
  if (!isLoaded) {
    const url = 'https://cdn.habitat.sketchup.com/' +
      'classifications/schemas/IFC2x3.skc';
    await op.modelLoadSchemaFromUrl(url);
  }
  // Create component with geometry
  const defRef = op.createDefinition('DoorComp');
  await op.createBuilder((builder) => {
    // Vertical door-shaped rectangle (X/Z plane)
    builder.createFace([
      [0, 0, 0], [36, 0, 0],
      [36, 0, 80], [0, 0, 80]
    ]);
  }).build(defRef);
  // Add and remove classification
  op.definitionAddClassification(
    defRef, 'IFC 2x3', 'IfcDoor'
  );
  op.definitionRemoveClassification(
    defRef, 'IFC 2x3', 'IfcDoor'
  );
}, 'Remove classification');

Since

SDK 2.30.0 Protocol 1.3.0

---

definitionSetClassificationValue()

definitionSetClassificationValue(ref, path, value): void

Sets a specific property value within a component’s classification data. The path navigates the classification hierarchy to the target attribute, like ['IFC 2x3', 'IfcDoor', 'Name', 'IfcLabel'].

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component or component reference
path	string[]	key path to the classification attribute
value	AttributeValue	the value to set (must be valid for that attribute’s type)

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Load IFC schema, skipping if already loaded
  const schemas = await model.getClassifications();
  const isLoaded = schemas.some(
    s => s.name === 'IFC 2x3'
  );
  if (!isLoaded) {
    const url = 'https://cdn.habitat.sketchup.com/' +
      'classifications/schemas/IFC2x3.skc';
    await op.modelLoadSchemaFromUrl(url);
  }
  // Create component with geometry
  const defRef = op.createDefinition('DoorComp');
  await op.createBuilder((builder) => {
    // Vertical door-shaped rectangle (X/Z plane)
    builder.createFace([
      [0, 0, 0], [36, 0, 0],
      [36, 0, 80], [0, 0, 80]
    ]);
  }).build(defRef);
  // Add classification and set property
  op.definitionAddClassification(
    defRef, 'IFC 2x3', 'IfcDoor'
  );
  op.definitionSetClassificationValue(
    defRef,
    ['IFC 2x3', 'IfcDoor', 'Name', 'IfcLabel'],
    'MainEntrance'
  );
}, 'Set classification value');

Since

SDK 2.30.0 Protocol 1.3.0

---

definitionSetDescription()

definitionSetDescription(ref, value): void

Sets the description for a component definition. The description appears in the Component Browser and can explain what the component represents, its design intent, or usage instructions.

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component or component reference
value	string	the description text

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const defRef = op.createDefinition('DoorFrame');
  await op.createBuilder((builder) => {
    // Vertical rectangle on the X/Z plane
    builder.createFace([
      [0, 0, 0], [36, 0, 0],
      [36, 0, 80], [0, 0, 80]
    ]);
  }).build(defRef);
  op.definitionSetDescription(
    defRef, 'Standard wooden frame for doors'
  );
}, 'Set component description');

Since

SDK 2.30.0

---

definitionSetName()

definitionSetName(ref, value): void

Renames a component definition. The name appears in the Component Browser and must be unique within the model — SketchUp may append a suffix if a conflict exists. Renaming here updates the definition; instance names are separate.

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component or component reference
value	string	the new name

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const defRef = op.createDefinition('OldName');
  await op.createBuilder((builder) => {
    // Vertical rectangle on the X/Z plane
    builder.createFace([
      [0, 0, 0], [50, 0, 0],
      [50, 0, 50], [0, 0, 50]
    ]);
  }).build(defRef);
  op.definitionSetName(defRef, 'WindowFrame');
}, 'Rename component');

Since

SDK 2.30.0

---

definitionSetNoScaleMask()

definitionSetNoScaleMask(ref, value): void

Controls which axes and planes are locked when the user scales an instance of this component. Use this to prevent non-uniform scaling on certain axes — for example, to keep a column always uniform in X/Z while allowing Y (height) to stretch freely.

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component or component reference
value	Partial<ComponentScaling>	which scaling axes/planes are locked

Returns

void

Example

let model = await SketchUpApi.getActiveModel();

await model.performOperation(op => {
  const defRef =
    op.createDefinition('ScaleTestColumn');

  // Build a cube inside the definition
  const faceRef = op.createFace(defRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0],
  ]);
  op.facePushPull(faceRef, 100);

  // Lock X and Y — only Z (up/down) can scale
  op.definitionSetNoScaleMask(defRef, {
    disableRed: true,
    disableBlue: true,
    disableRedBlue: true,
    disableRedGreen: true,
  });

  op.createInstance(
    model, defRef,
    SketchUpApi.Transformation.IDENTITY
  );
}, 'Create scale-locked column');

See

ComponentScaling

Since

SDK 2.30.0

---

definitionSetShadowsToFaceSun()

definitionSetShadowsToFaceSun(ref, value): void

Controls whether the shadow cast by this component always faces the sun, regardless of the component’s actual geometry. When enabled, the shadow behaves like a flat plane perpendicular to the sun — commonly used for 2D tree or person cutouts.

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component or component reference
value	boolean	when true, the shadow always faces the sun

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const treeGreen = op.createMaterial('TreeGreen');
  op.materialSetColor(
    treeGreen, new SketchUpApi.Color(34, 139, 34)
  );
  const defRef = op.createDefinition('Tree');
  await op.createBuilder((builder) => {
    return builder.createFace([
      [0, 0, 0], [100, 0, 0],
      [100, 100, 0], [0, 100, 0]
    ]);
  }).onPostBuild((converter, buildFaceRef) => {
    const faceRef = converter.asRef(buildFaceRef);
    op.drawingElementSetMaterial(faceRef, treeGreen);
    op.facePushPull(faceRef, 250);
  }).build(defRef);
  op.definitionSetShadowsToFaceSun(
    defRef, true
  );
}, 'Create sun-facing shadow component');

Since

SDK 2.30.0

---

definitionSetTo2d()

definitionSetTo2d(ref, value): void

Marks this component as a 2D flat cutout that always faces the camera. This is the “Always face camera” option in the Component Options panel — useful for trees, people, and other billboard- style objects that should always appear face-on to the viewer.

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component or component reference
value	boolean	when true, the component always rotates to face the camera

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const green = op.createMaterial('Green');
  op.materialSetColor(
    green, new SketchUpApi.Color(144, 238, 144)
  );
  const defRef = op.createDefinition('Billboard');
  await op.createBuilder((builder) => {
    return builder.createFace([
      [0, 0, 0], [100, 0, 0],
      [100, 0, 0], [0, 100, 0]
    ]);
  }).onPostBuild((converter, buildFaceRef) => {
    const faceRef = converter.asRef(buildFaceRef);
    op.drawingElementSetMaterial(faceRef, green);
  }).build(defRef);
  op.definitionSetTo2d(defRef, true);
  op.createInstance(
    op.model, defRef,
    SketchUpApi.Transformation.IDENTITY
  );
}, 'Create billboard component');

Since

SDK 2.30.0

---

definitionSetToCutOpening()

definitionSetToCutOpening(ref, value): void

Controls whether instances of this component automatically cut a hole through any face they are placed on. Useful for doors, windows, and other components that need an opening in a wall.

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component or component reference
value	boolean	when true, placed instances cut an opening in faces

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let def = await model.performOperation(async op => {
  const brown = op.createMaterial('Brown');
  op.materialSetColor(
    brown, new SketchUpApi.Color(139, 69, 19)
  );
  const defRef = op.createDefinition('WindowHole');
  await op.createBuilder((builder) => {
    // 2d components are modeled on the XY plane frame (X/Y plane) with a
    // hole cut in the middle
    return builder.createFace(
      [
        [0, 0, 0], [100, 0, 0],
        [100, 100, 0], [0, 100, 0]
      ],
      [[
        [75, 25, 0], [75, 75, 0],
        [25, 75, 0], [25, 25, 0]
      ]]
    );
  }).onPostBuild((converter, buildFaceRef) => {
    const faceRef = converter.asRef(buildFaceRef);
    op.drawingElementSetMaterial(faceRef, brown);
  }).build(defRef);
  op.definitionSetTo2d(defRef, true);
  op.definitionSetToSnapTo(defRef,
   SketchUpApi.ComponentSnapTo.Vertical);
  op.definitionSetToCutOpening(defRef, true);
  return op.entityForRef(defRef);
}, 'Create cut-opening component');

console.log('Glue the component to a vertical face to see the behavior');

Since

SDK 2.30.0

---

definitionSetToFaceCamera()

definitionSetToFaceCamera(ref, value): void

Controls whether instances of this component automatically rotate to face the camera (like 2D trees or people cutouts). When enabled, the component’s front face always points toward the viewer regardless of the camera angle.

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component definition or reference
value	boolean	true to enable always-face-camera behavior

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const pink = op.createMaterial('Pink');
  op.materialSetColor(
    pink, new SketchUpApi.Color(255, 105, 180)
  );
  const defRef = op.createDefinition('SignBoard');
  await op.createBuilder((builder) => {
    return builder.createFace([
      [0, 0, 0], [80, 0, 0],
      [80, 0, 80], [0, 0, 80]
    ]);
  }).onPostBuild((converter, buildFaceRef) => {
    const faceRef = converter.asRef(buildFaceRef);
    op.drawingElementSetMaterial(faceRef, pink);
  }).build(defRef);
  op.definitionSetTo2d(defRef, true);
  op.definitionSetToFaceCamera(defRef, true);
}, 'Create face-camera component');

Since

SDK 2.30.0

---

definitionSetToSnapTo()

definitionSetToSnapTo(ref, value): void

Controls what surface the component snaps to when the user places or moves an instance. For example, a chair component can snap to horizontal floors, a picture can snap to vertical walls, or a light can snap to sloped ceilings.

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component or component reference
value	ComponentSnapTo	the surface type this component snaps to when placed

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const gold = op.createMaterial('Gold');
  op.materialSetColor(
    gold, new SketchUpApi.Color(255, 215, 0)
  );
  const defRef = op.createDefinition('PictureFrame');
  await op.createBuilder((builder) => {
    // 2D snapping components must be modeled on the X/Y plane.
    return builder.createFace([
      [0, 0, 0], [50, 0, 0],
      [50, 50, 0], [0, 50, 0]
    ]);
  }).onPostBuild((converter, buildFaceRef) => {
    const faceRef = converter.asRef(buildFaceRef);
    op.drawingElementSetMaterial(faceRef, gold);
  }).build(defRef);
  op.definitionSetTo2d(defRef, true);
  op.definitionSetToSnapTo(defRef,
    SketchUpApi.ComponentSnapTo.Vertical
  );
}, 'Create snap-to-vertical component');

Since

SDK 2.30.0

---

loadDefinition()

loadDefinition(options): Promise<ComponentDefinitionRef>

Loads a component definition from an external resource (URL, Blob, or data URL) and adds it to the model. The resource must be a valid .skp file. Use this to import pre-built components from a library or CDN.

Parameters

Parameter	Type	Description
options	ComponentLoadOptions	resource and loading configuration

Returns

Promise<ComponentDefinitionRef>

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const defRef = await op.loadDefinition({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'examples/models/Bed.skp'
    }
  });
  op.createInstance(
    op.model, defRef,
    SketchUpApi.Transformation.IDENTITY
  );
}, 'Load component from CDN');

Since

SDK 2.30.0 Protocol 1.4.0

Throws

ComponentLoadError if SketchUp cannot parse the resource or the endpoint returns a non-2xx status

---

purgeUnusedDefinitions()

purgeUnusedDefinitions(): void

Removes all component definitions that have zero instances placed in the model. This reduces file size by cleaning up definitions that are no longer in use.

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Load a definition but never place an instance
  await op.loadDefinition({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'examples/models/Bed.skp'
    }
  });
  // Purge removes it since it's unused
  op.purgeUnusedDefinitions();
}, 'Purge unused definitions');

Since

SDK 2.30.0

---

removeDefinition()

removeDefinition(ref): void

Permanently removes a component definition from the model. All placed instances of this definition are also deleted.

Parameters

Parameter	Type	Description
ref	ComponentDefinition | ComponentDefinitionRef	the component definition or reference to remove

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const defRef = await op.loadDefinition({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'examples/models/Bed.skp'
    }
  });
  op.removeDefinition(defRef);
}, 'Remove component definition');

Since

SDK 2.30.0

ComponentInstance

createInstance()

createInstance(ref, componentRef, transform?): ComponentInstanceRef

Places an instance of a component definition into the model. Component instances are reusable copies of a shared definition — editing the definition updates all instances. The optional transformation positions, rotates, and scales the instance relative to its parent container’s axes.

Returns a ComponentInstanceRef that’s valid only within this operation. To read the instance’s properties or use it outside the operation callback, call entityForRef(instanceRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the instance will be placed (model, group, or another component instance).
componentRef	ComponentDefinition | ComponentDefinitionRef	The component definition to instantiate.
transform?	TransformationLike	Optional transformation to apply to the instance. Defaults to identity (origin with no rotation or scaling).

Returns

ComponentInstanceRef

A reference to the newly created component instance.

Example

let model = await SketchUpApi.getActiveModel();
let defs = await model.getDefinitions();
if (defs.length === 0) {
  console.log('there are no definitions');
} else {
  let instance =
    await model.performOperation(op => {
    const instanceRef = op.createInstance(
      op.model, defs[0]
    );
    return op.entityForRef(instanceRef);
  }, 'Create instance');
  console.log(instance);
}

See

• ComponentInstance for code examples
• entityForRef

Since

SDK 2.30.0

---

instanceApplyTransformation()

instanceApplyTransformation(ref, transformation): void

Multiplies the component instance’s current transformation by the given transformation, moving or rotating it relative to its current position. Use this for incremental movement. To set an absolute position, use instanceSetTransformation.

Parameters

Parameter	Type	Description
ref	ComponentInstance | ComponentInstanceRef	the component instance or component instance reference
transformation	TransformationLike	the transformation to compound with the current one

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create instance at origin
let instanceRef = await model.performOperation(
  async op => {
    const bedDef = await op.loadDefinition({
      resource: {
        request: 'https://cdn.habitat.sketchup.com/' +
          'examples/models/Bed.skp'
      }
    });
    const ref = op.createInstance(
      op.model, bedDef,
      SketchUpApi.Transformation.translation(
        [300, 0, 0]
      )
    );
    return op.entityForRef(ref);
  }, 'Create instance at origin'
);
// Second operation: apply relative transformation
await model.performOperation(op => {
  op.instanceApplyTransformation(
    instanceRef,
    SketchUpApi.Transformation.translation(
      [0, 100, 0]
    )
  );
}, 'Apply instance transformation');

Since

SDK 2.30.0 Protocol 0.4.0

---

instanceSetGluedTo()

instanceSetGluedTo(entity, element): void

Attaches (glues) a component instance or group to a face, so it moves and rotates with that face. Gluing is how windows stay in walls and decals stick to surfaces. Pass undefined to detach the instance from its current face.

Parameters

Parameter	Type	Description
entity	ComponentInstance | Group | ComponentInstanceRef | GroupRef	the group or component instance to glue
element	CanBeGluedToRef | CanBeGluedTo | undefined	the face to glue it to, or undefined to unglue

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Floor face on the X/Y plane
  const floorRef = op.createFace(op.model, [
    [300, 0, 0], [500, 0, 0],
    [500, 500, 0], [300, 500, 0]
  ]);
  const bedDef = await op.loadDefinition({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'examples/models/Bed.skp'
    }
  });
  // Glueable components must allow gluing
  op.definitionSetTo2d(bedDef, true);
  const instanceRef = op.createInstance(
    op.model, bedDef,
    SketchUpApi.Transformation.translation(
      [400, 0, 0]
    )
  );
  op.instanceSetGluedTo(instanceRef, floorRef);
}, 'Glue instance to floor face');

Since

SDK 2.30.0 Protocol 1.18.0

---

instanceSetLocked()

instanceSetLocked(ref, value): void

Locks or unlocks a component instance. Locked instances cannot be moved, edited, or deleted by the user in the viewport.

Parameters

Parameter	Type	Description
ref	ComponentInstance | ComponentInstanceRef	the component instance or component instance reference
value	boolean	true to lock, false to unlock

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const bedDef = await op.loadDefinition({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'examples/models/Bed.skp'
    }
  });
  const instanceRef = op.createInstance(
    op.model, bedDef,
    SketchUpApi.Transformation.translation(
      [100, 0, 0]
    )
  );
  op.instanceSetLocked(instanceRef, true);
}, 'Lock component instance');

Since

SDK 2.30.0 Protocol 0.4.0

---

instanceSetName()

instanceSetName(ref, value): void

Gives a component instance a user-visible name. Each instance can have its own name independent of its definition name — this shows in the Outliner panel and Entity Info.

Parameters

Parameter	Type	Description
ref	ComponentInstance | ComponentInstanceRef	the component instance or component instance reference
value	string	the display name, like "Front Door"

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const bedDef = await op.loadDefinition({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'examples/models/Bed.skp'
    }
  });
  const instanceRef = op.createInstance(
    op.model, bedDef,
    SketchUpApi.Transformation.translation(
      [0, 0, 0]
    )
  );
  op.instanceSetName(instanceRef, 'GuestBed');
}, 'Set instance name');

Since

SDK 2.30.0 Protocol 1.2.0

---

instanceSetTransformation()

instanceSetTransformation(ref, transformation): void

Replaces the component instance’s transformation with a new one, absolutely positioning and orienting it within its container. Use this for exact placement. To move an instance relative to its current position, use instanceApplyTransformation.

Parameters

Parameter	Type	Description
ref	ComponentInstance | ComponentInstanceRef	the component instance or component instance reference
transformation	TransformationLike	the new absolute transformation within its container

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create instance at origin
let instanceRef = await model.performOperation(
  async op => {
    const bedDef = await op.loadDefinition({
      resource: {
        request: 'https://cdn.habitat.sketchup.com/' +
          'examples/models/Bed.skp'
      }
    });
    const ref = op.createInstance(
      op.model, bedDef,
      SketchUpApi.Transformation.translation(
        [200, 0, 0]
      )
    );
    return op.entityForRef(ref);
  }, 'Create instance at origin'
);
// Second operation: set absolute transformation
await model.performOperation(op => {
  op.instanceSetTransformation(
    instanceRef,
    SketchUpApi.Transformation.translation(
      [200, 100, 0]
    )
  );
}, 'Set instance transformation');

Since

SDK 2.30.0 Protocol 0.4.0

ConstructionLine

constructionLineReverse()

constructionLineReverse(ref): void

Reverses the direction of a construction line, swapping its start and end points (or flipping the direction vector for infinite lines).

Parameters

Parameter	Type	Description
ref	ConstructionLine | ConstructionLineRef	the construction line or reference

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create a simple line
let lineRef = await model.performOperation(op => {
  const ref = op.createConstructionLine(
    op.model,
    new SketchUpApi.Point3d(600, 0, 0),
    new SketchUpApi.Point3d(600, 100, 0)
  );
  return op.entityForRef(ref);
}, 'Create construction line');
// Second operation: reverse start/end
await model.performOperation(op => {
  op.constructionLineReverse(lineRef);
}, 'Reverse construction line');

Since

SDK 2.7.0 Protocol 1.5.0

---

constructionLineSetDirection()

constructionLineSetDirection(ref, direction): void

Sets the direction vector of a construction line. For infinite lines, this determines the angle of the guide. For finite lines, the direction is derived from start/end points.

Parameters

Parameter	Type	Description
ref	ConstructionLine | ConstructionLineRef	the construction line or reference
direction	Vector3d | Point3d	the new direction vector

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create an infinite line
let lineRef = await model.performOperation(op => {
  const ref = op.createConstructionLine(
    op.model,
    new SketchUpApi.Point3d(300, 0, 0),
    new SketchUpApi.Vector3d(0, 1, 0)
  );
  return op.entityForRef(ref);
}, 'Create infinite construction line');
// Second operation: change its direction
await model.performOperation(op => {
  op.constructionLineSetDirection(
    lineRef,
    new SketchUpApi.Vector3d(0, 1, 1)
  );
}, 'Set construction line direction');

Since

SDK 2.7.0 Protocol 1.5.0

---

constructionLineSetEnd()

constructionLineSetEnd(ref, end): void

Sets the end point of a construction line, making it finite at the end. Pass null to make the line infinite (extending infinitely in the end direction).

Parameters

Parameter	Type	Description
ref	ConstructionLine | ConstructionLineRef	the construction line or reference
end	Vector3d | Point3d | null	the end point, or null for infinite

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create a simple line
let lineRef = await model.performOperation(op => {
  const ref = op.createConstructionLine(
    op.model,
    new SketchUpApi.Point3d(150, 0, 0),
    new SketchUpApi.Point3d(150, 100, 0)
  );
  return op.entityForRef(ref);
}, 'Create construction line');
// Second operation: move the end point
await model.performOperation(op => {
  op.constructionLineSetEnd(
    lineRef,
    new SketchUpApi.Point3d(150, 50, 0)
  );
}, 'Set construction line end');

Since

SDK 2.7.0 Protocol 1.5.0

---

constructionLineSetPosition()

constructionLineSetPosition(ref, position): void

Moves the construction line to pass through a new 3D point, while preserving its direction. Useful for sliding a guide line to a new position without changing its angle.

Parameters

Parameter	Type	Description
ref	ConstructionLine | ConstructionLineRef	the construction line or reference
position	Vector3d | Point3d	the new point the line should pass through

Returns

void

Since

SDK 2.7.0 Protocol 1.5.0

---

constructionLineSetStart()

constructionLineSetStart(ref, start): void

Sets the start point of a construction line, making it finite at the start. Pass null to make the line infinite (extending infinitely in the start direction).

Parameters

Parameter	Type	Description
ref	ConstructionLine | ConstructionLineRef	the construction line or reference
start	Vector3d | Point3d | null	the start point, or null for infinite

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create a simple line
let lineRef = await model.performOperation(op => {
  const ref = op.createConstructionLine(
    op.model,
    new SketchUpApi.Point3d(50, 0, 0),
    new SketchUpApi.Point3d(50, 100, 0)
  );
  return op.entityForRef(ref);
}, 'Create construction line');
// Second operation: move the start point
await model.performOperation(op => {
  op.constructionLineSetStart(
    lineRef,
    new SketchUpApi.Point3d(50, 50, 0)
  );
}, 'Set construction line start');

Since

SDK 2.7.0 Protocol 1.5.0

---

constructionLineSetStipple()

constructionLineSetStipple(ref, stipple): void

Set Construction Line stipple - the pattern used to display the Construction Line

Parameters

Parameter	Type	Description
ref	ConstructionLine | ConstructionLineRef	of Construction Line
stipple	string | number	string / number

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create a simple line
let lineRef = await model.performOperation(op => {
  const ref = op.createConstructionLine(
    op.model,
    new SketchUpApi.Point3d(450, 0, 0),
    new SketchUpApi.Point3d(450, 100, 0)
  );
  return op.entityForRef(ref);
}, 'Create construction line');
// Second operation: change the stipple pattern
await model.performOperation(op => {
  op.constructionLineSetStipple(lineRef, '.');
}, 'Set construction line stipple');

Since

SDK 2.7.0 Protocol 1.5.0

Valid strings are:

• ”.” (Dotted Line),
• ”-” (Short Dashes Line),
• ”_” (Long Dashes Line),
• ”-.-” (Dash Dot Dash Line).

---

createConstructionLine()

createConstructionLine(ref, start, end, stipple?): ConstructionLineRef

Creates a construction line, which is guide geometry that helps with snapping and alignment but doesn’t appear in rendered output. You can create a finite line segment (by passing two points) or an infinite ray (by passing a start point and a direction vector). The stipple parameter controls the line’s dash pattern.

Returns a ConstructionLineRef that’s valid only within this operation. To read the line’s properties or use it outside the operation callback, call entityForRef(constructionLineRef) before the operation ends.

Parameters

Parameter	Type	Default value	Description
ref	EntitiesContainer | EntitiesContainerRef	undefined	The container where the construction line will be created (model, group, or component instance).
start	Point3Like	undefined	The starting point of the line in 3D space (inches).
end	Vector3d | Point3Like	undefined	Either an end point (for a finite segment) or a direction vector (for an infinite ray).
stipple	string	'-'	The dash pattern, like ”-” for solid or ”.” for dotted. Defaults to ”-”.

Returns

ConstructionLineRef

A reference to the newly created construction line.

Example

let model = await SketchUpApi.getActiveModel();
let line = await model.performOperation(op => {
  const lineRef = op.createConstructionLine(
    op.model,
    new SketchUpApi.Point3d(0, 0, 0),
    new SketchUpApi.Point3d(100, 100, 0)
  );
  return op.entityForRef(lineRef);
}, 'Create construction line');
console.log(line);

See

• ConstructionLine for code examples
• entityForRef

Since

SDK 2.30.0 Protocol 1.5.0

ConstructionPoint

createConstructionPoint()

createConstructionPoint(ref, point): ConstructionPointRef

Creates a construction point at the given 3D location. Construction points are guide geometry — they don’t appear in rendered output but help with snapping and alignment during modeling. They’re often used to mark key locations like centers, intersections, or reference heights.

Returns a ConstructionPointRef that’s valid only within this operation. To read the point’s properties or use it outside the operation callback, call entityForRef(constructionPointRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the construction point will be created (model, group, or component instance).
point	Point3Like	The 3D position in inches.

Returns

ConstructionPointRef

A reference to the newly created construction point.

Example

let model = await SketchUpApi.getActiveModel();
let point = await model.performOperation(op => {
  const pointRef =
    op.createConstructionPoint(op.model, [50, 50, 50]);
  return op.entityForRef(pointRef);
}, 'Create construction point');
console.log(point);

See

• ConstructionPoint for code examples
• entityForRef

Since

SDK 2.30.0 Protocol 1.5.0

Curve

createCurve()

createCurve(container, points): CurveAndComponents

Creates a curve from an arbitrary list of points. Edges are drawn connecting consecutive points, and the resulting edge chain is grouped as a curve.

Because SketchUp intersects and deduplicates edges, multiple curves may result from a single call. This method returns a reference to the curve associated with the first edge. Use Model.findCurvesForEdges to find all curves produced by this instruction.

Parameters

Parameter	Type	Description
container	EntitiesContainer | EntitiesContainerRef	The container to create the curve on.
points	Point3Like[]	The points that define the curve’s path.

Returns

CurveAndComponents

A curve and any edges created.

Example

let model = await SketchUpApi.getActiveModel();
let curve = await model.performOperation(op => {
  const curveAndEdges = op.createCurve(op.model, [
    [0, 0, 0], [50, 25, 0],
    [100, 0, 0], [100, 50, 0]
  ]);
  return op.entityForRef(curveAndEdges.curve);
}, 'Create curve');
console.log(curve);

Since

SDK 2.30.0 Protocol 1.20.0

See

Curve for code examples

---

createCurveByWeldingEdges()

createCurveByWeldingEdges(edges): Promise<CurveRef[]>

Welds the given edges together into one or more curves. All edges must share the same parent container, otherwise SketchUp will throw an error.

Parameters

Parameter	Type	Description
edges	readonly (Edge | EdgeRef)[]	The edges to weld.

Returns

Promise<CurveRef[]>

The curve refs resulting from the weld.

Example

let model = await SketchUpApi.getActiveModel();
let curves = await model.performOperation(op => {
  const edgeRefs = op.createEdge(op.model, [
    [0, 50, 0], [25, 100, 0],
    [50, 75, 0], [50, 25, 0], [25, 0, 0]
  ]);
  return op.createCurveByWeldingEdges(
    edgeRefs
  );
}, 'Weld C-shaped edges');
console.log(curves);

See

Curve for code examples

Since

SDK 2.30.0 Protocol 1.20.0

---

curveMoveVertices()

curveMoveVertices(curve, newPoints): void

Moves the vertices of the curve to new positions. The number of points must exactly match the number of vertices in the curve, otherwise SketchUp will throw an error.

Parameters

Parameter	Type	Description
curve	ArcCurve | Curve | ArcCurveRef | CurveRef	the curve
newPoints	Point3Like[]	the new positions for each vertex

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let curve = await model.performOperation(op => {
  const curveAndEdges = op.createCurve(op.model, [
    [0, 0, 0], [50, 25, 0], [100, 0, 0]
  ]);
  op.curveMoveVertices(curveAndEdges.curve, [
    [0, 0, 0], [50, 50, 0], [100, 0, 0]
  ]);
  return op.entityForRef(curveAndEdges.curve);
}, 'Move curve vertices');
console.log(curve.vertices.map(v => v.y));
// => [0, 50, 0]

Since

SDK 2.23.0 Protocol 1.20.0

DimensionLinear

createDimensionLinear()

createDimensionLinear(container, start, end, offset): DimensionLinearRef

Creates a linear dimension that measures the distance between two points. The offset vector controls how far the dimension line is displaced from the measured geometry and must not be zero length.

Parameters

Parameter	Type	Description
container	EntitiesContainer | EntitiesContainerRef	the container to place the dimension in
start	DimensionPointRef	the first measurement point (vertex, edge midpoint, or free point)
end	DimensionPointRef	the second measurement point
offset	Vector3Like	non-zero vector displacing the dimension line from the geometry

Returns

DimensionLinearRef

A reference to the linear dimension

Example

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [100, 0, 0],
    [100, 100, 0],
    [50, 0, 0]
  );
  return op.entityForRef(dimRef);
}, 'Create dimension');
console.log(dim);

Dimension between a construction point and edge:

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const cpRef = op.createConstructionPoint(
    op.model, [200, 50, 0]
  );
  const edgeRefs = op.createEdge(op.model, [
    [0, 0, 0], [100, 0, 0]
  ]);
  const dimRef = op.createDimensionLinear(
    op.model,
    { entity: cpRef },
    {
      entity: edgeRefs[0],
      point: [50, 0, 0]
    },
    [0, 50, 0]
  );
  return op.entityForRef(dimRef);
}, 'Create dimension with edge');
console.log(dim);

Dimension with instance path:

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const edgeRefs = op.createEdge(op.model, [
    [0, 100, 0], [100, 100, 0]
  ]);
  const dimRef = op.createDimensionLinear(
    op.model,
    { point: [0, 200, 0] },
    {
      instancePath: [edgeRefs[0]],
      point: [100, 100, 0]
    },
    [0, 50, 0]
  );
  return op.entityForRef(dimRef);
}, 'Create dimension with instance path');
console.log(dim);

Since

SDK 2.30.0 Protocol 1.20.0

See

DimensionLinear for code examples

---

dimensionLinearSetAlignedTextPosition()

dimensionLinearSetAlignedTextPosition(dimension, textPosition): void

Sets the position of the text label relative to the dimension line when the dimension has aligned text enabled. Controls whether the text sits above, below, or on the line. Values come from DimensionAlignedTextPosition.

Parameters

Parameter	Type	Description
dimension	DimensionLinear | DimensionLinearRef	the dimension to modify
textPosition	DimensionAlignedTextPosition	the aligned text position

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [700, 0, 0],
    [700, 100, 0],
    [20, 0, 0]
  );
  op.dimensionSetHasAlignedText(dimRef, true);
  op.dimensionLinearSetAlignedTextPosition(
    dimRef,
    SketchUpApi.DimensionAlignedTextPosition.Outside
  );
  return op.entityForRef(dimRef);
}, 'Position aligned dimension text');
console.log(dim.alignedTextPosition);
// => 2

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionLinearSetEnd()

dimensionLinearSetEnd(dimension, point): void

Moves the end attachment point of a linear dimension to a new location. The dimension line will update to span from the start point to this new end point.

Parameters

Parameter	Type	Description
dimension	DimensionLinear | DimensionLinearRef	the dimension to modify
point	DimensionPointRef	the new end attachment point

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dimEntity = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [400, 0, 0],
    [400, 100, 0],
    [20, 0, 0]
  );
  return op.entityForRef(dimRef);
}, 'Create dimension');

let moved = await model.performOperation(op => {
  op.dimensionLinearSetEnd(
    dimEntity, [400, 150, 0]
  );
  return op.entityForRef(dimEntity);
}, 'Move dimension end');
console.log(moved.endPoint);
// => Point3d { x: 400, y: 150, z: 0 }

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionLinearSetOffset()

dimensionLinearSetOffset(dimension, offset): void

Sets the offset vector controlling how far the dimension line is displaced from the measured geometry. The vector points in the direction and distance to where the dimension text and line are drawn.

Parameters

Parameter	Type	Description
dimension	DimensionLinear | DimensionLinearRef	the dimension to modify
offset	Vector3Like	the offset vector from the geometry to the dimension line

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dimEntity = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [500, 0, 0],
    [500, 100, 0],
    [20, 0, 0]
  );
  return op.entityForRef(dimRef);
}, 'Create dimension');

let moved = await model.performOperation(op => {
  op.dimensionLinearSetOffset(
    dimEntity, [50, 0, 0]
  );
  return op.entityForRef(dimEntity);
}, 'Increase dimension offset');
console.log(moved.offsetVector);
// => Vector3d { x: 50, y: 0, z: 0 }

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionLinearSetStart()

dimensionLinearSetStart(dimension, point): void

Moves the start attachment point of a linear dimension to a new location. The dimension line will update to span from this new start point to the end point.

Parameters

Parameter	Type	Description
dimension	DimensionLinear | DimensionLinearRef	the dimension to modify
point	DimensionPointRef	the new start attachment point

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dimEntity = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [300, 0, 0],
    [300, 100, 0],
    [20, 0, 0]
  );
  return op.entityForRef(dimRef);
}, 'Create dimension');

let moved = await model.performOperation(op => {
  op.dimensionLinearSetStart(
    dimEntity, [300, 50, 0]
  );
  return op.entityForRef(dimEntity);
}, 'Move dimension start');
console.log(moved.startPoint);
// => Point3d { x: 300, y: 50, z: 0 }

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionLinearSetTextPosition()

dimensionLinearSetTextPosition(dimension, textPosition): void

Sets where the text label appears relative to the dimension line — for example, inside the extension lines, outside them, or centered. Values come from DimensionTextPosition.

Parameters

Parameter	Type	Description
dimension	DimensionLinear | DimensionLinearRef	the dimension to modify
textPosition	DimensionTextPosition	the text position relative to the dimension line

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [600, 0, 0],
    [600, 100, 0],
    [20, 0, 0]
  );
  op.dimensionLinearSetTextPosition(
    dimRef,
    SketchUpApi.DimensionTextPosition.OutsideStart
  );
  return op.entityForRef(dimRef);
}, 'Center dimension text');
console.log(dim.textPosition);
// => 1

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionSetArrowType()

dimensionSetArrowType(dimension, arrowType): void

Sets the arrowhead style used at both endpoints of a dimension. The type controls whether endpoints show filled arrows, open arrows, dots, slashes, or nothing. Values come from DimensionArrowType.

Parameters

Parameter	Type	Description
dimension	Dimension | DimensionRef	the dimension to modify
arrowType	DimensionArrowType	the new arrow type

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [100, 0, 0],
    [100, 100, 0],
    [20, 0, 0]
  );
  op.dimensionSetArrowType(
    dimRef,
    SketchUpApi.DimensionArrowType.Open
  );
  return op.entityForRef(dimRef);
}, 'Set dimension arrow type');
console.log(dim.arrowType);
// => 4

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionSetHasAlignedText()

dimensionSetHasAlignedText(dimension, hasAlignedText): void

Controls whether the dimension text label aligns with the measurement line (rotated to follow the line) or always stays horizontal regardless of the dimension’s orientation.

Parameters

Parameter	Type	Description
dimension	Dimension | DimensionRef	the dimension to modify
hasAlignedText	boolean	when true, text rotates to follow the dimension line

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [200, 0, 0],
    [200, 100, 0],
    [20, 0, 0]
  );
  op.dimensionSetHasAlignedText(dimRef, true);
  return op.entityForRef(dimRef);
}, 'Align dimension text');
console.log(dim.hasAlignedText);
// => true

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionSetText()

dimensionSetText(dimension, text): void

Overrides the auto-generated measurement text with a custom string. Pass an empty string to revert to the automatic value (the measured distance or radius).

Include ”<>” to add text generated from the measurement.

Parameters

Parameter	Type	Description
dimension	Dimension | DimensionRef	the dimension to modify
text	string	the custom label text, or empty string for auto

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [0, 0, 0],
    [0, 100, 0],
    [20, 0, 0]
  );
  op.dimensionSetText(dimRef, 'Wall span <>');
  return op.entityForRef(dimRef);
}, 'Set dimension text');
console.log(dim.text);
// => "Wall span"

Since

SDK 2.23.0 Protocol 1.20.0

DimensionRadial

createDimensionRadial()

createDimensionRadial(container, arcCurve, leaderBreakPoint): DimensionRadialRef

Creates a radial dimension that displays the radius (or diameter) of an arc or circle. The leader break point sets where the leader line bends on its way to the text label.

Parameters

Parameter	Type	Description
container	EntitiesContainer | EntitiesContainerRef	the container to place the dimension in
arcCurve	ArcCurve | ArcCurveRef	the arc or circle to measure
leaderBreakPoint	Point3Like	the 3D point where the leader line bends

Returns

DimensionRadialRef

A reference to the radial dimension

Example

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const circleAndEdges = op.createCircle(
    op.model, [0, 0, 0], [0, 0, 1], 50
  );
  const dimRef = op.createDimensionRadial(
    op.model,
    circleAndEdges.curve,
    [75, 75, 0]
  );
  return op.entityForRef(dimRef);
}, 'Create radial dimension');
console.log(dim);

Since

SDK 2.30.0 Protocol 1.20.0

See

DimensionRadial for code examples

---

dimensionRadialSetArcCurve()

dimensionRadialSetArcCurve(dimension, arcCurve): void

Changes which arc or circle a radial dimension is measuring. The dimension will update to display the radius (or diameter) of the new arc curve.

Parameters

Parameter	Type	Description
dimension	DimensionRadial | DimensionRadialRef	the dimension to modify
arcCurve	ArcCurve | ArcCurveRef	the arc or circle to measure

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let [dim, curve2] = await model.performOperation(async op => {
  const circle1 = op.createCircle(
    op.model, [800, 0, 0], [0, 0, 1], 30
  );
  const circle2 = op.createCircle(
    op.model, [800, 100, 0], [0, 0, 1], 60
  );
  const dimRef = op.createDimensionRadial(
    op.model, circle1.curve, [850, 0, 0]
  );
  return op.entitiesForRefs([dimRef, circle2.curve]);
}, 'Create circles and dimension');

let updated = await model.performOperation(op => {
  op.dimensionRadialSetArcCurve(dim, curve2);
  return op.entityForRef(dim);
}, 'Retarget radial dimension');
console.log(updated.text);
// => "R60.0"

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionRadialSetLeaderBreakPoint()

dimensionRadialSetLeaderBreakPoint(dimension, breakpoint): void

Sets the point where the radial dimension’s leader line bends. The leader runs from the arc to this breakpoint, then to the text label, creating the characteristic “elbow” in the line.

Parameters

Parameter	Type	Description
dimension	DimensionRadial | DimensionRadialRef	the dimension to modify
breakpoint	Point3Like	the 3D point where the leader line bends

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dimEntity = await model.performOperation(op => {
  const circle = op.createCircle(
    op.model, [900, 0, 0], [0, 0, 1], 40
  );
  const dimRef = op.createDimensionRadial(
    op.model, circle.curve, [950, 0, 0]
  );
  return op.entityForRef(dimRef);
}, 'Create radial dimension');

let moved = await model.performOperation(op => {
  op.dimensionRadialSetLeaderBreakPoint(
    dimEntity, [950, 50, 0]
  );
  return op.entityForRef(dimEntity);
}, 'Bend radial leader');
console.log(moved.leaderBreakPoint);
// => Point3d { x: 950, y: 50, z: 0 }

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionSetArrowType()

dimensionSetArrowType(dimension, arrowType): void

Sets the arrowhead style used at both endpoints of a dimension. The type controls whether endpoints show filled arrows, open arrows, dots, slashes, or nothing. Values come from DimensionArrowType.

Parameters

Parameter	Type	Description
dimension	Dimension | DimensionRef	the dimension to modify
arrowType	DimensionArrowType	the new arrow type

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [100, 0, 0],
    [100, 100, 0],
    [20, 0, 0]
  );
  op.dimensionSetArrowType(
    dimRef,
    SketchUpApi.DimensionArrowType.Open
  );
  return op.entityForRef(dimRef);
}, 'Set dimension arrow type');
console.log(dim.arrowType);
// => 4

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionSetHasAlignedText()

dimensionSetHasAlignedText(dimension, hasAlignedText): void

Controls whether the dimension text label aligns with the measurement line (rotated to follow the line) or always stays horizontal regardless of the dimension’s orientation.

Parameters

Parameter	Type	Description
dimension	Dimension | DimensionRef	the dimension to modify
hasAlignedText	boolean	when true, text rotates to follow the dimension line

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [200, 0, 0],
    [200, 100, 0],
    [20, 0, 0]
  );
  op.dimensionSetHasAlignedText(dimRef, true);
  return op.entityForRef(dimRef);
}, 'Align dimension text');
console.log(dim.hasAlignedText);
// => true

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionSetText()

dimensionSetText(dimension, text): void

Overrides the auto-generated measurement text with a custom string. Pass an empty string to revert to the automatic value (the measured distance or radius).

Include ”<>” to add text generated from the measurement.

Parameters

Parameter	Type	Description
dimension	Dimension | DimensionRef	the dimension to modify
text	string	the custom label text, or empty string for auto

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let dim = await model.performOperation(op => {
  const dimRef = op.createDimensionLinear(
    op.model,
    [0, 0, 0],
    [0, 100, 0],
    [20, 0, 0]
  );
  op.dimensionSetText(dimRef, 'Wall span <>');
  return op.entityForRef(dimRef);
}, 'Set dimension text');
console.log(dim.text);
// => "Wall span"

Since

SDK 2.23.0 Protocol 1.20.0

Drawing Element

drawingElementErase()

drawingElementErase(ref): void

Permanently removes a drawing element (face, edge, group, etc.) from the model. Connected edges may also be removed if they no longer bound any face.

Parameters

Parameter	Type	Description
ref	DrawingElement | DrawingElementRef	the drawing element or drawing element reference

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  op.drawingElementErase(faceRef);
}, 'Erase face');
console.log('Face erased');

---

drawingElementEraseWithForce()

drawingElementEraseWithForce(ref): void

Removes a drawing element even if it’s a locked group or component instance. Automatically unlocks the element before erasing it.

Parameters

Parameter	Type	Description
ref	DrawingElement | DrawingElementRef	the drawing element or drawing element reference

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.groupSetLocked(groupRef, true);
  op.drawingElementEraseWithForce(groupRef);
}, 'Erase locked group');
console.log('Locked group erased');

---

drawingElementsApplyTransformation()

drawingElementsApplyTransformation(refs, transform, options?): void

Moves, rotates, or scales one or more drawing elements (or vertices) by applying a transformation matrix. All elements receive the same transformation.

Parameters

Parameter	Type	Description
refs	Transformable | TransformableArray	the element(s) to transform
transform	TransformationLike	the transformation to apply
options?	{ parent?: EntitiesContainer | EntitiesContainerRef; }	the options
options.parent?	EntitiesContainer | EntitiesContainerRef	‐

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  const transform = SketchUpApi.Transformation
    .translation([50, 50, 0]);
  op.drawingElementsApplyTransformation(
    faceRef, transform
  );
}, 'Transform element');
console.log('Element transformed');

Since

SDK 2.14.0 Protocol 1.11.0

---

drawingElementsBulkTransformation()

drawingElementsBulkTransformation(refs, transforms): void

Moves, rotates, or scales multiple drawing elements in a single call. Each element is paired with its own transformation — the first ref gets the first transform, the second ref gets the second, and so on. Much more efficient than calling drawingElementsApplyTransformation repeatedly when you need different transforms for each element.

Parameters

Parameter	Type	Description
refs	Transformable | TransformableArray	the drawing elements or vertices to transform
transforms	TransformationLike[]	a transformation for each element (same length as refs)

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const face1 = op.createFace(op.model, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  const face2 = op.createFace(op.model, [
    [0, 100, 0], [50, 100, 0],
    [50, 150, 0], [0, 150, 0]
  ]);
  const transforms = [
    SketchUpApi.Transformation.translation([50, 0, 0]),
    SketchUpApi.Transformation.translation([0, 50, 0])
  ];
  op.drawingElementsBulkTransformation(
    [face1, face2], transforms
  );
}, 'Bulk transform');
console.log('Elements transformed');

Since

SDK 2.14.0 Protocol 1.11.0

---

drawingElementSetMaterial()

drawingElementSetMaterial(ref, materialRef): void

Paints a drawing element with a material. For faces, this sets the front material — use faceSetBackMaterial for the reverse side. For edges, groups, and component instances, this sets their overall material.

Parameters

Parameter	Type	Description
ref	DrawingElement | DrawingElementRef	the drawing element or drawing element reference
materialRef	Material | MaterialRef	the material to apply

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 1], [50, 0, 1],
    [50, 50, 1], [0, 50, 1]
  ]);
  const matRef = op.createMaterial('Brick');
  op.materialSetColor(
    matRef, new SketchUpApi.Color(180, 80, 40)
  );
  op.drawingElementSetMaterial(faceRef, matRef);
}, 'Set material');
console.log('Material applied');

See

Operation.faceSetBackMaterial to set face back material

---

drawingElementSetMaterialName()

drawingElementSetMaterialName(ref, materialName): void

Paints a drawing element with a material looked up by name. Convenient when you know the material’s name but don’t have a ref. For faces, this sets the front side — use faceSetBackMaterialName for the reverse.

Parameters

Parameter	Type	Description
ref	DrawingElement | DrawingElementRef	the drawing element or drawing element reference
materialName	string	The material’s name, like "Brick_Antique".

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 1], [50, 0, 1],
    [50, 50, 1], [0, 50, 1]
  ]);
  op.drawingElementSetMaterialName(
    faceRef, 'Brick_Antique'
  );
}, 'Set material by name');
console.log('Material applied');

See

Operation.faceSetBackMaterialName to set face back material

---

drawingElementSetProperties()

drawingElementSetProperties(ref, properties): void

Updates visibility, cast-shadows, receive-shadows, and other display properties on a drawing element in one call.

Parameters

Parameter	Type	Description
ref	DrawingElement | DrawingElementRef	the drawing element or drawing element reference
properties	DrawingElementPropertiesUpdate	the changes to apply to the properties

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  op.drawingElementSetProperties(faceRef, {
    hidden: true,
    castShadows: true
  });
}, 'Set element properties');
console.log('Properties updated');

---

drawingElementSetTag()

drawingElementSetTag(ref, tag): void

Assigns a tag (layer) to a drawing element. Tags control visibility — when a tag is hidden, all entities on that tag disappear from view.

Parameters

Parameter	Type	Description
ref	DrawingElement | DrawingElementRef	the drawing element or drawing element reference
tag	Tag | TagRef	the tag to assign

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  const tagRef = op.createTag('Floors');
  op.drawingElementSetTag(faceRef, tagRef);
}, 'Assign tag to face');
console.log('Tag assigned');

---

drawingElementSetTagName()

drawingElementSetTagName(ref, tagName): void

Assigns a tag to a drawing element by the tag’s name string. Convenient when you know the tag name but don’t have a TagRef.

Parameters

Parameter	Type	Description
ref	DrawingElement | DrawingElementRef	the drawing element or drawing element reference
tagName	string	the display name of the tag, like "Structure"

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  op.createTag('Floors');
  op.drawingElementSetTagName(faceRef, 'Floors');
}, 'Assign tag by name');
console.log('Tag assigned by name');

Edge

createEdge()

createEdge(ref, vertices): readonly EdgeRef[]

Creates one or more edges connecting the given vertices. Consecutive vertices are connected by edges — for example, four vertices create three edges. SketchUp will automatically intersect the new edges with existing geometry, potentially splitting faces or other edges where they cross.

For creating large amounts of geometry efficiently, use createBuilder instead — it avoids repeated intersection passes and is much faster for bulk operations.

Returns EdgeRef handles that are valid only within this operation. To read an edge’s properties or use it outside the operation callback, call entityForRef(edgeRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the edges will be created (model, group, or component instance).
vertices	readonly Point3Like[]	The points to connect with edges, in order. Three vertices create two edges (A-B and B-C).

Returns

readonly EdgeRef[]

References to the newly created edges, in the same order as the vertex segments.

Example

let model = await SketchUpApi.getActiveModel();
let edges = await model.performOperation(op => {
  const edgeRefs = op.createEdge(op.model, [
    [0, 0, 0], [100, 0, 0],
    [100, 100, 0]
  ]);
  return op.entitiesForRefs(edgeRefs);
}, 'Create edges');
console.log(edges);

See

• Edge for code examples
• createBuilder
• entityForRef

Since

SDK 2.30.0

---

edgeSetProperties()

edgeSetProperties(ref, edgeProperties): void

Updates display properties on an edge — soft, smooth, hidden, and color. Soft edges don’t show a visible crease; smooth edges interpolate normals across connected faces for a curved look.

Parameters

Parameter	Type	Description
ref	Edge | EdgeRef	the edge or edge reference
edgeProperties	EdgePropertiesUpdate	the property changes to apply

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let sharedEdge =
  await model.performOperation(op => {
  op.createFace(op.model, [
    [0, 0, 0], [50, 0, 10],
    [50, 100, 10], [0, 100, 0]
  ]);
  op.createFace(op.model, [
    [50, 0, 10], [100, 0, 0],
    [100, 100, 0], [50, 100, 10]
  ]);
  return op.entityForRef(
    op.createEdge(op.model, [
      [50, 0, 10], [50, 100, 10]
    ])[0]
  );
}, 'Create shared edge');
await model.performOperation(op => {
  op.edgeSetProperties(sharedEdge, {
    soft: true,
    smooth: true
  });
}, 'Soften edge');
console.log('Edge softened - notice smooth shading');

---

entitiesSetEdgeProperties()

entitiesSetEdgeProperties(ref, edgeUsageType, edgeProperties): void

Applies edge property changes to all edges in a container that match a given usage type. For example, you can soften all curve edges, or hide all profile edges, in one call. Much more efficient than modifying each edge individually.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	the entity container or container reference
edgeUsageType	EdgeUsageType | "Any" | "Shared" | "UniqueToFace" | "UniqueOrUnboundToFace" | "UnboundToFace"	the edge usage type to target (e.g. ‘Shared’)
edgeProperties	EdgePropertiesUpdate	the property changes to apply

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let group = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  op.createFace(groupRef, [
    [50, 0, 0], [100, 0, 0],
    [100, 50, 0], [50, 50, 0]
  ]);
  op.entitiesSetEdgeProperties(
    groupRef,
    SketchUpApi.EdgeUsageType.Shared,
    { smooth: true, hidden: true }
  );
  return op.entityForRef(groupRef);
}, 'Smooth shared mesh edges');
let edges = await group.entities.get({
  filterBy: { types: ['Edge'] }
});
let smoothEdges = edges.filter(e => e.smooth);
console.log(smoothEdges.length);
// => 1

Entity

entitiesForRefs()

entitiesForRefs<E>(refs): Promise<EntityFor<E>[]>

Resolves an array of entity references to full entity objects. Use this inside an operation to read back the properties of entities you created in the same operation, since refs only carry an identifier. Results are returned in the same order as the input refs.

Type Parameters

Type Parameter
E extends EntityRef

Parameters

Parameter	Type	Description
refs	readonly E[]	the entity references to resolve

Returns

Promise<EntityFor<E>[]>

the full entity objects in the same order as refs

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  const faceRef1 =
   op.createFace(op.model, [[0,0,0],[100,0,0],[100,100,0],[0,100,0]]);
  const faceRef2 =
   op.createFace(op.model, [[0,0,100],[100,0,100],[100,100,100],[0,100,100]]);
  return op.entitiesForRefs([faceRef1, faceRef2]);
}, 'Create faces');
console.log(face.vertices);

---

entityDeleteAttribute()

entityDeleteAttribute(ref, path, key): void

Removes a single attribute key from an entity’s attribute dictionary. The path identifies which dictionary contains the key. Must not be empty.

Parameters

Parameter	Type	Description
ref	Entity | EntityRef	the entity or entity reference
path	string | readonly string[]	the dictionary path (e.g. 'MyExtension' or ['MyExtension', 'Settings'])
key	string	the attribute key to delete

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let edge = await model.performOperation((op) => {
 let [ref] = op.createEdge(op.model,
   [[0, 0, 0], [10, 0, 0]]);
 op.entitySetAttribute(ref, 'MyPlugin',
   'type', 'beam');
 op.entitySetAttribute(ref, 'MyPlugin',
   'color', 'red');
 return op.entityForRef(ref);
}, 'Add attributes');
await model.performOperation((op) => {
 op.entityDeleteAttribute(edge, 'MyPlugin',
   'type');
}, 'Remove type attribute');
edge = await edge.refresh();
console.log(edge.attributes.hasValue(
  'MyPlugin', 'type'));

---

entityDeleteAttributes()

entityDeleteAttributes(ref, path): void

Removes an entire attribute dictionary (and all its keys) from the entity. The path identifies which dictionary to delete. Must not be empty.

Parameters

Parameter	Type	Description
ref	Entity | EntityRef	the entity or entity reference
path	string | readonly string[]	the dictionary path (e.g. 'MyExtension' or ['MyExtension', 'Settings'])

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let edge = await model.performOperation((op) => {
 let [ref] = op.createEdge(op.model,
   [[0, 0, 0], [10, 0, 0]]);
 op.entitySetAttribute(ref, 'MyPlugin',
   'type', 'beam');
 op.entitySetAttribute(ref, 'MyPlugin',
   'color', 'red');
 return op.entityForRef(ref);
}, 'Add attributes');
await model.performOperation((op) => {
 op.entityDeleteAttributes(edge, 'MyPlugin');
}, 'Remove all attributes');
edge = await edge.refresh();
console.log(edge.attributes.hasValue(
  'MyPlugin', 'type'));

---

entityForRef()

entityForRef<E>(ref): Promise<EntityFor<E>>

Fetches the full entity snapshot for an operation ref. Use this to read properties (geometry, name, material) of something you created or modified earlier in the operation. The ref must still exist in SketchUp — throws if it was deleted.

Type Parameters

Type Parameter
E extends EntityRef

Parameters

Parameter	Type	Description
ref	E	the entity reference

Returns

Promise<EntityFor<E>>

a promise containing the entity

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  const faceRef =
   op.createFace(op.model, [[0,0,0],[100,0,0],[100,100,0],[0,100,0]]);
  return op.entityForRef(faceRef);
}, 'Create Face');
console.log(face.vertices);

---

entitySetAttribute()

entitySetAttribute(ref, path, key, value): void

Stores a custom key/value pair in one of the entity’s attribute dictionaries. Attributes are persistent metadata that survive save/load cycles.

Parameters

Parameter	Type	Description
ref	Entity | EntityRef	the entity or entity reference
path	string | readonly string[]	Dictionary path (must not be empty), like 'MyPlugin' or ['MyPlugin', 'Settings'].
key	string	the attribute key
value	AttributeValue	the value to set

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let edge = await model.performOperation((op) => {
 let [ref] = op.createEdge(op.model,
   [[0, 0, 0], [10, 0, 0]]);
 op.entitySetAttribute(ref, 'MyPlugin',
   'type', 'beam');
 return op.entityForRef(ref);
}, 'Add edge attribute');
console.log(edge.attributes.getValue(
  'MyPlugin', 'type'));

Entity Container

createBuilder()

createBuilder<A>(func): EntityBuilderCall<A, A>

Creates a builder for efficiently constructing large amounts of geometry. The builder batches face, edge, and curve creation calls and applies SketchUp’s intersection logic once at the end, which is much faster than creating geometry piecemeal with createFace or createEdge.

The callback receives an EntitiesBuilder instance with methods like faceCreate, edgeCreate, and arcCreate. Once you’ve queued all the geometry, call .build(container) on the returned object to commit it to the model.

The builder’s create methods return refs to the created geometry, which you can use to set materials, apply transformations, or read back properties after calling build().

Type Parameters

Type Parameter
A

Parameters

Parameter	Type	Description
func	(entityBuilder) => A | Promise<A>	A callback that uses the builder’s methods to define geometry. Can be synchronous or async.

Returns

EntityBuilderCall<A, A>

An object with a build(container) method. Call it to insert the geometry into the model, group, or component instance.

See

EntitiesBuilder for code examples

---

createConstructionLine()

createConstructionLine(ref, start, end, stipple?): ConstructionLineRef

Creates a construction line, which is guide geometry that helps with snapping and alignment but doesn’t appear in rendered output. You can create a finite line segment (by passing two points) or an infinite ray (by passing a start point and a direction vector). The stipple parameter controls the line’s dash pattern.

Returns a ConstructionLineRef that’s valid only within this operation. To read the line’s properties or use it outside the operation callback, call entityForRef(constructionLineRef) before the operation ends.

Parameters

Parameter	Type	Default value	Description
ref	EntitiesContainer | EntitiesContainerRef	undefined	The container where the construction line will be created (model, group, or component instance).
start	Point3Like	undefined	The starting point of the line in 3D space (inches).
end	Vector3d | Point3Like	undefined	Either an end point (for a finite segment) or a direction vector (for an infinite ray).
stipple	string	'-'	The dash pattern, like ”-” for solid or ”.” for dotted. Defaults to ”-”.

Returns

ConstructionLineRef

A reference to the newly created construction line.

Example

let model = await SketchUpApi.getActiveModel();
let line = await model.performOperation(op => {
  const lineRef = op.createConstructionLine(
    op.model,
    new SketchUpApi.Point3d(0, 0, 0),
    new SketchUpApi.Point3d(100, 100, 0)
  );
  return op.entityForRef(lineRef);
}, 'Create construction line');
console.log(line);

See

• ConstructionLine for code examples
• entityForRef

Since

SDK 2.30.0 Protocol 1.5.0

---

createConstructionPoint()

createConstructionPoint(ref, point): ConstructionPointRef

Creates a construction point at the given 3D location. Construction points are guide geometry — they don’t appear in rendered output but help with snapping and alignment during modeling. They’re often used to mark key locations like centers, intersections, or reference heights.

Returns a ConstructionPointRef that’s valid only within this operation. To read the point’s properties or use it outside the operation callback, call entityForRef(constructionPointRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the construction point will be created (model, group, or component instance).
point	Point3Like	The 3D position in inches.

Returns

ConstructionPointRef

A reference to the newly created construction point.

Example

let model = await SketchUpApi.getActiveModel();
let point = await model.performOperation(op => {
  const pointRef =
    op.createConstructionPoint(op.model, [50, 50, 50]);
  return op.entityForRef(pointRef);
}, 'Create construction point');
console.log(point);

See

• ConstructionPoint for code examples
• entityForRef

Since

SDK 2.30.0 Protocol 1.5.0

---

createDefinition()

createDefinition(name): ComponentDefinitionRef

Creates a new component definition with the given name. If the name already exists, SketchUp appends a randomized suffix to make it unique.

The returned ref is only valid within this operation. To access the definition after the operation ends, convert it with entityForRef(defRef).

Parameters

Parameter	Type	Description
name	string	the name of the component

Returns

ComponentDefinitionRef

reference to the created component definition

Example

let model = await SketchUpApi.getActiveModel();
let def = await model.performOperation(op => {
  const defRef = op.createDefinition('MyComponent');
  op.createFace(defRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  return op.entityForRef(defRef);
}, 'Create definition');
console.log(def);

See

ComponentDefinition for code examples

Since

SDK 2.30.0

---

createEdge()

createEdge(ref, vertices): readonly EdgeRef[]

Creates one or more edges connecting the given vertices. Consecutive vertices are connected by edges — for example, four vertices create three edges. SketchUp will automatically intersect the new edges with existing geometry, potentially splitting faces or other edges where they cross.

For creating large amounts of geometry efficiently, use createBuilder instead — it avoids repeated intersection passes and is much faster for bulk operations.

Returns EdgeRef handles that are valid only within this operation. To read an edge’s properties or use it outside the operation callback, call entityForRef(edgeRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the edges will be created (model, group, or component instance).
vertices	readonly Point3Like[]	The points to connect with edges, in order. Three vertices create two edges (A-B and B-C).

Returns

readonly EdgeRef[]

References to the newly created edges, in the same order as the vertex segments.

Example

let model = await SketchUpApi.getActiveModel();
let edges = await model.performOperation(op => {
  const edgeRefs = op.createEdge(op.model, [
    [0, 0, 0], [100, 0, 0],
    [100, 100, 0]
  ]);
  return op.entitiesForRefs(edgeRefs);
}, 'Create edges');
console.log(edges);

See

• Edge for code examples
• createBuilder
• entityForRef

Since

SDK 2.30.0

---

createFace()

createFace(ref, vertices): FaceRef

Creates a face from an array of 3D points forming a closed loop. The vertices must be coplanar and define a non-degenerate polygon. SketchUp will automatically intersect the new face with existing geometry and may split edges or faces where they overlap.

For creating large amounts of geometry efficiently, use createBuilder instead — it bypasses intersection while building and only applies it once at the end.

Returns a FaceRef that’s valid only within this operation. To read the face’s properties or use it outside the operation callback, call entityForRef(faceRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the face will be created (model, group, or component instance).
vertices	readonly Point3Like[]	The corner points of the face in 3D space (inches), in order. The last vertex automatically connects back to the first.

Returns

FaceRef

A reference to the newly created face.

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0],
    [100, 100, 0], [0, 100, 0]
  ]);
  return op.entityForRef(faceRef);
}, 'Create rectangle face');
console.log(face);

See

• Face for code examples
• createBuilder
• entityForRef

Since

SDK 2.30.0

---

createGroup()

createGroup(ref): GroupRef

Creates an empty group in the specified container. Groups organize geometry into named, movable clusters — like component instances, but unique (not reusable across the model). After creating a group, you can add faces, edges, or nested groups to it by passing the returned GroupRef as the container to other create methods.

Returns a GroupRef that’s valid only within this operation. To read the group’s properties or use it outside the operation callback, call entityForRef(groupRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the group will be created (model, another group, or a component instance).

Returns

GroupRef

A reference to the newly created empty group.

Example

let model = await SketchUpApi.getActiveModel();
let group = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.groupSetName(groupRef, 'MyGroup');
  const faceRef = op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  return op.entityForRef(groupRef);
}, 'Create group with face');
console.log(group);

See

• Group for code examples
• entityForRef

Since

SDK 2.30.0

---

createImage()

Places an image into the model as a 2D entity. Images are flat rectangles that display a raster graphic — useful for reference photos, logos, or textures that aren’t applied to geometry. You can provide the image data as a data URL, an HTML image element, a Blob, or a fetch request.

The image is positioned by its lower-left corner (origin) and scaled to the given width and height (in inches). It initially faces the user along the model’s axes — you can rotate it afterward with transformation methods.

When options include a fetch or blob resource, this method returns a Promise that resolves once the image data is loaded. Data URLs and HTML elements load synchronously and return an ImageEntityRef directly.

Example

let model = await SketchUpApi.getActiveModel();
let img = await model.performOperation(async op => {
  const imgRef = await op.createImage(op.model, {
    resource: { request: 'https://cdn.habitat.sketchup.com/examples/images/ColorWheel.jpg' },
    origin: [0, 0, 0],
    width: 100,
    height: 100
  });
  return op.entityForRef(imgRef);
}, 'Create image');
console.log(img);

See

ImageEntity for code examples

Since

SDK 2.30.0 Protocol 1.18.0

Param

container

The container where the image will be placed (model, group, or component instance).

Param

options

Configuration including the image source (resource), position (origin), and dimensions (width and height in inches).

Call Signature

createImage(container, options): ImageEntityRef

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
options	ImageLoadDataUrl | ImageLoadHtmlElement

Returns

ImageEntityRef

Call Signature

createImage(container, options): Promise<ImageEntityRef>

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
options	ImageLoadFetch | ImageLoadBlob

Returns

Promise<ImageEntityRef>

Call Signature

createImage(container, options): ImageEntityRef | Promise<ImageEntityRef>

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
options	ImageLoadOptions

Returns

ImageEntityRef | Promise<ImageEntityRef>

---

createInstance()

createInstance(ref, componentRef, transform?): ComponentInstanceRef

Places an instance of a component definition into the model. Component instances are reusable copies of a shared definition — editing the definition updates all instances. The optional transformation positions, rotates, and scales the instance relative to its parent container’s axes.

Returns a ComponentInstanceRef that’s valid only within this operation. To read the instance’s properties or use it outside the operation callback, call entityForRef(instanceRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the instance will be placed (model, group, or another component instance).
componentRef	ComponentDefinition | ComponentDefinitionRef	The component definition to instantiate.
transform?	TransformationLike	Optional transformation to apply to the instance. Defaults to identity (origin with no rotation or scaling).

Returns

ComponentInstanceRef

A reference to the newly created component instance.

Example

let model = await SketchUpApi.getActiveModel();
let defs = await model.getDefinitions();
if (defs.length === 0) {
  console.log('there are no definitions');
} else {
  let instance =
    await model.performOperation(op => {
    const instanceRef = op.createInstance(
      op.model, defs[0]
    );
    return op.entityForRef(instanceRef);
  }, 'Create instance');
  console.log(instance);
}

See

• ComponentInstance for code examples
• entityForRef

Since

SDK 2.30.0

---

createSectionPlane()

createSectionPlane(ref, planeCoefficients): SectionPlaneRef

Creates a section plane in the container. The plane cuts through the model, revealing cross-sectional geometry. Activate it with sectionPlaneActivate to make the cut visible.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	the container or container ref
planeCoefficients	PlaneLike	the cutting plane as [a, b, c, d] coefficients

Returns

SectionPlaneRef

a reference to the created section plane

Example

let model = await SketchUpApi.getActiveModel();
await model.updateRenderingOptions(
  { DisplaySectionPlanes: true }
);
let sectionPlane =
  await model.performOperation(op => {
  const spRef = op.createSectionPlane(
    op.model, [0, 0, 1, -50]
  );
  return op.entityForRef(spRef);
}, 'Create section plane');
console.log(sectionPlane);

Since

SDK 2.30.0 Protocol 1.13.0

See

SectionPlane for code examples

---

createSnap()

createSnap(ref, position, direction, up?): SnapRef

Creates a snap point in the container. Snap points define attachment locations for component instances (like connection points for furniture or fixtures).

The returned SnapRef is only valid within this operation. To access it after the operation ends, convert it with entityForRef(snapRef).

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	the container or container ref
position	Point3Like	the position of the snap point
direction	Vector3Like	the direction vector of the snap point
up?	Vector3Like	optional up vector (if omitted, SketchUp determines orientation automatically)

Returns

SnapRef

a reference to the created snap point

Example

let model = await SketchUpApi.getActiveModel();
let snap = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  const snapRef = op.createSnap(
    groupRef, [25, 25, 0], [0, 0, 1]
  );
  return op.entityForRef(snapRef);
}, 'Create snap on group');
console.log(snap);

See

• Snap for code examples
• entityForRef

Since

SDK 2.30.0 Protocol 1.17.0

---

createText()

createText(ref, text, attachment, vector?): TextRef

Creates a text annotation in the model. Text entities can be screen-facing labels (2D) or leader-line callouts pointing at specific geometry (3D). The attachment point determines where the text’s arrow touches the model, and can optionally reference a nested component instance path so the text follows that geometry when it moves.

If you omit the leader vector, SketchUp creates a 2D screen-space text that always faces the camera. Providing a vector creates a 3D text with a leader line extending from the attachment point in the vector’s direction.

Returns a TextRef that’s valid only within this operation. To read the text’s properties or use it outside the operation callback, call entityForRef(textRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the text will be created (model, group, or component instance).
text	string	The text string to display.
attachment	TextAttachment	Either a 3D point, or an object with point and instancePath (array of entities forming a path to nested geometry).
vector?	Vector3Like	Optional leader direction. Omit to create a 2D screen text.

Returns

TextRef

A reference to the newly created text entity.

Examples

Create a standalone text entity.

let model = await SketchUpApi.getActiveModel();
let text = await model.performOperation(op => {
  const textRef = op.createText(
    op.model, 'Hello World',
    { point: [0, 0, 100] },
    [0, 0, 50]
  );
  return op.entityForRef(textRef);
}, 'Create text');
console.log(text);

Create text attached to a vertical edge.

let model = await SketchUpApi.getActiveModel();
let edgeText =
  await model.performOperation(op => {
  const edgeRefs = op.createEdge(op.model, [
    [50, 50, 0], [50, 50, 100]
  ]);
  const textRef = op.createText(
    op.model, 'Edge Label',
    { point: [50, 50, 50] },
    [50, 0, 0]
  );
  return op.entityForRef(textRef);
}, 'Create edge text');
console.log(edgeText);

See

• Text for code examples
• entityForRef

Since

SDK 2.30.0 Protocol 1.19.0

---

entitiesApplyTransformation()

entitiesApplyTransformation(ref, transformation, options?): void

Applies a transformation (move, rotate, or scale) to every entity inside a container in one instruction. You can optionally filter which entity types are affected. This is much more efficient than transforming entities one by one.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	the entity container or container reference
transformation	TransformationLike	the transformation to apply to all entities
options?	EntityQuery<EntityFilter> | SketchupEntityFilter	optional filter to limit which entity types are transformed

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let point = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  const pointRef = op.createConstructionPoint(
    groupRef, [0, 0, 0]
  );
  op.createEdge(groupRef, [
    [0, 0, 0], [50, 0, 0]
  ]);
  op.entitiesApplyTransformation(
    groupRef,
    SketchUpApi.Transformation.translation(
      [0, 0, 25]
    ),
    { filterBy: { types: ['ConstructionPoint'] } }
  );
  return op.entityForRef(pointRef);
}, 'Move points in group');
console.log(point.position.toArray());
// => [0, 0, 25]

Since

SDK 1.9.0 Protocol 0.8.0

---

entitiesClear()

entitiesClear(ref): void

Removes all geometry and child entities from a container, leaving it empty. Use this to wipe a group or component’s contents before rebuilding them.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	the entity container or container reference

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let groupEntity = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  return op.entityForRef(groupRef);
}, 'Create group with face');

let group = await model.performOperation(op => {
  op.entitiesClear(groupEntity);
  return op.entityForRef(groupEntity);
}, 'Clear group contents');
// undefined
console.log(await model.findEntity(group));

---

entitiesSetActivateSectionPlane()

entitiesSetActivateSectionPlane(ref, sectionPlaneRef?): void

Activates a specific section plane in a container, or clears the active section plane. The active plane’s cut is applied to the view; only one plane can be active per container. Pass undefined or null to deactivate all section planes in the container.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	the entities container or reference
sectionPlaneRef?	SectionPlaneRef | null	the section plane to activate, or undefined/null to clear

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.updateRenderingOptions(
  { DisplaySectionPlanes: true }
);
let plane = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  const spRef = op.createSectionPlane(
    groupRef, [0, 0, 1, -25]
  );
  op.entitiesSetActivateSectionPlane(
    groupRef, spRef
  );
  return op.entityForRef(spRef);
}, 'Activate section plane in group');
console.log(plane.active);
// => true

Since

SDK 2.16.0 Protocol 1.13.0

---

entitiesSetEdgeProperties()

entitiesSetEdgeProperties(ref, edgeUsageType, edgeProperties): void

Applies edge property changes to all edges in a container that match a given usage type. For example, you can soften all curve edges, or hide all profile edges, in one call. Much more efficient than modifying each edge individually.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	the entity container or container reference
edgeUsageType	EdgeUsageType | "Any" | "Shared" | "UniqueToFace" | "UniqueOrUnboundToFace" | "UnboundToFace"	the edge usage type to target (e.g. ‘Shared’)
edgeProperties	EdgePropertiesUpdate	the property changes to apply

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let group = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  op.createFace(groupRef, [
    [50, 0, 0], [100, 0, 0],
    [100, 50, 0], [50, 50, 0]
  ]);
  op.entitiesSetEdgeProperties(
    groupRef,
    SketchUpApi.EdgeUsageType.Shared,
    { smooth: true, hidden: true }
  );
  return op.entityForRef(groupRef);
}, 'Smooth shared mesh edges');
let edges = await group.entities.get({
  filterBy: { types: ['Edge'] }
});
let smoothEdges = edges.filter(e => e.smooth);
console.log(smoothEdges.length);
// => 1

Face

createFace()

createFace(ref, vertices): FaceRef

Creates a face from an array of 3D points forming a closed loop. The vertices must be coplanar and define a non-degenerate polygon. SketchUp will automatically intersect the new face with existing geometry and may split edges or faces where they overlap.

For creating large amounts of geometry efficiently, use createBuilder instead — it bypasses intersection while building and only applies it once at the end.

Returns a FaceRef that’s valid only within this operation. To read the face’s properties or use it outside the operation callback, call entityForRef(faceRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the face will be created (model, group, or component instance).
vertices	readonly Point3Like[]	The corner points of the face in 3D space (inches), in order. The last vertex automatically connects back to the first.

Returns

FaceRef

A reference to the newly created face.

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0],
    [100, 100, 0], [0, 100, 0]
  ]);
  return op.entityForRef(faceRef);
}, 'Create rectangle face');
console.log(face);

See

• Face for code examples
• createBuilder
• entityForRef

Since

SDK 2.30.0

---

createFaceFromEdges()

createFaceFromEdges(ref, edges): FaceRef

Creates a face bounded by the given edges. The edges must form a closed loop. SketchUp will apply face and edge intersection, so use EntitiesBuilder instead for large amounts of geometry.

The returned FaceRef is only valid within this operation. To access the face after the operation ends, convert it with entityForRef(faceRef).

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	the container or container ref
edges	readonly (Edge | EdgeRef)[]	the edges to use to create the face

Returns

FaceRef

a reference to the created face

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  const edge1 = op.createEdge(op.model,
    [[0, 0, 0], [100, 0, 0]])[0];
  const edge2 = op.createEdge(op.model,
    [[100, 0, 0], [100, 100, 0]])[0];
  const edge3 = op.createEdge(op.model,
    [[100, 100, 0], [0, 100, 0]])[0];
  const edge4 = op.createEdge(op.model,
    [[0, 100, 0], [0, 0, 0]])[0];
  const faceRef = op.createFaceFromEdges(
    op.model, [edge1, edge2, edge3, edge4]
  );
  return op.entityForRef(faceRef);
}, 'Create face from edges');
console.log(face);

See

• Face for code examples
• createBuilder
• entityForRef

Since

SDK 2.30.0 Protocol 1.22.0

---

faceClearBackTexturePosition()

faceClearBackTexturePosition(face): void

Removes the back-side UV texture positioning from a face, reverting to the material’s default tiling. Use this to undo custom UV pin placement on the back of a face.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face to clear positioning from

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create face and position texture
let face = await model.performOperation(async op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  const canvas = document.createElement('canvas');
  canvas.width = 200;
  canvas.height = 200;
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = 'black';
  ctx.fillRect(0, 0, 200, 200);
  ctx.fillStyle = 'yellow';
  ctx.beginPath();
  ctx.arc(150, 150, 30, 0, Math.PI * 2);
  ctx.fill();
  const texMat = op.createMaterial(
    'TexturedBack'
  );
  const b64 = canvas.toDataURL().split(',')[1];
  await op.materialSetTextureDataBase64(
    texMat, b64, 100, 100
  );
  op.facePositionBackMaterial(faceRef,
    texMat, [
      [0, 0, 0], [0, 0, 0],
      [100, 0, 0], [1, 0, 0],
      [100, 0, 50], [1, 1, 0],
      [0, 0, 50], [0, 1, 0]
    ]
  );
  return op.entityForRef(faceRef);
}, 'Create positioned texture');
// Second operation: clear the positioning
await model.performOperation(async op => {
  op.faceClearBackTexturePosition(face);
}, 'Clear back texture position');

Since

SDK 2.25.0 Protocol 1.22.0

---

faceClearBackTextureProjection()

faceClearBackTextureProjection(face): void

Resets the back-side texture projection of a face, reverting to the material’s default projection. Use this to remove any custom projection that was applied to the back side.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face to clear projection from

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create face and apply texture
let face = await model.performOperation(async op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  const canvas = document.createElement('canvas');
  canvas.width = 200;
  canvas.height = 200;
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = 'black';
  ctx.fillRect(0, 0, 200, 200);
  ctx.fillStyle = 'blue';
  ctx.beginPath();
  ctx.arc(50, 150, 30, 0, Math.PI * 2);
  ctx.fill();
  const texMat = op.createMaterial(
    'TexturedBack'
  );
  const b64 = canvas.toDataURL().split(',')[1];
  await op.materialSetTextureDataBase64(
    texMat, b64, 100, 100
  );
  op.facePositionBackMaterial(faceRef,
    texMat, [
      [0, 0, 0], [0, 0, 0],
      [100, 0, 0], [1, 0, 0],
      [100, 0, 50], [1, 1, 0],
      [0, 0, 50], [0, 1, 0]
    ],
    [1, -1, 0] // skew the texture
  );
  return op.entityForRef(faceRef);
}, 'Create textured face');
// Second operation: clear the projection
await model.performOperation(async op => {
  op.faceClearBackTextureProjection(face);
}, 'Clear back texture projection');

Since

SDK 2.25.0 Protocol 1.22.0

---

faceClearFrontTexturePosition()

faceClearFrontTexturePosition(face): void

Removes the front-side UV texture positioning from a face, reverting to the material’s default tiling. Use this to undo custom UV pin placement.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face to clear positioning from

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create face and position texture
let face = await model.performOperation(async op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  const canvas = document.createElement('canvas');
  canvas.width = 200;
  canvas.height = 200;
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = 'black';
  ctx.fillRect(0, 0, 200, 200);
  ctx.fillStyle = 'green';
  ctx.beginPath();
  ctx.arc(150, 50, 30, 0, Math.PI * 2);
  ctx.fill();
  const texMat = op.createMaterial(
    'TexturedFront'
  );
  const b64 = canvas.toDataURL().split(',')[1];
  await op.materialSetTextureDataBase64(
    texMat, b64, 100, 100
  );
  op.facePositionFrontMaterial(faceRef,
    texMat, [
      [0, 0, 0], [0, 0, 0],
      [100, 0, 0], [1, 0, 0],
      [100, 0, 50], [1, 1, 0],
      [0, 0, 50], [0, 1, 0]
    ]
  );
  return op.entityForRef(faceRef);
}, 'Create positioned texture');
// Second operation: clear the positioning
await model.performOperation(async op => {
  op.faceClearFrontTexturePosition(face);
}, 'Clear front texture position');

Since

SDK 2.25.0 Protocol 1.22.0

---

faceClearFrontTextureProjection()

faceClearFrontTextureProjection(face): void

Removes the front-side texture projection from a face, resetting it to the default flat mapping. Use this when you want to undo a previously applied projection without replacing it.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face to clear projection from

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create face and apply texture
let face = await model.performOperation(async op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  const canvas = document.createElement('canvas');
  canvas.width = 200;
  canvas.height = 200;
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = 'black';
  ctx.fillRect(0, 0, 200, 200);
  ctx.fillStyle = 'red';
  ctx.beginPath();
  ctx.arc(50, 50, 30, 0, Math.PI * 2);
  ctx.fill();
  const texMat = op.createMaterial(
    'TexturedFront'
  );
  const b64 = canvas.toDataURL().split(',')[1];
  await op.materialSetTextureDataBase64(
    texMat, b64, 100, 100
  );
  op.facePositionFrontMaterial(faceRef,
    texMat, [
      [0, 0, 0], [0, 0, 0],
      [100, 0, 0], [1, 0, 0],
      [100, 0, 50], [1, 1, 0],
      [0, 0, 50], [0, 1, 0]
    ],
    [1, -1, 0] // skew the texture
  );
  return op.entityForRef(faceRef);
}, 'Create textured face');
// Second operation: clear the projection
await model.performOperation(async op => {
  op.faceClearFrontTextureProjection(face);
}, 'Clear front texture projection');

Since

SDK 2.25.0 Protocol 1.22.0

---

faceFollowMe()

faceFollowMe(face, edges): Promise<boolean>

Sweeps a face along a path of edges, creating a 3D shape (like piping or extrusion along a curve). This is SketchUp’s “Follow Me” tool. The face and path edges may be consumed (deleted) by the operation.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the profile face to sweep
edges	readonly (Edge | EdgeRef)[]	the path to sweep along

Returns

Promise<boolean>

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Create path: curved edges to sweep along
  const pathEdges = op.createEdge(
    op.model,
    [[0, 0, 0], [50, 50, 0],
     [100, 100, 0]]
  );
  // Sweep face along path
  await op.faceFollowMe(faceRef, pathEdges);
}, 'Apply follow me sweep');

Since

SDK 2.25.0 Protocol 1.22.0

---

facePositionBackMaterial()

facePositionBackMaterial(face, material, positions, projection): void

Controls how a textured material is mapped onto the back (reverse) side of a face. Works identically to facePositionFrontMaterial but targets the opposite side.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face or face reference
material	Material | MaterialRef	the textured material to position
positions	TexturePositioning	1–4 pairs of [model point, UV point]
projection	Vector3Like | undefined	an optional repeating direction vector

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Create canvas with 4 colored circles
  const canvas = document.createElement('canvas');
  canvas.width = 200;
  canvas.height = 200;
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = 'black';
  ctx.fillRect(0, 0, 200, 200);
  // Red top-left, green top-right,
  // blue bottom-left, yellow bottom-right
  ctx.fillStyle = 'red';
  ctx.beginPath();
  ctx.arc(50, 50, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'green';
  ctx.beginPath();
  ctx.arc(150, 50, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'blue';
  ctx.beginPath();
  ctx.arc(50, 150, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'yellow';
  ctx.beginPath();
  ctx.arc(150, 150, 30, 0, Math.PI * 2);
  ctx.fill();
  // Create textured material and position
  const texMat = op.createMaterial(
    'TexturedBack'
  );
  const b64 = canvas.toDataURL().split(',')[1];
  await op.materialSetTextureDataBase64(
    texMat, b64, 100, 100
  );
  op.facePositionBackMaterial(faceRef,
    texMat,
    [
      [0, 0, 0], [0, 0, 0],
      [100, 0, 0], [1, 0, 0],
      [100, 0, 50], [1, 1, 0],
      [0, 0, 50], [0, 1, 0]
    ]
  );
}, 'Position back texture');

---

facePositionFrontMaterial()

facePositionFrontMaterial(face, material, positions, projection?): void

Controls how a textured material is mapped onto the front of a face. You provide pairs of [3D point, UV coordinate] to pin texture corners to specific locations on the face. The material must have a texture — positioning a solid-color material throws.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face or face reference
material	Material | MaterialRef	the textured material to position
positions	TexturePositioning	1–4 pairs of [model point, UV point]
projection?	Vector3Like	an optional repeating direction vector

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Create canvas with 4 colored circles
  const canvas = document.createElement('canvas');
  canvas.width = 200;
  canvas.height = 200;
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = 'black';
  ctx.fillRect(0, 0, 200, 200);
  // Red top-left, green top-right,
  // blue bottom-left, yellow bottom-right
  ctx.fillStyle = 'red';
  ctx.beginPath();
  ctx.arc(50, 50, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'green';
  ctx.beginPath();
  ctx.arc(150, 50, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'blue';
  ctx.beginPath();
  ctx.arc(50, 150, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'yellow';
  ctx.beginPath();
  ctx.arc(150, 150, 30, 0, Math.PI * 2);
  ctx.fill();
  // Create textured material and position
  const texMat = op.createMaterial(
    'TexturedFront'
  );
  const b64 = canvas.toDataURL().split(',')[1];
  await op.materialSetTextureDataBase64(
    texMat, b64, 100, 100
  );
  op.facePositionFrontMaterial(faceRef,
    texMat,
    [
      [0, 0, 0], [0, 0, 0],
      [100, 0, 0], [1, 0, 0],
      [100, 0, 50], [1, 1, 0],
      [0, 0, 50], [0, 1, 0]
    ]
  );
}, 'Position front texture');

---

facePushPull()

facePushPull(face, distance, copy?): void

Extrudes a face along its normal direction, creating a 3D solid. Positive values push outward (along the normal), negative values push inward. If copy is true the original face remains in place and a new extruded shape is created alongside it.

Parameters

Parameter	Type	Default value	Description
face	Face | FaceRef	undefined	the face to extrude
distance	number	undefined	extrusion distance in inches (positive = outward)
copy	boolean	false	when true, leaves the original face and creates a new solid

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Extrude the face upward (along Y axis)
  op.facePushPull(faceRef, 50);
}, 'Extrude L-shaped face');

Since

SDK 2.2.0 Protocol 1.1.0

---

faceReverse()

faceReverse(face): void

Flips a face so the front becomes the back and vice versa. The normal direction reverses, and front/back materials swap sides.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face or face reference

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Apply different materials to front/back
  const red = op.createMaterial('RedFront');
  op.materialSetColor(
    red, new SketchUpApi.Color(200, 50, 50)
  );
  const blue = op.createMaterial('BlueBack');
  op.materialSetColor(
    blue, new SketchUpApi.Color(50, 50, 200)
  );
  op.faceSetFrontMaterial(faceRef, red);
  op.faceSetBackMaterial(faceRef, blue);
  // Reverse to swap front/back
  op.faceReverse(faceRef);
}, 'Reverse face');

---

faceSetBackMaterial()

faceSetBackMaterial(face, material): void

Paints the back (reverse) side of a face with a material. The back side is the one facing away from the face’s normal direction.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face or face reference
material	Material | MaterialRef	the material or material reference

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Create back material
  const blue = op.createMaterial('BlueBack');
  op.materialSetColor(
    blue, new SketchUpApi.Color(50, 50, 200)
  );
  op.faceSetBackMaterial(faceRef, blue);
  return op.entityForRef(faceRef);
}, 'Apply back material');
console.log(face);

---

faceSetBackMaterialName()

faceSetBackMaterialName(face, materialName): void

Paints the back (reverse) side of a face with a material looked up by name.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face or face reference
materialName	string	The material’s name, like "Brick_Antique".

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Apply back material by name
  op.faceSetBackMaterialName(faceRef, 'blue');
  return op.entityForRef(faceRef);
}, 'Apply back material by name');
console.log(face);

---

faceSetEdgeProperties()

faceSetEdgeProperties(ref, edgeUsageType, edgeProperties): void

Updates edge display properties (soft, smooth, hidden) on all edges of a face that match a particular usage type. Use this to soften or hide interior edges in bulk without targeting each one individually.

Parameters

Parameter	Type	Description
ref	Face | FaceRef	the face or face reference
edgeUsageType	EdgeUsageType | "Any" | "Shared" | "UniqueToFace" | "UniqueOrUnboundToFace" | "UnboundToFace"	which edges to affect (border, interior, etc.)
edgeProperties	EdgePropertiesUpdate	the property changes to apply

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Hide all border edges
  op.faceSetEdgeProperties(faceRef,
    SketchUpApi.EdgeUsageType.Any,
    { hidden: true }
  );
}, 'Hide face edges');

---

faceSetFrontMaterial()

faceSetFrontMaterial(ref, materialRef): void

Sets the front material on the face, alias of drawingElementSetMaterial

Parameters

Parameter	Type	Description
ref	Face | FaceRef	the face or face reference
materialRef	Material | MaterialRef	the material or material reference

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Create and apply front material
  const red = op.createMaterial('RedFront');
  op.materialSetColor(
    red, new SketchUpApi.Color(200, 50, 50)
  );
  op.faceSetFrontMaterial(faceRef, red);
  return op.entityForRef(faceRef);
}, 'Apply front material');
console.log(face);

See

Operation.drawingElementSetMaterial

---

faceSetFrontMaterialName()

faceSetFrontMaterialName(ref, materialName): void

Sets the front material on the face by name, alias of drawingElementSetMaterialName

Parameters

Parameter	Type	Description
ref	DrawingElement | DrawingElementRef	the face or face reference
materialName	string	the name of the material

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Apply front material by name
  op.faceSetFrontMaterialName(faceRef, 'red');
  return op.entityForRef(faceRef);
}, 'Apply front material by name');
console.log(face);

See

Operation.drawingElementSetMaterialName

Group

createGroup()

createGroup(ref): GroupRef

Creates an empty group in the specified container. Groups organize geometry into named, movable clusters — like component instances, but unique (not reusable across the model). After creating a group, you can add faces, edges, or nested groups to it by passing the returned GroupRef as the container to other create methods.

Returns a GroupRef that’s valid only within this operation. To read the group’s properties or use it outside the operation callback, call entityForRef(groupRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the group will be created (model, another group, or a component instance).

Returns

GroupRef

A reference to the newly created empty group.

Example

let model = await SketchUpApi.getActiveModel();
let group = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.groupSetName(groupRef, 'MyGroup');
  const faceRef = op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  return op.entityForRef(groupRef);
}, 'Create group with face');
console.log(group);

See

• Group for code examples
• entityForRef

Since

SDK 2.30.0

---

groupApplyTransformation()

groupApplyTransformation(ref, transformation): void

Multiplies a transformation onto the group’s existing transform. Use this to move or rotate a group incrementally without losing its current position — unlike groupSetTransformation which replaces everything.

Parameters

Parameter	Type	Description
ref	Group | GroupRef	the group or group reference
transformation	TransformationLike	the transformation to compose on top

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create group at origin
let groupRef = await model.performOperation(op => {
  const ref = op.createGroup(op.model);
  const { edges } = op.createCircle(
    ref, [400, 0, 0], [0, 0, 1], 50
  );
  const faceRef = op.createFaceFromEdges(
    ref, edges
  );
  op.drawingElementSetMaterialName(
    faceRef, '#DA70D6'
  );
  op.faceSetBackMaterialName(
    faceRef, '#DA70D6'
  );
  return op.entityForRef(ref);
}, 'Create group with circle');
// Second operation: apply relative transformation
await model.performOperation(op => {
  op.groupApplyTransformation(
    groupRef,
    SketchUpApi.Transformation.translation(
      [0, 100, 0]
    )
  );
}, 'Apply group transformation');

---

groupSetDescription()

groupSetDescription(ref, description): void

Sets a human-readable description on a group. This text appears in SketchUp’s Entity Info panel when the group is selected.

Parameters

Parameter	Type	Description
ref	Group | GroupRef	the group or group reference
description	string	the description text

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  const { edges } = op.createCircle(
    groupRef, [0, 0, 0], [0, 0, 1], 50
  );
  const faceRef = op.createFaceFromEdges(
    groupRef, edges
  );
  op.drawingElementSetMaterialName(
    faceRef, '#FF6347'
  );
  op.faceSetBackMaterialName(
    faceRef, '#FF6347'
  );
  op.groupSetDescription(
    groupRef, 'A simple circular disc'
  );
}, 'Set group description');

---

groupSetLocked()

groupSetLocked(ref, locked): void

Locks or unlocks a group. Locked groups cannot be moved, edited, or deleted by the user in the viewport — but you can still modify them programmatically.

Parameters

Parameter	Type	Description
ref	Group | GroupRef	the group or group reference
locked	boolean	true to lock, false to unlock

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  const { edges } = op.createCircle(
    groupRef, [100, 0, 0], [0, 0, 1], 50
  );
  const faceRef = op.createFaceFromEdges(
    groupRef, edges
  );
  op.drawingElementSetMaterialName(
    faceRef, '#4682B4'
  );
  op.faceSetBackMaterialName(
    faceRef, '#4682B4'
  );
  op.groupSetLocked(groupRef, true);
}, 'Lock group');

---

groupSetName()

groupSetName(ref, name): void

Gives a group a user-visible name. This name appears in the Outliner panel and Entity Info.

Parameters

Parameter	Type	Description
ref	Group | GroupRef	the group or group reference
name	string	the display name, like "Roof" or "Room 3"

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  const { edges } = op.createCircle(
    groupRef, [200, 0, 0], [0, 0, 1], 50
  );
  const faceRef = op.createFaceFromEdges(
    groupRef, edges
  );
  op.drawingElementSetMaterialName(
    faceRef, '#32CD32'
  );
  op.faceSetBackMaterialName(
    faceRef, '#32CD32'
  );
  op.groupSetName(groupRef, 'CircleGroup');
}, 'Set group name');

---

groupSetTransformation()

groupSetTransformation(ref, transformation): void

Replaces a group’s transformation (position, rotation, scale) relative to its parent container. This is an absolute set — any previous transformation is discarded.

Parameters

Parameter	Type	Description
ref	Group | GroupRef	the group or group reference
transformation	TransformationLike	the new transformation matrix

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
// First operation: create group at origin
let groupRef = await model.performOperation(op => {
  const ref = op.createGroup(op.model);
  const { edges } = op.createCircle(
    ref, [300, 0, 0], [0, 0, 1], 50
  );
  const faceRef = op.createFaceFromEdges(
    ref, edges
  );
  op.drawingElementSetMaterialName(
    faceRef, '#FFD700'
  );
  op.faceSetBackMaterialName(
    faceRef, '#FFD700'
  );
  return op.entityForRef(ref);
}, 'Create group with circle');
// Second operation: set absolute transformation
await model.performOperation(op => {
  op.groupSetTransformation(
    groupRef,
    SketchUpApi.Transformation.translation(
      [0, 100, 0]
    )
  );
}, 'Set group transformation');

---

instanceSetGluedTo()

instanceSetGluedTo(entity, element): void

Attaches (glues) a component instance or group to a face, so it moves and rotates with that face. Gluing is how windows stay in walls and decals stick to surfaces. Pass undefined to detach the instance from its current face.

Parameters

Parameter	Type	Description
entity	ComponentInstance | Group | ComponentInstanceRef | GroupRef	the group or component instance to glue
element	CanBeGluedToRef | CanBeGluedTo | undefined	the face to glue it to, or undefined to unglue

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Floor face on the X/Y plane
  const floorRef = op.createFace(op.model, [
    [300, 0, 0], [500, 0, 0],
    [500, 500, 0], [300, 500, 0]
  ]);
  const bedDef = await op.loadDefinition({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'examples/models/Bed.skp'
    }
  });
  // Glueable components must allow gluing
  op.definitionSetTo2d(bedDef, true);
  const instanceRef = op.createInstance(
    op.model, bedDef,
    SketchUpApi.Transformation.translation(
      [400, 0, 0]
    )
  );
  op.instanceSetGluedTo(instanceRef, floorRef);
}, 'Glue instance to floor face');

Since

SDK 2.30.0 Protocol 1.18.0

Image

createImage()

Places an image into the model as a 2D entity. Images are flat rectangles that display a raster graphic — useful for reference photos, logos, or textures that aren’t applied to geometry. You can provide the image data as a data URL, an HTML image element, a Blob, or a fetch request.

The image is positioned by its lower-left corner (origin) and scaled to the given width and height (in inches). It initially faces the user along the model’s axes — you can rotate it afterward with transformation methods.

When options include a fetch or blob resource, this method returns a Promise that resolves once the image data is loaded. Data URLs and HTML elements load synchronously and return an ImageEntityRef directly.

Example

let model = await SketchUpApi.getActiveModel();
let img = await model.performOperation(async op => {
  const imgRef = await op.createImage(op.model, {
    resource: { request: 'https://cdn.habitat.sketchup.com/examples/images/ColorWheel.jpg' },
    origin: [0, 0, 0],
    width: 100,
    height: 100
  });
  return op.entityForRef(imgRef);
}, 'Create image');
console.log(img);

See

ImageEntity for code examples

Since

SDK 2.30.0 Protocol 1.18.0

Param

container

The container where the image will be placed (model, group, or component instance).

Param

options

Configuration including the image source (resource), position (origin), and dimensions (width and height in inches).

Call Signature

createImage(container, options): ImageEntityRef

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
options	ImageLoadDataUrl | ImageLoadHtmlElement

Returns

ImageEntityRef

Call Signature

createImage(container, options): Promise<ImageEntityRef>

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
options	ImageLoadFetch | ImageLoadBlob

Returns

Promise<ImageEntityRef>

Call Signature

createImage(container, options): ImageEntityRef | Promise<ImageEntityRef>

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
options	ImageLoadOptions

Returns

ImageEntityRef | Promise<ImageEntityRef>

---

imageApplyTransformation()

imageApplyTransformation(entity, transformation): void

Multiplies the image’s current transformation by the given transformation, moving or rotating it relative to its current position. To set an absolute position instead, use imageSetTransformation.

Parameters

Parameter	Type	Description
entity	ImageEntity | ImageEntityRef	the image to transform
transformation	TransformationLike	the transformation to compound with the current one

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let imgEntity = await model.performOperation(
  async op => {
    const imgRef = await op.createImage(op.model, {
      resource: {
        request: 'https://cdn.habitat.sketchup.com/' +
          'examples/images/ColorWheel.jpg'
      },
      origin: [300, 0, 0],
      width: 50,
      height: 50
    });
    return op.entityForRef(imgRef);
  }, 'Create image'
);

let rotated = await model.performOperation(op => {
  op.imageApplyTransformation(
    imgEntity,
    SketchUpApi.Transformation.rotation(
      [300, 0, 0], [0, 0, 1], Math.PI / 4
    )
  );
  return op.entityForRef(imgEntity);
}, 'Rotate image 45 degrees');
console.log(rotated.zrotation);
// => 0.7853981633974483

Since

SDK 2.21.0 Protocol 1.18.0

---

imageSetDimensions()

imageSetDimensions(entity, options): void

Resizes an image entity in the model. Width and height are in inches (model units). If you supply only one dimension, the aspect ratio is preserved.

Parameters

Parameter	Type	Description
entity	ImageEntity | ImageEntityRef	the image to resize
options	{ height?: number; width?: number; }	the new width and/or height in inches
options.height?	number	‐
options.width?	number	‐

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let img = await model.performOperation(async op => {
  const imgRef = await op.createImage(op.model, {
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'examples/images/ColorWheel.jpg'
    },
    origin: [100, 0, 0],
    width: 50,
    height: 50
  });
  op.imageSetDimensions(imgRef, {
    width: 100, height: 100
  });
  return op.entityForRef(imgRef);
}, 'Resize image');
console.log(img.width, img.height);
// => 100 100

Since

SDK 2.21.0 Protocol 1.18.0

---

imageSetGluedTo()

imageSetGluedTo(entity, element): void

Attaches (glues) an image entity to a face so it moves and rotates with that face. Useful for decals, photos, and texture references placed directly on surfaces. Pass undefined to detach the image from its current face.

Parameters

Parameter	Type	Description
entity	ImageEntity | ImageEntityRef	the image to glue
element	CanBeGluedToRef | CanBeGluedTo | undefined	the face to attach to, or undefined to unglue

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let img = await model.performOperation(async op => {
  const floorRef = op.createFace(op.model, [
    [400, 0, 0], [600, 0, 0],
    [600, 200, 0], [400, 200, 0]
  ]);
  const imgRef = await op.createImage(op.model, {
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'examples/images/ColorWheel.jpg'
    },
    origin: [450, 50, 0],
    width: 50,
    height: 50
  });
  op.imageSetGluedTo(imgRef, floorRef);
  return op.entityForRef(imgRef);
}, 'Glue image to floor');
console.log(img.gluedToId !== undefined);
// => true

Since

SDK 2.21.0 Protocol 1.18.0

---

imageSetOrigin()

imageSetOrigin(entity, origin): void

Moves the image’s anchor point (lower-left corner) to a new position in model space, without changing its rotation or size.

Parameters

Parameter	Type	Description
entity	ImageEntity | ImageEntityRef	the image to move
origin	Point3Like	the new anchor position in model coordinates

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let img = await model.performOperation(async op => {
  const imgRef = await op.createImage(op.model, {
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'examples/images/ColorWheel.jpg'
    },
    origin: [0, 0, 0],
    width: 50,
    height: 50
  });
  op.imageSetOrigin(imgRef, [0, 0, 50]);
  return op.entityForRef(imgRef);
}, 'Move image origin');
console.log(img.transform.origin.toArray());
// => [0, 0, 50]

Since

SDK 2.21.0 Protocol 1.18.0

---

imageSetTransformation()

imageSetTransformation(entity, transformation): void

Replaces the image’s transformation with an absolute one, setting its exact position and orientation in model space. To move it relative to its current position, use imageApplyTransformation.

Parameters

Parameter	Type	Description
entity	ImageEntity | ImageEntityRef	the image to reposition
transformation	TransformationLike	the new absolute transformation

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let imgEntity = await model.performOperation(
  async op => {
    const imgRef = await op.createImage(op.model, {
      resource: {
        request: 'https://cdn.habitat.sketchup.com/' +
          'examples/images/ColorWheel.jpg'
      },
      origin: [200, 0, 0],
      width: 50,
      height: 50
    });
    return op.entityForRef(imgRef);
  }, 'Create image'
);

let moved = await model.performOperation(op => {
  op.imageSetTransformation(
    imgEntity,
    SketchUpApi.Transformation.translation(
      [200, 100, 0]
    )
  );
  return op.entityForRef(imgEntity);
}, 'Reposition image');
console.log(moved.transform.origin.toArray());
// => [200, 100, 0]

Since

SDK 2.21.0 Protocol 1.18.0

Material

createMaterial()

createMaterial(name): MaterialRef

Creates a new material with the given name. The material starts with default properties (solid white, no texture) — use materialSetColor, materialSetAlpha, materialSetTexture, and related methods to configure it. Once created, you can apply it to faces, edges, groups, and component instances.

Material names should be unique within the model. If a material with the same name already exists, SketchUp may append a suffix to make it unique.

Returns a MaterialRef that’s valid only within this operation. To read the material’s properties or use it outside the operation callback, call entityForRef(materialRef) before the operation ends.

Parameters

Parameter	Type	Description
name	string	The material’s display name, like “BrickRed” or “Glass”.

Returns

MaterialRef

A reference to the newly created material.

Example

let model = await SketchUpApi.getActiveModel();
let material = await model.performOperation(op => {
  const matRef = op.createMaterial('BrickRed');
  op.materialSetColor(
    matRef, new SketchUpApi.Color(200, 80, 60)
  );
  return op.entityForRef(matRef);
}, 'Create material');
console.log(material);

See

• Material for code examples
• entityForRef

---

facePositionBackMaterial()

facePositionBackMaterial(face, material, positions, projection): void

Controls how a textured material is mapped onto the back (reverse) side of a face. Works identically to facePositionFrontMaterial but targets the opposite side.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face or face reference
material	Material | MaterialRef	the textured material to position
positions	TexturePositioning	1–4 pairs of [model point, UV point]
projection	Vector3Like | undefined	an optional repeating direction vector

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Create canvas with 4 colored circles
  const canvas = document.createElement('canvas');
  canvas.width = 200;
  canvas.height = 200;
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = 'black';
  ctx.fillRect(0, 0, 200, 200);
  // Red top-left, green top-right,
  // blue bottom-left, yellow bottom-right
  ctx.fillStyle = 'red';
  ctx.beginPath();
  ctx.arc(50, 50, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'green';
  ctx.beginPath();
  ctx.arc(150, 50, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'blue';
  ctx.beginPath();
  ctx.arc(50, 150, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'yellow';
  ctx.beginPath();
  ctx.arc(150, 150, 30, 0, Math.PI * 2);
  ctx.fill();
  // Create textured material and position
  const texMat = op.createMaterial(
    'TexturedBack'
  );
  const b64 = canvas.toDataURL().split(',')[1];
  await op.materialSetTextureDataBase64(
    texMat, b64, 100, 100
  );
  op.facePositionBackMaterial(faceRef,
    texMat,
    [
      [0, 0, 0], [0, 0, 0],
      [100, 0, 0], [1, 0, 0],
      [100, 0, 50], [1, 1, 0],
      [0, 0, 50], [0, 1, 0]
    ]
  );
}, 'Position back texture');

---

facePositionFrontMaterial()

facePositionFrontMaterial(face, material, positions, projection?): void

Controls how a textured material is mapped onto the front of a face. You provide pairs of [3D point, UV coordinate] to pin texture corners to specific locations on the face. The material must have a texture — positioning a solid-color material throws.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face or face reference
material	Material | MaterialRef	the textured material to position
positions	TexturePositioning	1–4 pairs of [model point, UV point]
projection?	Vector3Like	an optional repeating direction vector

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Create canvas with 4 colored circles
  const canvas = document.createElement('canvas');
  canvas.width = 200;
  canvas.height = 200;
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = 'black';
  ctx.fillRect(0, 0, 200, 200);
  // Red top-left, green top-right,
  // blue bottom-left, yellow bottom-right
  ctx.fillStyle = 'red';
  ctx.beginPath();
  ctx.arc(50, 50, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'green';
  ctx.beginPath();
  ctx.arc(150, 50, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'blue';
  ctx.beginPath();
  ctx.arc(50, 150, 30, 0, Math.PI * 2);
  ctx.fill();
  ctx.fillStyle = 'yellow';
  ctx.beginPath();
  ctx.arc(150, 150, 30, 0, Math.PI * 2);
  ctx.fill();
  // Create textured material and position
  const texMat = op.createMaterial(
    'TexturedFront'
  );
  const b64 = canvas.toDataURL().split(',')[1];
  await op.materialSetTextureDataBase64(
    texMat, b64, 100, 100
  );
  op.facePositionFrontMaterial(faceRef,
    texMat,
    [
      [0, 0, 0], [0, 0, 0],
      [100, 0, 0], [1, 0, 0],
      [100, 0, 50], [1, 1, 0],
      [0, 0, 50], [0, 1, 0]
    ]
  );
}, 'Position front texture');

---

faceSetBackMaterial()

faceSetBackMaterial(face, material): void

Paints the back (reverse) side of a face with a material. The back side is the one facing away from the face’s normal direction.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face or face reference
material	Material | MaterialRef	the material or material reference

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Create back material
  const blue = op.createMaterial('BlueBack');
  op.materialSetColor(
    blue, new SketchUpApi.Color(50, 50, 200)
  );
  op.faceSetBackMaterial(faceRef, blue);
  return op.entityForRef(faceRef);
}, 'Apply back material');
console.log(face);

---

faceSetBackMaterialName()

faceSetBackMaterialName(face, materialName): void

Paints the back (reverse) side of a face with a material looked up by name.

Parameters

Parameter	Type	Description
face	Face | FaceRef	the face or face reference
materialName	string	The material’s name, like "Brick_Antique".

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Apply back material by name
  op.faceSetBackMaterialName(faceRef, 'blue');
  return op.entityForRef(faceRef);
}, 'Apply back material by name');
console.log(face);

---

faceSetFrontMaterial()

faceSetFrontMaterial(ref, materialRef): void

Sets the front material on the face, alias of drawingElementSetMaterial

Parameters

Parameter	Type	Description
ref	Face | FaceRef	the face or face reference
materialRef	Material | MaterialRef	the material or material reference

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Create and apply front material
  const red = op.createMaterial('RedFront');
  op.materialSetColor(
    red, new SketchUpApi.Color(200, 50, 50)
  );
  op.faceSetFrontMaterial(faceRef, red);
  return op.entityForRef(faceRef);
}, 'Apply front material');
console.log(face);

See

Operation.drawingElementSetMaterial

---

faceSetFrontMaterialName()

faceSetFrontMaterialName(ref, materialName): void

Sets the front material on the face by name, alias of drawingElementSetMaterialName

Parameters

Parameter	Type	Description
ref	DrawingElement | DrawingElementRef	the face or face reference
materialName	string	the name of the material

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let face = await model.performOperation(op => {
  // Create L-shaped face on X/Z plane
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [100, 0, 0], [100, 0, 50],
    [50, 0, 50], [50, 0, 100],
    [0, 0, 100]
  ]);
  // Apply front material by name
  op.faceSetFrontMaterialName(faceRef, 'red');
  return op.entityForRef(faceRef);
}, 'Apply front material by name');
console.log(face);

See

Operation.drawingElementSetMaterialName

---

loadMaterial()

loadMaterial(options): Promise<MaterialRef>

Loads a material from an external resource (URL, Blob, or data URL) and adds it to the model. The resource must be a valid .skm (SketchUp Material) file. Use this to import pre-built materials from a library or CDN.

Parameters

Parameter	Type	Description
options	MaterialLoadOptions	resource and loading configuration

Returns

Promise<MaterialRef>

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const matRef = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  const faceRef = op.createFace(op.model, [
    [0, 0, 1], [100, 0, 1],
    [100, 100, 1], [0, 100, 1]
  ]);
  op.drawingElementSetMaterial(faceRef, matRef);
}, 'Load material from CDN');

Since

SDK 2.30.0 protocol 1.9.0

---

materialSetAlpha()

materialSetAlpha(material, alpha): void

Sets the opacity of a material. This controls how transparent the material appears when rendered.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
alpha	number	1.0 = fully opaque, 0.0 = fully transparent

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const matRef = op.createMaterial('Glass');
  op.materialSetAlpha(matRef, 0.5);
}, 'Set material alpha');

---

materialSetAmbientOcclusionEnabled()

materialSetAmbientOcclusionEnabled(material, aoEnabled): void

Enables or disables the ambient occlusion (AO) channel for a PBR material. When disabled, the AO strength setting has no effect. Enable first, then set the strength with materialSetAmbientOcclusionStrength. Only available in PBR workflow on SketchUp 2025+.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
aoEnabled	boolean	when true, AO crevice-darkening is active

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let matRef = await model.performOperation(async op => {
  const mat = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  op.materialSetAmbientOcclusionEnabled(mat, true);
  return mat;
}, 'Enable AO');

Since

SDK 2.12.0 Protocol 1.9.0

---

materialSetAmbientOcclusionStrength()

materialSetAmbientOcclusionStrength(material, aoStrength): void

Controls how pronounced ambient occlusion crevice-darkening appears on the material. Only applies to PBR materials with AO enabled.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
aoStrength	number	value from 0.0 (no effect) to 1.0 (full darkening)

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let matRef = await model.performOperation(async op => {
  const mat = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  op.materialSetAmbientOcclusionEnabled(mat, true);
  op.materialSetAmbientOcclusionStrength(mat, 0.8);
  return mat;
}, 'Set AO strength');

Since

SDK 2.12.0 Protocol 1.9.0

---

materialSetColor()

materialSetColor(material, color): void

Changes the base color of a material. If the material also has a texture, the color will tint or show through transparent areas — setting the color does not remove the texture.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
color	Color	the new color (use new SketchUpApi.Color(r, g, b))

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const matRef = op.createMaterial('WallPaint');
  op.materialSetColor(
    matRef, new SketchUpApi.Color(100, 150, 200)
  );
}, 'Set material color');

---

materialSetColorizeType()

materialSetColorizeType(material, colorizeType): void

Controls how the material’s color blends with its texture. The colorize type determines the blending algorithm — for example, tinting, shifting, or replacing the texture’s hue with the material color.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
colorizeType	MaterialColorizeType	the blending algorithm to use

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const mat = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  op.materialSetColor(mat,
    new SketchUpApi.Color(200, 100, 50)
  );
  op.materialSetColorizeType(mat,
    SketchUpApi.ColorizeType.Tint
  );
}, 'Set colorize type');

Since

SDK 2.15.0 Protocol 1.12.0

---

materialSetMetallicFactor()

materialSetMetallicFactor(material, metallicFactor): void

Controls how metallic the material appears. At 0.0 the surface looks like a dielectric (plastic, wood); at 1.0 it looks fully metallic (steel, gold). Only applies to PBR materials with metalness enabled.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
metallicFactor	number	value from 0.0 (non-metal) to 1.0 (fully metallic)

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const mat = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  op.materialSetMetalnessEnabled(mat, true);
  op.materialSetMetallicFactor(mat, 0.9);
}, 'Set metallic factor');

Since

SDK 2.12.0 Protocol 1.9.0

---

materialSetMetalnessEnabled()

materialSetMetalnessEnabled(material, metalnessEnabled): void

Enables or disables the metalness channel for a PBR material. When disabled, the metallic factor has no effect. Enable first, then set the intensity with materialSetMetallicFactor. Only available in PBR workflow on SketchUp 2025+.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
metalnessEnabled	boolean	when true, the metallic appearance is active

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const mat = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  op.materialSetMetalnessEnabled(mat, true);
}, 'Enable metalness');

Since

SDK 2.12.0 Protocol 1.9.0

---

materialSetName()

materialSetName(material, name): void

Renames a material. The new name must be unique among all materials in the model — SketchUp will error if there’s a collision.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
name	string	the new name, like "WallPaint_Blue"

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const matRef = op.createMaterial('Material1');
  op.materialSetName(matRef, 'CeramicTile');
}, 'Rename material');

---

materialSetNormalEnabled()

materialSetNormalEnabled(material, normalEnabled): void

Enables or disables the normal map channel for a PBR material. When disabled, the bump effect has no visual effect. Enable first, then set the intensity with materialSetNormalScale. Only available in PBR workflow on SketchUp 2025+.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
normalEnabled	boolean	when true, the normal map bump effect is active

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const mat = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  op.materialSetNormalEnabled(mat, true);
}, 'Enable normal map');

Since

SDK 2.12.0 Protocol 1.9.0

---

materialSetNormalScale()

materialSetNormalScale(material, normalScale): void

Controls the intensity of the normal map’s bump effect. Higher values make the surface appear more deeply textured; 0.0 disables the visual effect without removing the map. Only applies to PBR materials with normal mapping enabled.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
normalScale	number	intensity multiplier (0.0 = flat, typical range 0.0–2.0)

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const mat = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  op.materialSetNormalEnabled(mat, true);
  op.materialSetNormalScale(mat, 1.5);
}, 'Set normal scale');

Since

SDK 2.12.0 Protocol 1.9.0

---

materialSetNormalStyle()

materialSetNormalStyle(material, style): void

Chooses the convention used to interpret the normal map texture. Different authoring tools export normal maps in different formats (OpenGL vs DirectX style) — this setting ensures SketchUp reads the green channel correctly.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
style	MaterialNormalStyle	the normal map convention to use

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const mat = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  op.materialSetNormalStyle(mat,
    SketchUpApi.MaterialNormalStyle.OpenGL
  );
}, 'Set normal style');

Since

SDK 2.12.0 Protocol 1.9.0

---

materialSetRoughnessEnabled()

materialSetRoughnessEnabled(material, roughnessEnabled): void

Enables or disables the roughness channel for a PBR material. When disabled, the roughness factor has no effect. Enable first, then set the value with materialSetRoughnessFactor. Only available in PBR workflow on SketchUp 2025+.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
roughnessEnabled	boolean	when true, the roughness channel is active

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const mat = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  op.materialSetRoughnessEnabled(mat, true);
}, 'Enable roughness');

Since

SDK 2.12.0 Protocol 1.9.0

---

materialSetRoughnessFactor()

materialSetRoughnessFactor(material, roughnessFactor): void

Controls how rough or smooth the material’s surface appears. At 0.0 the surface is mirror-smooth (like polished chrome); at 1.0 it’s fully rough (like unfinished concrete). Only applies to PBR materials with roughness enabled.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
roughnessFactor	number	value from 0.0 (mirror) to 1.0 (fully rough)

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const mat = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  op.materialSetRoughnessEnabled(mat, true);
  op.materialSetRoughnessFactor(mat, 0.6);
}, 'Set roughness factor');

Since

SDK 2.12.0 Protocol 1.9.0

---

materialSetTexture()

materialSetTexture(material, texture, options?): void

Assigns a texture image to a material by copying an existing Texture object. Pass undefined to remove the texture and revert the material to solid color only. The optional textureType controls which PBR channel receives the texture (standard, normal map, metallic, etc.).

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material to assign the texture to
texture	Texture | undefined	the texture to copy, or undefined to remove
options?	{ textureType: MaterialTextureType; }	optional PBR texture type
options.textureType?	MaterialTextureType	‐

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const srcMatRef = await op.loadMaterial({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'materials/metal/Metal_Cladding_01_1K.skm'
    }
  });
  const srcMat = op.entityForRef(srcMatRef);
  const matRef = op.createMaterial('CopyTex');
  op.materialSetTexture(matRef, srcMat.texture);
}, 'Copy texture to material');

Since

SDK 2.12.0 Protocol 1.9.0

---

materialSetTextureDataBase64()

materialSetTextureDataBase64(material, base64Data, options?): void

Sets the material’s texture from a base64-encoded image string. Supports JPEG and PNG formats. This is the most common way to apply textures from canvas-generated images or fetched assets.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
base64Data	string	the base64-encoded image data (no data: prefix needed)
options?	{ textureType?: MaterialTextureType; }	texture type (standard or PBR channel)
options.textureType?	MaterialTextureType	‐

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const matRef = op.createMaterial('CanvasTex');
  // Create a simple texture on canvas
  const canvas = document.createElement('canvas');
  canvas.width = 64;
  canvas.height = 64;
  const ctx = canvas.getContext('2d');
  ctx.fillStyle = '#FF6B6B';
  ctx.fillRect(0, 0, 64, 64);
  const b64 = canvas.toDataURL().split(',')[1];
  await op.materialSetTextureDataBase64(matRef,
    b64
  );
}, 'Set material texture from base64');

Since

SDK 1.6.0 Protocol 0.5.0

---

materialSetTextureFromHtmlImage()

materialSetTextureFromHtmlImage(material, element, options_or_type?, quality?): void

Sets the material’s texture from an <img> element already loaded in the DOM. The image is internally converted to a data URL using canvas — see the MDN docs for supported type/quality options.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference
element	HTMLImageElement	the html element to convert into an image
options_or_type?	string | { quality?: number; textureType?: MaterialTextureType; type?: string; }	options for setting the texture (Added in SDK 2.12.0) or a deprecated type string
quality?	number	deprecated quality parameter

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const matRef = op.createMaterial('ImgTex');
  const img = document.createElement('img');
  img.src = 'data:image/svg+xml,%3Csvg...%3E';
  await img.decode();
  op.materialSetTextureFromHtmlImage(matRef, img);
}, 'Set material texture from image');

See

https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL for valid type and quality parameters

Since

SDK 1.6.0 Protocol 0.5.0

---

materialSetTextureImageRep()

materialSetTextureImageRep(material, options): void

Applies a texture to the material from raw pixel data (image rep). The imageData length must equal (width * (bitsPerPixel / 8) + rowPadding) * height.

The native byte order is RGB(A) on macOS and BGR(A) on Windows. Supplying a non-native byte order incurs a performance cost as the SDK must swap channels before sending to SketchUp.

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material to apply the texture to
options	SetTextureFromImageRepOptions	‐

Returns

void

See

https://ruby.sketchup.com/Sketchup/ImageRep.html#set_data-instance_method Image Rep Ruby documentation

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const matRef = op.createMaterial('TexturedMat');
  // 8x8 red pixels (3 bytes per pixel RGB)
  const pixelData = new Uint8Array(8 * 8 * 3);
  for (let i = 0; i < pixelData.length; i += 3) {
    pixelData[i] = 255;     // R
    pixelData[i + 1] = i % 255;  // G
    pixelData[i + 2] = 0;   // B
  }
  op.materialSetTextureImageRep(matRef, {
    width: 8,
    height: 8,
    bitsPerPixel: 24,
    rowPadding: 0,
    imageData: [...pixelData].map(p => String.fromCharCode(p)).join('')
  });
}, 'Set material texture from image rep');

---

purgeUnusedMaterials()

purgeUnusedMaterials(): void

Removes all materials from the model that are not applied to any face, group, or component instance. Useful for reducing file size after deleting geometry that used those materials.

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  // Create unused material (not applied to any geometry)
  op.createMaterial('UnusedMat');
  // Purge removes it
  op.purgeUnusedMaterials();
}, 'Purge unused materials');

Since

SDK 2.30.0

---

removeMaterial()

removeMaterial(material): void

Permanently removes a material from the model. Any faces that were using this material revert to the default (no material / inherited from parent).

Parameters

Parameter	Type	Description
material	Material | MaterialRef	the material or material reference to remove

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const matRef = op.createMaterial('TempMaterial');
  op.removeMaterial(matRef);
}, 'Remove material');

Since

SDK 2.30.0

---

setCurrentMaterial()

setCurrentMaterial(material): void

Sets the “active” material in the model — the one shown in SketchUp’s Materials panel and applied when the user paints with the Paint Bucket tool. Pass undefined to clear it.

Parameters

Parameter	Type	Description
material	Material | MaterialRef | undefined	the material to activate, or undefined to clear

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const matRef = op.createMaterial('ActiveMat');
  op.materialSetColor(
    matRef, new SketchUpApi.Color(150, 200, 100)
  );
  op.setCurrentMaterial(matRef);
}, 'Set current material');

Since

SDK 2.30.0

Model

modelDeleteAttribute()

modelDeleteAttribute(path, key): void

Removes an attribute from the model’s attribute dictionary. The path identifies which dictionary (or nested dictionary) contains the key. Must not be empty.

Parameters

Parameter	Type	Description
path	string | readonly string[]	the dictionary path (e.g. 'MyExtension' or ['MyExtension', 'Settings'])
key	string	the attribute key to delete

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation((op) => {
 op.modelDeleteAttribute('MyExtension', 'ConfigValue');
}, 'Delete model attribute');
model = await model.refresh();

console.log(
  model.attributes.hasValue('MyExtension')
);

---

modelDeleteAttributes()

modelDeleteAttributes(path): void

Removes an entire attribute dictionary (and all its keys) from the model. The path identifies which dictionary to delete. Must not be empty.

Parameters

Parameter	Type	Description
path	string | readonly string[]	the dictionary path (e.g. 'MyExtension' or ['MyExtension', 'Settings'])

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation((op) => {
 op.modelSetAttribute('MyExtension', 'version',
   '1.0');
}, 'Set attribute');
model = await model.refresh();

let hasAttr = model.attributes.hasValue(
  'MyExtension', 'version');
console.log('Before delete:', hasAttr);

await model.performOperation((op) => {
 op.modelDeleteAttributes('MyExtension');
}, 'Delete attributes');
model = await model.refresh();

hasAttr = model.attributes.hasValue(
  'MyExtension', 'version');
console.log('After delete:', hasAttr);

---

modelLoadSchemaFromUrl()

modelLoadSchemaFromUrl(input, init?): Promise<void>

Loads an IFC or custom classification schema from a URL into the model. Once loaded, you can classify entities using the schema’s types. The URL should point to a valid SketchUp classification schema file.

Parameters

Parameter	Type	Description
input	RequestInfo | URL	the fetch RequestInfo or URL pointing to the schema
init?	RequestInit	optional fetch request initialization parameters

Returns

Promise<void>

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async (op) => {
 await op.modelLoadSchemaFromUrl(
   'https://example.com/schema.skc'
 );
}, 'Load schema');
console.log('Schema loaded');

NOTE: This method will fail if the schema with the same name already exists in the model, check the existence of the schema by name model.getClassifications() before calling this method.

Since

SDK 2.5.0 Protocol 1.3.0

---

modelSetActivePath()

modelSetActivePath(path): void

Opens a group or component for editing, as if the user had double-clicked into it. The path must be a valid chain from the model root to the target container — the operation will fail if the path is invalid. Pass an empty array to return to the model root.

Parameters

Parameter	Type	Description
path	(ActivePathEntity | ActivePathEntityRef)[]	the path from the root of the model through subsequent groups and instances

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let instances =
 await model.entities.get({filterBy: {types: ['ComponentInstance']}});
if (instances.length > 0) {
  await model.performOperation((op) => {
   op.modelSetActivePath([instances[0]]);
  }, 'Activate first component');
  let activePath = await model.getActivePath();

  console.log(activePath);
} else {
  console.log('No component instances available.');
}

Since

SDK 2.17.0 Protocol 1.14.0

---

modelSetAttribute()

modelSetAttribute(path, key, value): void

Stores a custom key/value pair in one of the model’s attribute dictionaries. Attributes let you attach arbitrary data to the model — useful for plugin state or metadata.

Parameters

Parameter	Type	Description
path	string | readonly string[]	The dictionary path (must not be empty), like 'MyPlugin' or ['MyPlugin', 'Settings'].
key	string	the attribute key
value	AttributeValue	the value to set

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation((op) => {
 op.modelSetAttribute('MyExtension', 'ConfigValue', true);
}, 'Set model name');
model = await model.refresh();

console.log(model.attributes.getValue('MyExtension', 'ConfigValue'));

---

modelSetAxes()

modelSetAxes(origin, xaxis, yaxis, zaxis): void

Repositions the model’s global axes. The three axis vectors must be mutually orthogonal — the operation will fail otherwise.

Parameters

Parameter	Type	Description
origin	Point3Like	the new origin point (in inches)
xaxis	Vector3Like	the red axis direction (must be unit length)
yaxis	Vector3Like	the green axis direction (must be unit length)
zaxis	Vector3Like	the blue axis direction (must be unit length)

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation((op) => {
 op.modelSetAxes([100,100,0],[1,0,0],[0,1,0],[0,0,-1]);
}, 'Invert and offset axes');
let axes = await model.getAxes();

console.log(axes);

---

modelSetCRSLocation()

modelSetCRSLocation(location): void

Sets or clears the model’s geographic coordinate reference system (CRS) location. This geo-locates the model in real-world coordinates. Pass undefined to clear the location.

Parameters

Parameter	Type	Description
location	CRSLocationData | MinimalCRSLocationData | undefined	the CRS data, or undefined to clear

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let crs = new SketchUpApi.CRSLocation({
 name: 'EPSG:27700',
 eastings: 530000,
 northings: 180000,
 height: 0,
 scale: SketchUpApi.CRSScale.Meters
});
await model.performOperation((op) => {
 op.modelSetCRSLocation(crs);
}, 'Set CRS location');
console.log('CRS location set');

Since

SDK 2.28.0 Protocol 1.25.0

---

modelSetName()

modelSetName(name): void

Changes the model’s internal name. This is not the same as the window title (which comes from the file name on disk).

Parameters

Parameter	Type	Description
name	string	the model name

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation((op) => {
 op.modelSetName('New Model Name');
}, 'Set model name');
model = await model.refresh();

console.log(model.name);

---

modelUnloadSchema()

modelUnloadSchema(schemaName): void

Removes a previously loaded classification schema from the model. Any entities classified with this schema will lose their classification data.

Parameters

Parameter	Type	Description
schemaName	string	the name of the schema to unload

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let schemaUrl =
 'https://cdn.habitat.sketchup.com/' +
 'classifications/schemas/IFC2x3.skc';
await model.performOperation(async (op) => {
 await op.modelLoadSchemaFromUrl(schemaUrl);
}, 'Load IFC schema');
await model.performOperation((op) => {
 op.modelUnloadSchema('IFC2x3');
}, 'Unload IFC schema');
console.log('Schema unloaded');

Since

SDK 2.5.0 Protocol 1.3.0

Operation

model

readonly model: Model

---

name

readonly name: string

---

currentStatus

Get Signature

get currentStatus(): "open" | "committed" | "aborted" | "closed_backend"

Returns the local lifecycle state. This value may lag behind SketchUp’s actual state — call synchronize() if you need a guaranteed-fresh answer.

See

Operation.synchronize to ensure this value is up to date

Returns

"open" | "committed" | "aborted" | "closed_backend"

the current status of the operation

---

status

Get Signature

get status(): "open" | "committed" | "aborted" | "closed_backend"

The current lifecycle state of this operation. Starts as 'open' and transitions to 'committed' or 'aborted' when you finish.

Returns

"open" | "committed" | "aborted" | "closed_backend"

---

abort()

abort(): Promise<OperationAbortResult>

Aborts this operation, discarding all queued instructions. The model reverts to the state before the operation started. Only call this if you used model.startOperation() — when using model.performOperation(), abort happens automatically on error.

Returns

Promise<OperationAbortResult>

a promise with the abort result.

See

Model.startOperation

---

commit()

commit(): Promise<OperationCommitResult>

Commits this operation, applying all queued instructions to the model. Only call this if you used model.startOperation() — when using model.performOperation(), commit happens automatically.

Returns

Promise<OperationCommitResult>

a promise with the commit result.

See

Model.startOperation

---

flush()

flush(): void

Sends any buffered instructions to SketchUp immediately instead of waiting for the next automatic batch. Useful when you want to ensure progress before continuing with more instructions.

Returns

void

Since

SDK 2.21.0

---

synchronize()

synchronize(): Promise<OperationStatusResult>

Waits until all instructions queued so far have been processed by SketchUp. Use this when you need to read back geometry that you just created earlier in the same operation. Overuse will hurt performance — each call is a full round-trip.

Returns

Promise<OperationStatusResult>

a promise containing the operation status

Throws

Error if the backend operation is already closed

Other

toString()

toString(): string

Returns

string

RenderingOptions

sceneUpdateRenderingOptions()

sceneUpdateRenderingOptions(scene, update): void

Applies rendering option changes to the given scene’s saved rendering state. If any property fails to update, the entire operation is rejected. To fully configure a scene’s appearance, call this alongside styleUpdateRenderingOptions.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene to update
update	RenderingOptionsUpdate	the rendering option properties to change

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const sceneRef = op.createScene(
    'Red Sky', { use_rendering_options: true }
  );
  op.sceneUpdateRenderingOptions(sceneRef, {
    SkyColor: '#FF0000'
  });
  return op.entityForRef(sceneRef);
}, 'Update scene rendering options');
let options = await scene.getRenderingOptions();
console.log(options.SkyColor.toHex());
// => "#FF0000FF"

Since

SDK 2.24.0 Protocol 1.21.0

Scene

createScene()

createScene(name?, properties?, index?): SceneRef

Creates a scene that captures the current state of the model. Scenes (also called pages) save camera position, visible tags, active section planes, shadow settings, and other view properties so you can return to the same configuration later. They’re essential for presentations, construction sequences, and design reviews.

You can specify which properties to save — by default, all properties are captured. The scene is inserted at the given index in the scene list, or appended to the end if no index is provided.

Returns a SceneRef that’s valid only within this operation. To read the scene’s properties or use it outside the operation callback, call entityForRef(sceneRef) before the operation ends.

Parameters

Parameter	Type	Default value	Description
name	string | undefined	undefined	The scene’s display name. If undefined, SketchUp generates a name like “Scene 1”.
properties	Partial<SketchupSceneProperties>	ALL_SCENE_PROPS	Which model properties to capture (camera, tags, styles, etc.). Defaults to all properties.
index	number | undefined	undefined	Where to insert the scene in the list (0-based). Defaults to the end.

Returns

SceneRef

A reference to the newly created scene.

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const sceneRef =
    op.createScene('MyScene');
  return op.entityForRef(sceneRef);
}, 'Create scene');
console.log(scene);

Create a scene capturing only the camera:

let model = await SketchUpApi.getActiveModel();
let cameraScene =
  await model.performOperation(op => {
  const sceneRef = op.createScene(
    'CameraOnly', { use_camera: true }
  );
  return op.entityForRef(sceneRef);
}, 'Create camera scene');
console.log(cameraScene);

See

• Scene for code examples
• entityForRef

Since

SDK 2.30.0 Protocol 1.7.0

---

removeScene()

removeScene(scene): void

Permanently deletes a scene from the model. The scene tab and all its saved settings (camera, tag visibility, rendering options) are removed and cannot be recovered. This action cannot be undone.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference to delete

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const sceneRef = op.createScene('Temporary');
  const before = op.entityForRef(sceneRef);
  op.removeScene(sceneRef);
  return before;
}, 'Remove scene');
console.log(scene.name);
// => "Temporary"

Since

SDK 2.30.0 Protocol 1.7.0

---

sceneReorder()

sceneReorder(scene, index): void

Moves a scene to a different position in the scene tab order. Scenes are displayed left-to-right in SketchUp’s scene tabs; index 0 is the leftmost position. This affects the tab order but not the scene’s saved settings.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference to move
index	number	the target zero-based tab position

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const firstRef = op.createScene('First');
  op.createScene('Second');
  op.sceneReorder(firstRef, 1);
}, 'Reorder scenes');
let scenes = await model.getScenes();
console.log(scenes.map(s => s.name));
// => ["Second", "First"]

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneSetAnimationDelayTime()

sceneSetAnimationDelayTime(scene, animationDelayTime): void

Sets how long SketchUp pauses on this scene (in seconds) before transitioning to the next scene during an animation playback. A delay of 0 means the transition starts immediately.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
animationDelayTime	number	pause duration in seconds before transitioning

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const sceneRef = op.createScene('Long Pause');
  op.sceneSetAnimationDelayTime(sceneRef, 3);
  return op.entityForRef(sceneRef);
}, 'Set scene delay time');
console.log(scene.animation.delayTime);
// => 3

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneSetAnimationTransitionTime()

sceneSetAnimationTransitionTime(scene, animationTransitionTime): void

Sets how long (in seconds) the animated transition into this scene takes. During playback, SketchUp interpolates camera position and other properties from the previous scene over this duration before settling on this scene.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
animationTransitionTime	number	transition duration in seconds

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const sceneRef = op.createScene('Slow Transition');
  op.sceneSetAnimationTransitionTime(sceneRef, 5);
  return op.entityForRef(sceneRef);
}, 'Set scene transition time');
console.log(scene.animation.transitionTime);
// => 5

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneSetAxes()

sceneSetAxes(scene, origin, xaxis, yaxis, zaxis): void

Sets the custom axes for a scene, overriding the model’s default axes when the scene is activated. Only takes effect if the scene has use_axes enabled — set this via sceneSetProperties first.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
origin	Point3Like	the origin of the axes
xaxis	Vector3Like	the x-axis direction vector
yaxis	Vector3Like	the y-axis direction vector
zaxis	Vector3Like	the z-axis direction vector

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const sceneRef = op.createScene(
    'Custom Axes', { use_axes: true }
  );
  op.sceneSetAxes(
    sceneRef,
    [50, 50, 0], [1, 0, 0], [0, 1, 0], [0, 0, 1]
  );
  return op.entityForRef(sceneRef);
}, 'Set scene axes');
console.log(scene.axes.origin);
// => Point3d { x: 50, y: 50, z: 0 }

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneSetCamera()

sceneSetCamera(scene, camera): void

Sets the saved camera viewpoint for a scene. When the user activates this scene, SketchUp will animate to the stored camera position. Only takes effect if the scene has use_camera enabled.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
camera	CameraData | Camera	the camera viewpoint to store for this scene

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const sceneRef = op.createScene(
    'Front View', { use_camera: true }
  );
  const cam = SketchUpApi.Camera.default()
    .setOrientation(
      [0, -500, 200], [0, 0, 0], [0, 0, 1]
    )
    .setFieldOfView(35);
  op.sceneSetCamera(sceneRef, cam.build());
  return op.entityForRef(sceneRef);
}, 'Set scene camera');
console.log(scene.camera.fieldOfView);
// => 35

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneSetDescription()

sceneSetDescription(scene, description): void

Sets the description for a scene. The description is visible in the Scenes panel alongside the scene name and can explain what the scene captures or when to use it.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
description	string	the description text

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const sceneRef = op.createScene('Overview');
  op.sceneSetDescription(
    sceneRef, 'Wide shot of the whole site'
  );
  return op.entityForRef(sceneRef);
}, 'Set scene description');
console.log(scene.description);
// => "Wide shot of the whole site"

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneSetDrawingElementVisibility()

sceneSetDrawingElementVisibility(scene, element, visible): void

Stores the visibility state of a drawing element in a scene. When the user activates this scene, the element is shown or hidden accordingly. Only takes effect if the scene has use_hidden_objects enabled. The element must be at the model root, or be a component instance or section plane.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
element	DrawingElement | DrawingElementRef	the drawing element or element reference
visible	boolean	whether the element should be visible in this scene

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  const sceneRef = op.createScene(
    'Hide Group', { use_hidden_objects: true }
  );
  op.sceneSetDrawingElementVisibility(
    sceneRef, groupRef, false
  );
  return op.entityForRef(sceneRef);
}, 'Hide element in scene');
let hidden = await scene.getHiddenElements();
console.log(hidden.length);
// => 1

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneSetIncludedInAnimation()

sceneSetIncludedInAnimation(scene, includedInAnimation): void

Controls whether this scene is played back during a SketchUp animation. When false, the scene is skipped — the animation jumps from the previous scene to the next one. The scene tab still appears; it’s just excluded from playback.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
includedInAnimation	boolean	when false, this scene is skipped during animation

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const sceneRef = op.createScene('Skip Me');
  op.sceneSetIncludedInAnimation(sceneRef, false);
  return op.entityForRef(sceneRef);
}, 'Exclude scene from animation');
console.log(scene.animation.included);
// => false

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneSetName()

sceneSetName(scene, name): void

Renames a scene. The name appears in the scene’s tab at the bottom of the SketchUp viewport. If the name is not unique, SketchUp will append a suffix to make it unique.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
name	string	the new tab name for the scene

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const sceneRef = op.createScene('Draft');
  op.sceneSetName(sceneRef, 'Final Render');
  return op.entityForRef(sceneRef);
}, 'Rename scene');
console.log(scene.name);
// => "Final Render"

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneSetProperties()

sceneSetProperties(scene, properties): void

Configures which aspects of the model a scene saves and restores. Properties are flags like use_camera, use_hidden_tags, use_hidden_objects, and use_rendering_options. When the user activates the scene, only the enabled properties are applied. Omitted properties are left unchanged.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
properties	Partial<SketchupSceneProperties>	the partial properties to set, any properties not included will be left alone

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const sceneRef = op.createScene('Camera Only');
  op.sceneSetProperties(sceneRef, {
    use_camera: true,
    use_hidden_tags: false
  });
  return op.entityForRef(sceneRef);
}, 'Set scene properties');
console.log(scene.properties.use_camera);
// => true

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneSetTagFolderVisibility()

sceneSetTagFolderVisibility(scene, folder, visible): void

Stores the visibility state of a tag folder in a scene. All tags in the folder are affected when the scene is activated. Only takes effect if the scene has use_hidden_tags enabled.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
folder	TagFolder | TagFolderRef	the tag folder or folder reference
visible	boolean	whether the tag folder should be visible in this scene

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const folderRef = op.createTagFolder('MEP');
  const sceneRef = op.createScene(
    'No MEP', { use_hidden_tags: true }
  );
  op.sceneSetTagFolderVisibility(
    sceneRef, folderRef, false
  );
  return op.entityForRef(sceneRef);
}, 'Hide tag folder in scene');
let hidden = await scene.getHiddenTagFolders();
console.log(hidden.map(f => f.name));
// => ["MEP"]

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneSetTagVisibility()

sceneSetTagVisibility(scene, tag, visible): void

Stores the visibility state of a tag in a scene. When the user activates this scene, SketchUp shows or hides the tag accordingly. Only takes effect if the scene has use_hidden_tags enabled.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
tag	Tag | TagRef	the tag or tag reference
visible	boolean	whether the tag should be visible in this scene

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let scene = await model.performOperation(op => {
  const tagRef = op.createTag('Furniture');
  const sceneRef = op.createScene(
    'No Furniture', { use_hidden_tags: true }
  );
  op.sceneSetTagVisibility(sceneRef, tagRef, false);
  return op.entityForRef(sceneRef);
}, 'Hide tag in scene');
let hidden = await scene.getHiddenTags();
console.log(hidden.map(t => t.name));
// => ["Furniture"]

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneUpdate()

sceneUpdate(scene, properties): void

Updates the scene by capturing the current model state for the given properties. Unlike sceneSetProperties, which directly sets property values, this method re-captures what SketchUp currently shows — equivalent to “unset and re-set” the desired property. Excluded and false properties are not updated.

Parameters

Parameter	Type	Description
scene	Scene | SceneRef	the scene or scene reference
properties	Partial<SketchupSceneProperties>	the scene properties to re-capture from the current model state

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let sceneEntity = await model.performOperation(op => {
  const sceneRef = op.createScene(
    'Updating View', { use_camera: true }
  );
  return op.entityForRef(sceneRef);
}, 'Create scene');

await model.view.setCamera(
  SketchUpApi.Camera.default()
    .setOrientation(
      [0, -800, 400], [0, 0, 0], [0, 0, 1]
    )
    .build()
);

let updated = await model.performOperation(op => {
  op.sceneUpdate(sceneEntity, { use_camera: true });
  return op.entityForRef(sceneEntity);
}, 'Recapture scene camera');
console.log(updated.camera.eye);
// => Point3d { x: 0, y: -800, z: 400 }

Since

SDK 2.10.0 Protocol 1.7.0

SectionPlane

createSectionPlane()

createSectionPlane(ref, planeCoefficients): SectionPlaneRef

Creates a section plane in the container. The plane cuts through the model, revealing cross-sectional geometry. Activate it with sectionPlaneActivate to make the cut visible.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	the container or container ref
planeCoefficients	PlaneLike	the cutting plane as [a, b, c, d] coefficients

Returns

SectionPlaneRef

a reference to the created section plane

Example

let model = await SketchUpApi.getActiveModel();
await model.updateRenderingOptions(
  { DisplaySectionPlanes: true }
);
let sectionPlane =
  await model.performOperation(op => {
  const spRef = op.createSectionPlane(
    op.model, [0, 0, 1, -50]
  );
  return op.entityForRef(spRef);
}, 'Create section plane');
console.log(sectionPlane);

Since

SDK 2.30.0 Protocol 1.13.0

See

SectionPlane for code examples

---

entitiesSetActivateSectionPlane()

entitiesSetActivateSectionPlane(ref, sectionPlaneRef?): void

Activates a specific section plane in a container, or clears the active section plane. The active plane’s cut is applied to the view; only one plane can be active per container. Pass undefined or null to deactivate all section planes in the container.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	the entities container or reference
sectionPlaneRef?	SectionPlaneRef | null	the section plane to activate, or undefined/null to clear

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.updateRenderingOptions(
  { DisplaySectionPlanes: true }
);
let plane = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  const spRef = op.createSectionPlane(
    groupRef, [0, 0, 1, -25]
  );
  op.entitiesSetActivateSectionPlane(
    groupRef, spRef
  );
  return op.entityForRef(spRef);
}, 'Activate section plane in group');
console.log(plane.active);
// => true

Since

SDK 2.16.0 Protocol 1.13.0

---

sectionPlaneActivate()

sectionPlaneActivate(ref): void

Activates a section plane so its cut is visible and applied to the model view. Only one section plane can be active per container at a time — activating one automatically deactivates any previously active plane in the same container.

Parameters

Parameter	Type	Description
ref	SectionPlaneRef	the section plane or section plane reference

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.updateRenderingOptions(
  { DisplaySectionPlanes: true }
);
let plane = await model.performOperation(op => {
  const spRef = op.createSectionPlane(
    op.model, [0, 0, 1, -50]
  );
  op.sectionPlaneActivate(spRef);
  return op.entityForRef(spRef);
}, 'Activate section plane');
console.log(plane.active);
// => true

Since

SDK 2.16.0 Protocol 1.13.0

---

sectionPlaneDeactivate()

sectionPlaneDeactivate(ref): void

Deactivates a section plane, restoring the full model view. The section plane remains in the model but its cut is no longer applied to the viewport.

Parameters

Parameter	Type	Description
ref	SectionPlaneRef	the section plane or section plane reference

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.updateRenderingOptions(
  { DisplaySectionPlanes: true }
);
let plane = await model.performOperation(op => {
  const spRef = op.createSectionPlane(
    op.model, [0, 0, 1, -50]
  );
  op.sectionPlaneActivate(spRef);
  op.sectionPlaneDeactivate(spRef);
  return op.entityForRef(spRef);
}, 'Deactivate section plane');
console.log(plane.active);
// => false

Since

SDK 2.16.0 Protocol 1.13.0

---

sectionPlaneSetName()

sectionPlaneSetName(ref, name): void

Sets a display name for the section plane. The name appears in the Outliner panel and helps identify which cut each plane represents, like "North Elevation Cut".

Parameters

Parameter	Type	Description
ref	SectionPlaneRef	the section plane or section plane reference
name	string	the display name

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.updateRenderingOptions(
  { DisplaySectionPlanes: true }
);
let plane = await model.performOperation(op => {
  const spRef = op.createSectionPlane(
    op.model, [0, 0, 1, -50]
  );
  op.sectionPlaneSetName(
    spRef, 'North Elevation Cut'
  );
  return op.entityForRef(spRef);
}, 'Name section plane');
console.log(plane.name);
// => "North Elevation Cut"

Since

SDK 2.16.0 Protocol 1.13.0

---

sectionPlaneSetPlane()

sectionPlaneSetPlane(ref, plane): void

Repositions and reorients a section plane by setting new plane coefficients. The plane cuts the model at the defined position and angle, revealing cross-sections of the geometry.

Parameters

Parameter	Type	Description
ref	SectionPlaneRef	the section plane or section plane reference
plane	PlaneLike	the new plane as [a, b, c, d] coefficients

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.updateRenderingOptions(
  { DisplaySectionPlanes: true }
);
let plane = await model.performOperation(op => {
  const spRef = op.createSectionPlane(
    op.model, [0, 0, 1, -50]
  );
  op.sectionPlaneSetPlane(spRef, [0, 0, 1, -100]);
  return op.entityForRef(spRef);
}, 'Reposition section plane');
console.log(plane.plane.d);
// => -100

Since

SDK 2.16.0 Protocol 1.13.0

---

sectionPlaneSetSymbol()

sectionPlaneSetSymbol(ref, symbol): void

Sets the short symbol label displayed on the section plane’s indicator arrow in the viewport, like "A" or "01".

Parameters

Parameter	Type	Description
ref	SectionPlaneRef	the section plane or section plane reference
symbol	string	the short symbol label, like "A"

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.updateRenderingOptions(
  { DisplaySectionPlanes: true }
);
let plane = await model.performOperation(op => {
  const spRef = op.createSectionPlane(
    op.model, [0, 0, 1, -50]
  );
  op.sectionPlaneSetSymbol(spRef, 'A');
  return op.entityForRef(spRef);
}, 'Set section plane symbol');
console.log(plane.symbol);
// => "A"

Since

SDK 2.16.0 Protocol 1.13.0

Shadow Info

shadowInfoSetCity()

shadowInfoSetCity(city, scene?): void

Sets the city label in the shadow info. This is a display-only string that appears alongside the shadow settings — it does not affect sun position calculations (use shadowInfoSetLatitude and shadowInfoSetLongitude for that).

Parameters

Parameter	Type	Description
city	string	the city name to display, like "San Francisco"
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetCountry()

shadowInfoSetCountry(country, scene?): void

Sets the country label in the shadow info. Like shadowInfoSetCity, this is a display-only string and does not affect sun position calculations.

Parameters

Parameter	Type	Description
country	string	the country name to display, like "United States"
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetDark()

shadowInfoSetDark(dark, scene?): void

Sets the shadow darkness intensity, controlling how dark the shadow areas appear. Higher values produce darker, more pronounced shadows; lower values create lighter, softer shadows.

Parameters

Parameter	Type	Description
dark	number	the shadow darkness, from 0 (lightest) to 100 (darkest)
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetDaylightSavings()

shadowInfoSetDaylightSavings(daylightSavings, scene?): void

Controls whether daylight saving time is applied when computing shadow positions. When true, the shadow time is adjusted forward by one hour relative to standard time.

Parameters

Parameter	Type	Description
daylightSavings	boolean	when true, daylight saving time offset is applied
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetDisplayNorth()

shadowInfoSetDisplayNorth(displayNorth, scene?): void

Shows or hides the True North indicator line in the viewport. This line marks the direction of True North in the model, which may differ from the green axis if a north angle offset has been set.

Parameters

Parameter	Type	Description
displayNorth	boolean	when true, the north indicator line is visible
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetDisplayOnAllFaces()

shadowInfoSetDisplayOnAllFaces(displayOnAllFaces, scene?): void

Controls whether shadows appear on ALL faces, including those not directly facing the sun. When false, only sun-facing faces receive shadows. Enabling this is more realistic but can slow rendering on complex models.

Parameters

Parameter	Type	Description
displayOnAllFaces	boolean	when true, shadows render on all faces regardless of sun angle
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetDisplayOnGroundPlane()

shadowInfoSetDisplayOnGroundPlane(displayOnGroundPlane, scene?): void

Controls whether shadows are cast onto the virtual ground plane (Z = 0). Enabling this shows shadows falling on the ground even when no geometry exists there.

Parameters

Parameter	Type	Description
displayOnGroundPlane	boolean	when true, shadows render on the Z=0 ground plane
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetDisplayShadows()

shadowInfoSetDisplayShadows(displayShadows, scene?): void

The master toggle for shadow rendering. When false, no shadows are drawn regardless of other shadow settings. Turning shadows off can significantly speed up rendering and navigation.

Parameters

Parameter	Type	Description
displayShadows	boolean	when true, shadow rendering is enabled
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetEdgesCastShadows()

shadowInfoSetEdgesCastShadows(edgesCastShadows, scene?): void

Controls whether edges (as well as faces) cast shadows. When enabled, thin geometry like wires or mullions cast visible line shadows on surfaces beneath them.

Parameters

Parameter	Type	Description
edgesCastShadows	boolean	when true, edges cast shadows in addition to faces
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetLatitude()

shadowInfoSetLatitude(latitude, scene?): void

Sets the latitude used to compute the sun position for shadow rendering. This controls sun angle only — it does not change the model’s geographic location set via geo-location.

Parameters

Parameter	Type	Description
latitude	number	the latitude in degrees (−90 to 90)
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetLight()

shadowInfoSetLight(light, scene?): void

Sets the sunlight intensity for non-shadowed areas. Higher values make lit areas brighter and more washed out; lower values create a softer, more overcast look.

Parameters

Parameter	Type	Description
light	number	the light intensity, from 0 (dimmest) to 100 (brightest)
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetLongitude()

shadowInfoSetLongitude(longitude, scene?): void

Sets the longitude used to compute the sun position for shadow rendering. This controls sun angle only — it does not change the model’s geographic location set via geo-location.

Parameters

Parameter	Type	Description
longitude	number	the longitude in degrees (−180 to 180)
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetNorthAngle()

shadowInfoSetNorthAngle(northAngle, scene?): void

Sets the angle between the model’s green axis and True North, used to orient the sun for shadow rendering. Setting this to a non-zero value offsets north from the green axis and may break exports to geo-referenced formats.

Parameters

Parameter	Type	Description
northAngle	number	the north angle in degrees
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetShadowTimeEpochSeconds()

shadowInfoSetShadowTimeEpochSeconds(epochSeconds, scene?): void

Sets the date and time used for shadow calculations, expressed as a Unix timestamp (seconds since 1970-01-01 UTC). This determines the sun angle, so the same scene will look different at noon in June versus noon in December.

Parameters

Parameter	Type	Description
epochSeconds	number	the Unix timestamp for the shadow time
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetTZOffset()

shadowInfoSetTZOffset(tzOffset, scene?): void

Sets the UTC timezone offset used when computing shadow time. For example, -8 means Pacific Standard Time (UTC−8). This adjusts how the shadow time epoch maps to a local clock time for sun position calculations.

Parameters

Parameter	Type	Description
tzOffset	number	the hours offset from UTC, like -8 or +5.5
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

---

shadowInfoSetUseSunForAllShading()

shadowInfoSetUseSunForAllShading(useSunForAllShading, scene?): void

When enabled, SketchUp uses the sun direction for all ambient shading, even when shadows are off. This creates a shading effect that looks like sunlight without full shadow rendering, which is faster and still gives a sense of depth.

Parameters

Parameter	Type	Description
useSunForAllShading	boolean	when true, sun direction drives ambient shading
scene?	Scene | SceneRef	since 2.10.0 when supplied sets the value for the shadow info associated with the scene rather than the model

Returns

void

Snap

createSnap()

createSnap(ref, position, direction, up?): SnapRef

Creates a snap point in the container. Snap points define attachment locations for component instances (like connection points for furniture or fixtures).

The returned SnapRef is only valid within this operation. To access it after the operation ends, convert it with entityForRef(snapRef).

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	the container or container ref
position	Point3Like	the position of the snap point
direction	Vector3Like	the direction vector of the snap point
up?	Vector3Like	optional up vector (if omitted, SketchUp determines orientation automatically)

Returns

SnapRef

a reference to the created snap point

Example

let model = await SketchUpApi.getActiveModel();
let snap = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  const snapRef = op.createSnap(
    groupRef, [25, 25, 0], [0, 0, 1]
  );
  return op.entityForRef(snapRef);
}, 'Create snap on group');
console.log(snap);

See

• Snap for code examples
• entityForRef

Since

SDK 2.30.0 Protocol 1.17.0

---

snapSetPose()

snapSetPose(ref, position, direction?, up?): void

Sets the position and/or orientation of an existing Snap point

Parameters

Parameter	Type	Description
ref	Snap | SnapRef	the Snap or SnapRef to modify
position	Point3Like	the new position of the snap point
direction?	Vector3Like	optional direction vector; if omitted, SketchUp preserves current orientation
up?	Vector3Like	optional up vector (requires direction to be specified)

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let snap = await model.performOperation(op => {
  const groupRef = op.createGroup(op.model);
  op.createFace(groupRef, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  const snapRef = op.createSnap(
    groupRef, [25, 25, 0], [0, 0, 1]
  );
  op.snapSetPose(
    snapRef, [25, 25, 10], [0, 0, -1]
  );
  return op.entityForRef(snapRef);
}, 'Reposition snap on group');
console.log(snap.position.toArray());
// => [25, 25, 10]
console.log(snap.direction.toArray());
// => [0, 0, -1]

Since

SDK 2.20.0 Protocol 1.17.0

Style

createDuplicateStyle()

createDuplicateStyle(style): StyleRef

Duplicates an existing style, creating a new style with an auto-generated unique name and description. Useful for creating variations of a style without modifying the original.

Parameters

Parameter	Type	Description
style	Style | StyleRef	the style to duplicate

Returns

StyleRef

Example

let model = await SketchUpApi.getActiveModel();
let duplicate = await model.performOperation(
  async op => {
    const styleRef = await op.loadStyle({
      resource: {
        request: 'https://cdn.habitat.sketchup.com/' +
          'styles/defaults/Wireframe.style'
      }
    });
    const dupRef = op.createDuplicateStyle(styleRef);
    return op.entityForRef(dupRef);
  }, 'Duplicate style'
);
console.log(duplicate.name);
// => "Wireframe Copy"

See

Style for code examples

Since

SDK 2.30.0

---

loadStyle()

loadStyle(options): Promise<StyleRef>

Loads a style from the source. For a full list of default SketchUp styles use https://cdn.habitat.sketchup.com/styles/index.html.

This action cannot be undone.

Parameters

Parameter	Type	Description
options	{ deduplicate?: boolean; resource: ResourceSourceFetch | ResourceSourceDataUrl | ResourceSourceBlob; }	‐
options.deduplicate?	boolean	When true, an existing style will be reused if one matches the resource. As a side effect, the loaded style becomes the selected style. Defaults to true.
options.resource	ResourceSourceFetch | ResourceSourceDataUrl | ResourceSourceBlob	‐

Returns

Promise<StyleRef>

Example

let model = await SketchUpApi.getActiveModel();
let style = await model.performOperation(async op => {
  const styleRef = await op.loadStyle({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'styles/defaults/Wireframe.style'
    }
  });
  return op.entityForRef(styleRef);
}, 'Load style');
console.log(style.name);
// => "Wireframe"

Since

SDK 2.30.0 Protocol 1.23.0

---

purgeUnusedStyles()

purgeUnusedStyles(): void

Purges any unused styles from the model. This action cannot be undone.

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  await op.loadStyle({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'styles/defaults/Wireframe.style'
    }
  });
  op.purgeUnusedStyles();
}, 'Purge unused styles');
let styles = await model.getStyles();
let names = styles.map(s => s.name);
console.log(names.includes('Wireframe'));
// => false

Since

SDK 2.30.0 Protocol 1.23.0

---

removeStyle()

removeStyle(style): void

Removes a style from the model. This action cannot be undone.

Parameters

Parameter	Type	Description
style	Style | StyleRef	‐

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let style = await model.performOperation(async op => {
  const styleRef = await op.loadStyle({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'styles/defaults/HiddenLine.style'
    }
  });
  const before = op.entityForRef(styleRef);
  op.removeStyle(styleRef);
  return before;
}, 'Remove style');
console.log(style.name);
// => "HiddenLine"

Since

SDK 2.30.0 Protocol 1.23.0

---

setSelectedStyle()

setSelectedStyle(style): void

Sets the selected style to the given instance. This action cannot be undone.

Parameters

Parameter	Type
style	Style | StyleRef

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let selected = await model.performOperation(
  async op => {
    const styleRef = await op.loadStyle({
      resource: {
        request: 'https://cdn.habitat.sketchup.com/' +
          'styles/defaults/Wireframe.style'
      }
    });
    op.setSelectedStyle(styleRef);
    return op.entityForRef(styleRef);
  }, 'Select style'
);
console.log(selected.name);
// => "Wireframe"

Since

SDK 2.30.0 Protocol 1.23.0

---

styleSetDescription()

styleSetDescription(style, description): void

Sets the description of the style. This action cannot be undone. If the style is the active style, the change may be reverted when updateActiveStyle is called.

Parameters

Parameter	Type	Description
style	Style | StyleRef	‐
description	string	‐

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let style = await model.performOperation(async op => {
  const styleRef = await op.loadStyle({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'styles/defaults/Wireframe.style'
    }
  });
  op.styleSetDescription(
    styleRef, 'Outline-only presentation style'
  );
  return op.entityForRef(styleRef);
}, 'Set style description');
console.log(style.description);
// => "Outline-only presentation style"

Since

SDK 2.26.0 Protocol 1.23.0

---

styleSetName()

styleSetName(style, name): void

Sets the name of the style. This action cannot be undone. If the style is the active style, the change may be reverted when updateActiveStyle is called.

Parameters

Parameter	Type	Description
style	Style | StyleRef	‐
name	string	‐

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let style = await model.performOperation(async op => {
  const styleRef = await op.loadStyle({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'styles/defaults/Wireframe.style'
    }
  });
  op.styleSetName(styleRef, 'My Wireframe');
  return op.entityForRef(styleRef);
}, 'Rename style');
console.log(style.name);
// => "My Wireframe"

Since

SDK 2.26.0 Protocol 1.23.0

---

styleUpdateRenderingOptions()

styleUpdateRenderingOptions(style, update): void

Updates the rendering options for a style. Internally this selects the style, applies the rendering option changes, updates the selected style, then restores the previous selection.

Not all rendering option properties are supported for styles (fog properties, for example). To fully configure a scene’s rendering, call styleUpdateRenderingOptions followed by sceneUpdateRenderingOptions.

Parameters

Parameter	Type	Description
style	Style | StyleRef	‐
update	RenderingOptionsUpdate	‐

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let style = await model.performOperation(
  async op => {
    const styleRef = await op.loadStyle({
      resource: {
        request: 'https://cdn.habitat.sketchup.com/' +
          'styles/defaults/Wireframe.style'
      }
    });
    op.styleUpdateRenderingOptions(styleRef, {
      BackgroundColor: '#FFFFFF'
    });
    return op.entityForRef(styleRef);
  }, 'Update style rendering options'
);
let options = await style.getRenderingOptions();
console.log(options.BackgroundColor.toHex());
// => "#FFFFFFFF"

---

updateSelectedStyle()

updateSelectedStyle(): void

Updates the selected style to match the settings of the active style. This action cannot be undone.

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(async op => {
  const styleRef = await op.loadStyle({
    resource: {
      request: 'https://cdn.habitat.sketchup.com/' +
        'styles/defaults/Wireframe.style'
    }
  });
  op.setSelectedStyle(styleRef);
}, 'Select style');

await model.updateRenderingOptions({
  BackgroundColor: '#FF0000'
});

await model.performOperation(op => {
  op.updateSelectedStyle();
}, 'Save changes to style');

let selected = await model.getSelectedStyle();
console.log(selected.info.hasBeenModified);
// => false

Since

SDK 2.30.0 Protocol 1.23.0

Tag

createTag()

createTag(name, parent?): TagRef

Creates a tag (layer) with the given name under the parent.

If the name is already taken, this will return a reference to that existing tag

Parameters

Parameter	Type	Description
name	string	the name of the tag
parent?	TagFolder | TagFolderRef | TagManager	optionally supplied parent to create the tag under.

Returns

TagRef

Example

let model = await SketchUpApi.getActiveModel();
let tag = await model.performOperation(op => {
  const tagRef = op.createTag('MyLayer');
  return op.entityForRef(tagRef);
}, 'Create tag');
console.log(tag);
console.log('Open the tag manager to see the new tag');

Since

SDK 2.30.0

---

drawingElementSetTag()

drawingElementSetTag(ref, tag): void

Assigns a tag (layer) to a drawing element. Tags control visibility — when a tag is hidden, all entities on that tag disappear from view.

Parameters

Parameter	Type	Description
ref	DrawingElement | DrawingElementRef	the drawing element or drawing element reference
tag	Tag | TagRef	the tag to assign

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  const tagRef = op.createTag('Floors');
  op.drawingElementSetTag(faceRef, tagRef);
}, 'Assign tag to face');
console.log('Tag assigned');

---

drawingElementSetTagName()

drawingElementSetTagName(ref, tagName): void

Assigns a tag to a drawing element by the tag’s name string. Convenient when you know the tag name but don’t have a TagRef.

Parameters

Parameter	Type	Description
ref	DrawingElement | DrawingElementRef	the drawing element or drawing element reference
tagName	string	the display name of the tag, like "Structure"

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const faceRef = op.createFace(op.model, [
    [0, 0, 0], [50, 0, 0],
    [50, 50, 0], [0, 50, 0]
  ]);
  op.createTag('Floors');
  op.drawingElementSetTagName(faceRef, 'Floors');
}, 'Assign tag by name');
console.log('Tag assigned by name');

---

removeTag()

removeTag(ref, removeEntities?): void

Permanently deletes a tag from the model. When removeEntities is false (the default), any entities on this tag are reassigned to the default “Untagged” tag rather than deleted.

Parameters

Parameter	Type	Default value	Description
ref	Tag | TagRef	undefined	the tag or tag reference
removeEntities	boolean	false	when true, entities on this tag are also deleted

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let tags = await model.performOperation(op => {
  const tagRef = op.createTag('Scratch');
  const before = op.entityForRef(tagRef);
  op.removeTag(tagRef);
  return { before };
}, 'Remove tag');
console.log(tags.before.name);
// => "Scratch"

Since

SDK 2.30.0

---

removeTagFromFolder()

removeTagFromFolder(ref, tagFolderRef): void

Removes a tag from a folder and moves it back to the top-level tag manager. The tag itself is not deleted — it remains in the model, just no longer nested under that folder.

Parameters

Parameter	Type	Description
ref	Tag | TagRef	the tag or tag reference to un-nest
tagFolderRef	TagFolder | TagFolderRef	the folder to remove the tag from

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let tag = await model.performOperation(op => {
  const folderRef = op.createTagFolder('Structural');
  const tagRef = op.createTag('Beams', folderRef);
  op.removeTagFromFolder(tagRef, folderRef);
  return op.entityForRef(tagRef);
}, 'Un-nest tag from folder');
console.log(tag.folderRef);
// => undefined

Since

SDK 2.30.0

---

tagAssignParent()

tagAssignParent(ref, parent): void

Moves a tag into a different folder, or back to the top-level tag manager. Pass the TagManager as parent to place the tag at the root level (outside any folder).

Parameters

Parameter	Type	Description
ref	Tag | TagRef	the tag or tag reference to move
parent	TagFolder | TagFolderRef | TagManager	the folder to move the tag into, or TagManager for root

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let tag = await model.performOperation(op => {
  const folderRef = op.createTagFolder('Framing');
  const tagRef = op.createTag('Joists');
  op.tagAssignParent(tagRef, folderRef);
  return op.entityForRef(tagRef);
}, 'Move tag into folder');
console.log(tag.folderRef !== undefined);
// => true

---

tagSetColor()

tagSetColor(ref, color): void

Alters the color of the tag, used in the Color By Tag functionality in SketchUp

Parameters

Parameter	Type	Description
ref	Tag | TagRef	the tag or tag reference
color	Color	the color of the tag

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let tag = await model.performOperation(op => {
  const tagRef = op.createTag('Plumbing');
  op.tagSetColor(
    tagRef, new SketchUpApi.Color(0, 100, 200)
  );
  return op.entityForRef(tagRef);
}, 'Set tag color');
console.log(tag.color.toHex());
// => "#0064c8"

---

tagSetName()

tagSetName(ref, name): void

Alters the name of the tag, if the name is not unique this will result in an error

Parameters

Parameter	Type	Description
ref	Tag | TagRef	the tag or tag reference
name	string	the new name

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let tag = await model.performOperation(op => {
  const tagRef = op.createTag('Walls');
  op.tagSetName(tagRef, 'Exterior Walls');
  return op.entityForRef(tagRef);
}, 'Rename tag');
console.log(tag.name);
// => "Exterior Walls"

---

tagSetVisible()

tagSetVisible(ref, visible): void

Shows or hides all entities on the tag Visibility is hierarchical, an entity will only display if all the parent folders and its tag are visible.

Parameters

Parameter	Type	Description
ref	Tag | TagRef	the tag or tag reference
visible	boolean	true if the entities are visible

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let tag = await model.performOperation(op => {
  const tagRef = op.createTag('Furniture');
  op.tagSetVisible(tagRef, false);
  return op.entityForRef(tagRef);
}, 'Hide tag');
console.log(tag.visible);
// => false

Tag Folder

createTag()

createTag(name, parent?): TagRef

Creates a tag (layer) with the given name under the parent.

If the name is already taken, this will return a reference to that existing tag

Parameters

Parameter	Type	Description
name	string	the name of the tag
parent?	TagFolder | TagFolderRef | TagManager	optionally supplied parent to create the tag under.

Returns

TagRef

Example

let model = await SketchUpApi.getActiveModel();
let tag = await model.performOperation(op => {
  const tagRef = op.createTag('MyLayer');
  return op.entityForRef(tagRef);
}, 'Create tag');
console.log(tag);
console.log('Open the tag manager to see the new tag');

Since

SDK 2.30.0

---

createTagFolder()

createTagFolder(name, parent?): TagFolderRef

Creates a tag folder, there are no requirements for the uniqueness of the name

Parameters

Parameter	Type	Description
name	string	the name of the folder
parent?	TagFolder | TagFolderRef | TagManager	optionally a parent to create the folder on

Returns

TagFolderRef

Examples

Create a tag folder.

let model = await SketchUpApi.getActiveModel();
let folder = await model.performOperation(op => {
  const folderRef = op.createTagFolder('MyFolder');
  return op.entityForRef(folderRef);
}, 'Create tag folder');
console.log(folder);

Create a tag under a folder.

let model = await SketchUpApi.getActiveModel();
let tag = await model.performOperation(op => {
  const folderRef = op.createTagFolder('MyFolder');
  const tagRef = op.createTag('MyTag', folderRef);
  return op.entityForRef(tagRef);
}, 'Create tag in folder');
console.log(tag);

Since

SDK 2.30.0

---

removeTagFolder()

removeTagFolder(ref, parent?): void

Removes a tag folder from the model

Folders and Tags will be reassigned to the parent of the deleted folder

Parameters

Parameter	Type	Description
ref	TagFolder | TagFolderRef	the tag folder or tag folder reference
parent?	TagFolder | TagFolderRef | TagManager	when supplied, the folder is only removed if the parent is the same as supplied

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let folder = await model.performOperation(op => {
  const folderRef = op.createTagFolder('Temporary');
  const before = op.entityForRef(folderRef);
  op.removeTagFolder(folderRef);
  return before;
}, 'Remove tag folder');
console.log(folder.name);
// => "Temporary"

Since

SDK 2.30.0

---

removeTagFromFolder()

removeTagFromFolder(ref, tagFolderRef): void

Removes a tag from a folder and moves it back to the top-level tag manager. The tag itself is not deleted — it remains in the model, just no longer nested under that folder.

Parameters

Parameter	Type	Description
ref	Tag | TagRef	the tag or tag reference to un-nest
tagFolderRef	TagFolder | TagFolderRef	the folder to remove the tag from

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let tag = await model.performOperation(op => {
  const folderRef = op.createTagFolder('Structural');
  const tagRef = op.createTag('Beams', folderRef);
  op.removeTagFromFolder(tagRef, folderRef);
  return op.entityForRef(tagRef);
}, 'Un-nest tag from folder');
console.log(tag.folderRef);
// => undefined

Since

SDK 2.30.0

---

tagAssignParent()

tagAssignParent(ref, parent): void

Moves a tag into a different folder, or back to the top-level tag manager. Pass the TagManager as parent to place the tag at the root level (outside any folder).

Parameters

Parameter	Type	Description
ref	Tag | TagRef	the tag or tag reference to move
parent	TagFolder | TagFolderRef | TagManager	the folder to move the tag into, or TagManager for root

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let tag = await model.performOperation(op => {
  const folderRef = op.createTagFolder('Framing');
  const tagRef = op.createTag('Joists');
  op.tagAssignParent(tagRef, folderRef);
  return op.entityForRef(tagRef);
}, 'Move tag into folder');
console.log(tag.folderRef !== undefined);
// => true

---

tagFolderAssignParent()

tagFolderAssignParent(ref, parent): void

Moves a tag folder into a different parent folder, creating nested folder hierarchies, or back to the top-level tag manager. Pass the TagManager as parent to place the folder at the root level.

Parameters

Parameter	Type	Description
ref	TagFolder | TagFolderRef	the tag folder or tag folder reference to move
parent	TagFolder | TagFolderRef | TagManager	the new parent folder, or TagManager for root

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let folder = await model.performOperation(op => {
  const parentRef = op.createTagFolder('Building');
  const childRef = op.createTagFolder('Floor 1');
  op.tagFolderAssignParent(childRef, parentRef);
  return op.entityForRef(childRef);
}, 'Nest tag folder');
console.log(folder.folderRef !== undefined);
// => true

---

tagFolderSetName()

tagFolderSetName(ref, name): void

Renames a tag folder. The name appears in the Tags panel to group related tags. Names do not need to be unique.

Parameters

Parameter	Type	Description
ref	TagFolder | TagFolderRef	the tag folder or folder reference
name	string	the new folder name

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let folder = await model.performOperation(op => {
  const folderRef = op.createTagFolder('MEP');
  op.tagFolderSetName(
    folderRef, 'Mechanical & Electrical'
  );
  return op.entityForRef(folderRef);
}, 'Rename tag folder');
console.log(folder.name);
// => "Mechanical & Electrical"

---

tagFolderSetVisible()

tagFolderSetVisible(ref, visible): void

Shows or hides all entities on the tag folder. Visibility is hierarchical, an entity will only display if all the parent folders and its tag are visible.

Parameters

Parameter	Type	Description
ref	TagFolder | TagFolderRef	the tag or tag reference
visible	boolean	true if the entities are visible

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
let folder = await model.performOperation(op => {
  const folderRef = op.createTagFolder('Site');
  op.tagFolderSetVisible(folderRef, false);
  return op.entityForRef(folderRef);
}, 'Hide tag folder');
console.log(folder.visible);
// => false

Text

createText()

createText(ref, text, attachment, vector?): TextRef

Creates a text annotation in the model. Text entities can be screen-facing labels (2D) or leader-line callouts pointing at specific geometry (3D). The attachment point determines where the text’s arrow touches the model, and can optionally reference a nested component instance path so the text follows that geometry when it moves.

If you omit the leader vector, SketchUp creates a 2D screen-space text that always faces the camera. Providing a vector creates a 3D text with a leader line extending from the attachment point in the vector’s direction.

Returns a TextRef that’s valid only within this operation. To read the text’s properties or use it outside the operation callback, call entityForRef(textRef) before the operation ends.

Parameters

Parameter	Type	Description
ref	EntitiesContainer | EntitiesContainerRef	The container where the text will be created (model, group, or component instance).
text	string	The text string to display.
attachment	TextAttachment	Either a 3D point, or an object with point and instancePath (array of entities forming a path to nested geometry).
vector?	Vector3Like	Optional leader direction. Omit to create a 2D screen text.

Returns

TextRef

A reference to the newly created text entity.

Examples

Create a standalone text entity.

let model = await SketchUpApi.getActiveModel();
let text = await model.performOperation(op => {
  const textRef = op.createText(
    op.model, 'Hello World',
    { point: [0, 0, 100] },
    [0, 0, 50]
  );
  return op.entityForRef(textRef);
}, 'Create text');
console.log(text);

Create text attached to a vertical edge.

let model = await SketchUpApi.getActiveModel();
let edgeText =
  await model.performOperation(op => {
  const edgeRefs = op.createEdge(op.model, [
    [50, 50, 0], [50, 50, 100]
  ]);
  const textRef = op.createText(
    op.model, 'Edge Label',
    { point: [50, 50, 50] },
    [50, 0, 0]
  );
  return op.entityForRef(textRef);
}, 'Create edge text');
console.log(edgeText);

See

• Text for code examples
• entityForRef

Since

SDK 2.30.0 Protocol 1.19.0

---

textSetArrowType()

textSetArrowType(ref, arrowType): void

Sets the arrowhead style at the leader’s attachment point. Values come from TextArrowType: None, Slash, Dot, Closed Arrow, or Open Arrow.

Parameters

Parameter	Type	Description
ref	Text | TextRef	the text or text reference
arrowType	TextArrowType	the arrowhead style

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const textRef = op.createText(
    op.model, 'Closed arrow',
    { point: [0, 0, 100] },
    [0, 50, 0]
  );
  op.textSetArrowType(
    textRef,
    SketchUpApi.TextArrowType.Closed
  );
}, 'Set text arrow type');

Since

SDK 2.22.0 Protocol 1.19.0

---

textSetAttachedTo()

textSetAttachedTo(ref, attachment): void

Changes what geometry this text label is attached to. The attachment includes the position and an instance path that navigates to the target entity inside nested groups or components. An instance path is required.

Parameters

Parameter	Type	Description
ref	Text | TextRef	the text or text reference
attachment	Required<TextAttachment>	the new attachment location and instance path

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const textRef = op.createText(
    op.model, 'Attached to point',
    { point: [1050, 0, 100] },
    [0, 50, 0]
  );
  // Attach the text to a construction point
  const pointRef = op.createConstructionPoint(
    op.model, [1050, 0, 100]
  );
  op.textSetAttachedTo(textRef, {
    point: [1050, 0, 100],
    instancePath: [pointRef],
  });
}, 'Set text attached to');

Since

SDK 2.22.0 Protocol 1.19.0

---

textSetDisplayLeader()

textSetDisplayLeader(ref, displayLeader): void

Shows or hides the leader line for a text entity. A text entity can have a leader configured but temporarily hidden — this toggles its visibility without removing the leader.

Parameters

Parameter	Type	Description
ref	Text | TextRef	the text or text reference
displayLeader	boolean	when true, the leader line is visible

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const textRef = op.createText(
    op.model, 'No leader',
    { point: [150, 0, 100] },
    [0, 50, 0]
  );
  op.textSetDisplayLeader(textRef, false);
}, 'Hide text leader');

Since

SDK 2.22.0 Protocol 1.19.0

---

textSetLeaderType()

textSetLeaderType(ref, leaderType): void

Sets how the leader line behaves in 3D space. Values come from TextLeaderType: View (leader stays flat to the screen) or Model (leader is fixed in 3D and rotates with the model).

Parameters

Parameter	Type	Description
ref	Text | TextRef	the text or text reference
leaderType	TextLeaderType	the leader behavior in 3D space

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const textRef = op.createText(
    op.model, 'Model leader',
    { point: [900, 0, 100] },
    [0, 50, 0]
  );
  op.textSetLeaderType(
    textRef,
    SketchUpApi.TextLeaderType.Model
  );
}, 'Set text leader type');

Since

SDK 2.22.0 Protocol 1.19.0

---

textSetLineWeight()

textSetLineWeight(ref, lineWeight): void

Sets the thickness of the leader line in pixels. A weight of 1 produces a thin line; higher values produce a bolder stroke. This affects only the leader line, not the text itself.

Parameters

Parameter	Type	Description
ref	Text | TextRef	the text or text reference
lineWeight	number	the leader line thickness in pixels

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const textRef = op.createText(
    op.model, 'Bold leader',
    { point: [750, 0, 100] },
    [0, 50, 0]
  );
  op.textSetLineWeight(textRef, 4);
}, 'Set text line weight');

Since

SDK 2.22.0 Protocol 1.19.0

---

textSetPoint()

textSetPoint(ref, point): void

Moves the text anchor — the position of the text box itself in 3D model space. This does not affect the leader attachment point; it only repositions where the label text appears.

Parameters

Parameter	Type	Description
ref	Text | TextRef	the text or text reference
point	Point3Like	the new anchor position for the text box

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const textRef = op.createText(
    op.model, 'Moved anchor',
    { point: [300, 0, 100] },
    [0, 50, 0]
  );
  // Move the text anchor further along Y
  op.textSetPoint(textRef, [300, 50, 150]);
}, 'Set text point');

Since

SDK 2.22.0 Protocol 1.19.0

---

textSetText()

textSetText(ref, text): void

Replaces the displayed label string of a text entity with new content. The string appears in the viewport as the label text.

Parameters

Parameter	Type	Description
ref	Text | TextRef	the text or text reference
text	string	the new label string to display

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const textRef = op.createText(
    op.model, 'Old label',
    { point: [600, 0, 100] },
    [0, 50, 0]
  );
  op.textSetText(textRef, 'New label');
}, 'Set text content');

Since

SDK 2.22.0 Protocol 1.19.0

---

textSetVector()

textSetVector(ref, vector): void

Sets the leader vector, which points from the text anchor toward the attachment point. The length of this vector determines how far the leader extends from the label.

Parameters

Parameter	Type	Description
ref	Text | TextRef	the text or text reference
vector	Vector3Like	the vector from the text box to the attachment point

Returns

void

Example

let model = await SketchUpApi.getActiveModel();
await model.performOperation(op => {
  const textRef = op.createText(
    op.model, 'Longer leader',
    { point: [450, 0, 100] },
    [0, 50, 0]
  );
  // Extend the leader further along Y
  op.textSetVector(textRef, [0, 100, 0]);
}, 'Set text vector');

Since

SDK 2.22.0 Protocol 1.19.0

Show Deprecated

Deprecated

arcCreate()

arcCreate(container, center, xaxis, normal, radius, startAngle, endAngle, numSegments?): ArcCurveAndComponents

Alias of createArc

Deprecated

since SDK 2.30.0, use createArc instead.

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
center	Point3Like
xaxis	Vector3Like
normal	Vector3Like
radius	number
startAngle	number
endAngle	number
numSegments?	number

Returns

ArcCurveAndComponents

Since

SDK 2.23.0 Protocol 1.20.0

---

circleCreate()

circleCreate(container, center, normal, radius, numSegments?): ArcCurveAndComponents

Alias of createCircle

Deprecated

since SDK 2.30.0, use createCircle instead.

Parameters

Parameter	Type	Default value
container	EntitiesContainer | EntitiesContainerRef	undefined
center	Point3Like	undefined
normal	Vector3Like	undefined
radius	number	undefined
numSegments	number	24

Returns

ArcCurveAndComponents

Since

SDK 2.23.0 Protocol 1.20.0

---

componentAddClassification()

componentAddClassification(ref, schemaName, schemaType): void

Alias of definitionAddClassification

Deprecated

since SDK 2.30.0, use definitionAddClassification instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef
schemaName	string
schemaType	string

Returns

void

---

componentCreate()

componentCreate(name): ComponentDefinitionRef

Alias of createDefinition

Deprecated

since SDK 2.30.0, use createDefinition instead.

Parameters

Parameter	Type
name	string

Returns

ComponentDefinitionRef

---

componentForRef()

componentForRef(ref): Promise<ComponentDefinition>

Finds a ComponentDefinition from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	ComponentDefinitionRef	the component reference

Returns

Promise<ComponentDefinition>

a promise containing the component

---

componentInstanceApplyTransformation()

componentInstanceApplyTransformation(ref, transformation): void

Alias of instanceApplyTransformation

Deprecated

since SDK 2.30.0, use instanceApplyTransformation instead.

Parameters

Parameter	Type
ref	ComponentInstance | ComponentInstanceRef
transformation	TransformationLike

Returns

void

---

componentInstanceCreate()

componentInstanceCreate(ref, componentRef, transform?): ComponentInstanceRef

Alias of createInstance

Deprecated

since SDK 2.30.0, use createInstance instead.

Parameters

Parameter	Type
ref	EntitiesContainer | EntitiesContainerRef
componentRef	ComponentDefinition | ComponentDefinitionRef
transform?	TransformationLike

Returns

ComponentInstanceRef

---

componentInstanceForRef()

componentInstanceForRef(ref): Promise<ComponentInstance>

Finds a ComponentInstance from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	ComponentInstanceRef	the component instance reference

Returns

Promise<ComponentInstance>

a promise containing the component instance

---

componentInstanceSetGluedTo()

componentInstanceSetGluedTo(entity, element): void

Alias of instanceSetGluedTo

Deprecated

since SDK 2.30.0, use instanceSetGluedTo instead.

Parameters

Parameter	Type
entity	ComponentInstance | Group | ComponentInstanceRef | GroupRef
element	CanBeGluedToRef | CanBeGluedTo | undefined

Returns

void

---

componentInstanceSetLocked()

componentInstanceSetLocked(ref, value): void

Alias of instanceSetLocked

Deprecated

since SDK 2.30.0, use instanceSetLocked instead.

Parameters

Parameter	Type
ref	ComponentInstance | ComponentInstanceRef
value	boolean

Returns

void

---

componentInstanceSetName()

componentInstanceSetName(ref, value): void

Alias of instanceSetName

Deprecated

since SDK 2.30.0, use instanceSetName instead.

Parameters

Parameter	Type
ref	ComponentInstance | ComponentInstanceRef
value	string

Returns

void

---

componentInstanceSetTransformation()

componentInstanceSetTransformation(ref, transformation): void

Alias of instanceSetTransformation

Deprecated

since SDK 2.30.0, use instanceSetTransformation instead.

Parameters

Parameter	Type
ref	ComponentInstance | ComponentInstanceRef
transformation	TransformationLike

Returns

void

---

componentInstancesForRefs()

componentInstancesForRefs(refs): Promise<readonly ComponentInstance[]>

Finds ComponentInstances from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly ComponentInstanceRef[]	the component instance references

Returns

Promise<readonly ComponentInstance[]>

a promise containing the component instances in the order specified

---

componentRemoveClassification()

componentRemoveClassification(ref, schemaName, schemaType): void

Alias of definitionRemoveClassification

Deprecated

since SDK 2.30.0, use definitionRemoveClassification instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef
schemaName	string
schemaType	string

Returns

void

Since

SDK 2.5.0 Protocol 1.3.0

---

componentSetClassificationValue()

componentSetClassificationValue(ref, path, value): void

Alias of definitionSetClassificationValue

Deprecated

since SDK 2.30.0, use definitionSetClassificationValue instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef
path	string[]
value	AttributeValue

Returns

void

---

componentSetDescription()

componentSetDescription(ref, value): void

Alias of definitionSetDescription

Deprecated

since SDK 2.30.0, use definitionSetDescription instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef
value	string

Returns

void

---

componentSetName()

componentSetName(ref, value): void

Alias of definitionSetName

Deprecated

since SDK 2.30.0, use definitionSetName instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef
value	string

Returns

void

---

componentSetNoScaleMask()

componentSetNoScaleMask(ref, value): void

Alias of definitionSetNoScaleMask

Deprecated

since SDK 2.30.0, use definitionSetNoScaleMask instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef
value	Partial<ComponentScaling>

Returns

void

---

componentSetShadowsToFaceSun()

componentSetShadowsToFaceSun(ref, value): void

Alias of definitionSetShadowsToFaceSun

Deprecated

since SDK 2.30.0, use definitionSetShadowsToFaceSun instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef
value	boolean

Returns

void

---

componentSetTo2d()

componentSetTo2d(ref, value): void

Alias of definitionSetTo2d

Deprecated

since SDK 2.30.0, use definitionSetTo2d instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef
value	boolean

Returns

void

---

componentSetToCutOpening()

componentSetToCutOpening(ref, value): void

Alias of definitionSetToCutOpening

Deprecated

since SDK 2.30.0, use definitionSetToCutOpening instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef
value	boolean

Returns

void

---

componentSetToFaceCamera()

componentSetToFaceCamera(ref, value): void

Alias of definitionSetToFaceCamera

Deprecated

since SDK 2.30.0, use definitionSetToFaceCamera instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef
value	boolean

Returns

void

---

componentSetToSnapTo()

componentSetToSnapTo(ref, value): void

Alias of definitionSetToSnapTo

Deprecated

since SDK 2.30.0, use definitionSetToSnapTo instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef
value	ComponentSnapTo

Returns

void

---

componentsForRefs()

componentsForRefs(refs): Promise<readonly ComponentDefinition[]>

Finds Components from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly ComponentDefinitionRef[]	the component references

Returns

Promise<readonly ComponentDefinition[]>

a promise containing the components in the order specified

---

componentsLoad()

componentsLoad(blob, options?): Promise<ComponentDefinitionRef>

Loads the blob as a component ref

Deprecated

since 2.30.0, use loadDefinition instead

Parameters

Parameter	Type	Description
blob	Blob	the binary representation of the component
options?	LegacyComponentLoadOptions	component loading options

Returns

Promise<ComponentDefinitionRef>

Since

SDK 2.6.0 Protocol 1.4.0

Throws

ComponentLoadError if SketchUp cannot load the component from the binary

---

componentsLoadFromUrl()

componentsLoadFromUrl(input, init?, options?): Promise<ComponentDefinitionRef>

Loads a component from the url

Deprecated

since 2.30.0, use loadDefinition instead

Parameters

Parameter	Type	Description
input	RequestInfo | URL	the fetch RequestInfo or URL
init?	RequestInit	optional fetch request initialization parameters
options?	LegacyComponentLoadOptions	component loading options

Returns

Promise<ComponentDefinitionRef>

Since

SDK 2.6.0 Protocol 1.4.0

Throws

ComponentLoadError if SketchUp cannot load the component from the binary or if the endpoint returns a non-2xx status code

---

componentsPurgeUnused()

componentsPurgeUnused(): void

Alias of purgeUnusedDefinitions

Deprecated

since SDK 2.30.0, use purgeUnusedDefinitions instead.

Returns

void

---

componentsRemove()

componentsRemove(ref): void

Alias of removeDefinition

Deprecated

since SDK 2.30.0, use removeDefinition instead.

Parameters

Parameter	Type
ref	ComponentDefinition | ComponentDefinitionRef

Returns

void

---

constructionLineCreate()

constructionLineCreate(ref, start, end, stipple?): ConstructionLineRef

Alias of createConstructionLine

Deprecated

since SDK 2.30.0, use createConstructionLine instead.

Parameters

Parameter	Type	Default value
ref	EntitiesContainer | EntitiesContainerRef	undefined
start	Point3d	undefined
end	Vector3d | Point3d	undefined
stipple	string	'-'

Returns

ConstructionLineRef

Since

SDK 2.7.0 Protocol 1.5.0

---

constructionLineForRef()

constructionLineForRef(ref): Promise<ConstructionLine>

Finds a constructionLine from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	ConstructionLineRef	the constructionLine reference

Returns

Promise<ConstructionLine>

a promise containing the ConstructionLine

---

constructionLinesForRefs()

constructionLinesForRefs(refs): Promise<readonly ConstructionLine[]>

Finds ConstructionLines from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly ConstructionLineRef[]	the construction lines references

Returns

Promise<readonly ConstructionLine[]>

a promise containing the ConstructionLine in the order specified

---

constructionPointCreate()

constructionPointCreate(ref, point): ConstructionPointRef

Alias of createConstructionPoint

Deprecated

since SDK 2.30.0, use createConstructionPoint instead.

Parameters

Parameter	Type
ref	EntitiesContainer | EntitiesContainerRef
point	Point3Like

Returns

ConstructionPointRef

Since

SDK 2.7.0 Protocol 1.5.0

---

constructionPointForRef()

constructionPointForRef(ref): Promise<ConstructionPoint>

Finds a constructionPoint from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	ConstructionPointRef	the constructionPoint reference

Returns

Promise<ConstructionPoint>

a promise containing the ConstructionPoint

---

constructionPointsForRefs()

constructionPointsForRefs(refs): Promise<readonly ConstructionPoint[]>

Finds ConstructionPoints from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly ConstructionPointRef[]	the construction points references

Returns

Promise<readonly ConstructionPoint[]>

a promise containing the ConstructionPoint in the order specified

---

curveCreate()

curveCreate(container, points): CurveAndComponents

Alias of createCurve

Deprecated

since SDK 2.30.0, use createCurve instead.

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
points	Point3Like[]

Returns

CurveAndComponents

Since

SDK 2.23.0 Protocol 1.20.0

---

curveCreateByWeldingEdges()

curveCreateByWeldingEdges(edges): Promise<CurveRef[]>

Alias of createCurveByWeldingEdges

Deprecated

since SDK 2.30.0, use createCurveByWeldingEdges instead.

Parameters

Parameter	Type
edges	readonly (Edge | EdgeRef)[]

Returns

Promise<CurveRef[]>

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionLinearCreate()

dimensionLinearCreate(container, start, end, offset): DimensionLinearRef

Alias of createDimensionLinear

Deprecated

since SDK 2.30.0, use createDimensionLinear instead.

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
start	DimensionPointRef
end	DimensionPointRef
offset	Vector3Like

Returns

DimensionLinearRef

Since

SDK 2.23.0 Protocol 1.20.0

---

dimensionRadialCreate()

dimensionRadialCreate(container, arcCurve, leaderBreakPoint): DimensionRadialRef

Alias of createDimensionRadial

Deprecated

since SDK 2.30.0, use createDimensionRadial instead.

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
arcCurve	ArcCurve | ArcCurveRef
leaderBreakPoint	Point3Like

Returns

DimensionRadialRef

Since

SDK 2.23.0 Protocol 1.20.0

---

drawingElementForRef()

drawingElementForRef(ref): Promise<DrawingElement>

Finds a DrawingElement from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	DrawingElementRef	the drawing element reference

Returns

Promise<DrawingElement>

a promise containing the drawing element

---

drawingElementsForRefs()

drawingElementsForRefs(refs): Promise<readonly DrawingElement[]>

Finds DrawingElements from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly DrawingElementRef[]	the drawing element references

Returns

Promise<readonly DrawingElement[]>

a promise containing the drawing elements in the order specified

---

edgeCreate()

edgeCreate(ref, vertices): readonly EdgeRef[]

Alias of createEdge

Deprecated

since SDK 2.30.0, use createEdge instead.

Parameters

Parameter	Type
ref	EntitiesContainer | EntitiesContainerRef
vertices	readonly Point3Like[]

Returns

readonly EdgeRef[]

---

edgeForRef()

edgeForRef(ref): Promise<Edge>

Finds a Edge from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	EdgeRef	the edge reference

Returns

Promise<Edge>

a promise containing the edge

---

edgesForRefs()

edgesForRefs(refs): Promise<readonly Edge[]>

Finds Edges from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly EdgeRef[]	the edge references

Returns

Promise<readonly Edge[]>

a promise containing the edges in the order specified

---

faceCreate()

faceCreate(ref, vertices): FaceRef

Alias of createFace

Deprecated

since SDK 2.30.0, use createFace instead.

Parameters

Parameter	Type
ref	EntitiesContainer | EntitiesContainerRef
vertices	readonly Point3Like[]

Returns

FaceRef

---

faceCreateFromEdges()

faceCreateFromEdges(ref, edges): FaceRef

Alias of createFaceFromEdges

Deprecated

since 2.30.0, use createFaceFromEdges instead.

Parameters

Parameter	Type
ref	EntitiesContainer | EntitiesContainerRef
edges	readonly (Edge | EdgeRef)[]

Returns

FaceRef

Since

SDK 2.25.0 Protocol 1.22.0

---

faceForRef()

faceForRef(ref): Promise<Face>

Finds a Face from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	FaceRef	the face reference

Returns

Promise<Face>

a promise containing the face

---

facesForRefs()

facesForRefs(refs): Promise<readonly Face[]>

Finds Faces from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly FaceRef[]	the face references

Returns

Promise<readonly Face[]>

a promise containing the faces in the order specified

---

groupCreate()

groupCreate(ref): GroupRef

Alias of createGroup

Deprecated

since SDK 2.30.0, use createGroup instead.

Parameters

Parameter	Type
ref	EntitiesContainer | EntitiesContainerRef

Returns

GroupRef

---

groupForRef()

groupForRef(ref): Promise<Group>

Finds a Group from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	GroupRef	the group reference

Returns

Promise<Group>

a promise containing the group

---

groupsForRefs()

groupsForRefs(refs): Promise<readonly Group[]>

Finds Groups from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly GroupRef[]	the group references

Returns

Promise<readonly Group[]>

a promise containing the groups in the order specified

---

imageCreate()

Call Signature

imageCreate(container, options): ImageEntityRef

Alias of createImage

Deprecated

since SDK 2.30.0, use createImage instead.

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
options	ImageLoadDataUrl | ImageLoadHtmlElement

Returns

ImageEntityRef

Since

SDK 2.21.0 Protocol 1.18.0

Call Signature

imageCreate(container, options): Promise<ImageEntityRef>

Alias of createImage

Deprecated

since SDK 2.30.0, use createImage instead.

Parameters

Parameter	Type
container	EntitiesContainer | EntitiesContainerRef
options	ImageLoadFetch

Returns

Promise<ImageEntityRef>

Since

SDK 2.21.0 Protocol 1.18.0

---

imageForRef()

imageForRef(ref): Promise<ImageEntity>

Finds a Image from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	ImageEntityRef	the image reference

Returns

Promise<ImageEntity>

a promise containing the group

---

imagesForRefs()

imagesForRefs(refs): Promise<readonly ImageEntity[]>

Finds Images from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly ImageEntityRef[]	the image references

Returns

Promise<readonly ImageEntity[]>

a promise containing the images in the order specified

---

materialForRef()

materialForRef(ref): Promise<Material>

Finds a Material from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	MaterialRef	the material reference

Returns

Promise<Material>

a promise containing the material

---

materialsAdd()

materialsAdd(name): MaterialRef

Alias of createMaterial

Deprecated

since SDK 2.30.0, use createMaterial instead.

Parameters

Parameter	Type
name	string

Returns

MaterialRef

---

materialsForRefs()

materialsForRefs(refs): Promise<readonly Material[]>

Finds Materials from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly MaterialRef[]	the material references

Returns

Promise<readonly Material[]>

a promise containing the materials in the order specified

---

materialsLoad()

materialsLoad(blob, options?): Promise<MaterialRef>

Loads a material from a binary blob of data (must be a valid skm file)

Deprecated

since SDK 2.30.0 use loadMaterial instead

Parameters

Parameter	Type	Description
blob	Blob	the data blob
options?	LegacyMaterialLoadOptions	material loading options

Returns

Promise<MaterialRef>

Since

SDK 2.12.0 protocol 1.9.0

---

materialsLoadDataUrl()

materialsLoadDataUrl(dataUrl, options?): Promise<MaterialRef>

Loads a material from a binary blob of data (must be a valid skm file)

Deprecated

since SDK 2.30.0 use loadMaterial instead

Parameters

Parameter	Type	Description
dataUrl	string	the data url
options?	LegacyMaterialLoadOptions	material loading options

Returns

Promise<MaterialRef>

Since

SDK 2.12.0 protocol 1.9.0

---

materialsLoadFromUrl()

materialsLoadFromUrl(input, init?, options?): Promise<MaterialRef>

Loads a material from the given URL

Deprecated

since SDK 2.30.0 use loadMaterial instead

Parameters

Parameter	Type	Description
input	RequestInfo | URL	the input url
init?	RequestInit	the request options for the http request
options?	LegacyMaterialLoadOptions	material loading options

Returns

Promise<MaterialRef>

Since

SDK 2.12.0 protocol 1.9.0

---

materialsPurgeUnused()

materialsPurgeUnused(): void

Alias of purgeUnusedMaterials

Deprecated

since SDK 2.30.0, use purgeUnusedMaterials instead.

Returns

void

---

materialsRemove()

materialsRemove(material): void

Alias of removeMaterial

Deprecated

since SDK 2.30.0, use removeMaterial instead.

Parameters

Parameter	Type
material	Material | MaterialRef

Returns

void

---

materialsSetCurrent()

materialsSetCurrent(material): void

Alias of setCurrentMaterial

Deprecated

since SDK 2.30.0, use setCurrentMaterial instead.

Parameters

Parameter	Type
material	Material | MaterialRef | undefined

Returns

void

---

ngonCreate()

ngonCreate(container, center, normal, radius, numSegments?): ArcCurveAndComponents

Alias of createNgon

Deprecated

since SDK 2.30.0, use createNgon instead.

Parameters

Parameter	Type	Default value
container	EntitiesContainer | EntitiesContainerRef	undefined
center	Point3Like	undefined
normal	Vector3Like	undefined
radius	number	undefined
numSegments	number	24

Returns

ArcCurveAndComponents

Since

SDK 2.23.0 Protocol 1.20.0

---

sceneCreate()

sceneCreate(name?, properties?, index?): SceneRef

Alias of createScene

Deprecated

since SDK 2.30.0, use createScene instead.

Parameters

Parameter	Type	Default value
name	string | undefined	undefined
properties	Partial<SketchupSceneProperties>	ALL_SCENE_PROPS
index	number | undefined	undefined

Returns

SceneRef

Since

SDK 2.10.0 Protocol 1.7.0

---

sceneForRef()

sceneForRef(ref): Promise<Scene>

Finds a Tag from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	SceneRef	the tag reference

Returns

Promise<Scene>

a promise containing the tag

---

sceneRemove()

sceneRemove(scene): void

Alias of removeScene

Deprecated

since SDK 2.30.0, use removeScene instead.

Parameters

Parameter	Type
scene	Scene | SceneRef

Returns

void

Since

SDK 2.10.0 Protocol 1.7.0

---

sectionPlaneCreate()

sectionPlaneCreate(ref, planeCoefficients): SectionPlaneRef

Alias of createSectionPlane

Deprecated

since SDK 2.30.0, use createSectionPlane instead.

Parameters

Parameter	Type
ref	EntitiesContainer | EntitiesContainerRef
planeCoefficients	PlaneLike

Returns

SectionPlaneRef

Since

SDK 2.16.0 Protocol 1.13.0

---

sectionPlaneForRef()

sectionPlaneForRef(ref): Promise<SectionPlane>

Finds a sectionPlane from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	SectionPlaneRef	the sectionPlane reference

Returns

Promise<SectionPlane>

a promise containing the SectionPlane

Since

SDK 2.16.0 Protocol 1.13.0

---

sectionPlanesForRefs()

sectionPlanesForRefs(refs): Promise<readonly SectionPlane[]>

Finds SectionPlanes from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly SectionPlaneRef[]	the section planes references

Returns

Promise<readonly SectionPlane[]>

a promise containing the SectionPlanes in the order specified

Since

SDK 2.16.0 Protocol 1.13.0

---

snapCreate()

snapCreate(ref, position, direction, up?): SnapRef

Alias of createSnap

Deprecated

since SDK 2.30.0, use createSnap instead.

Parameters

Parameter	Type
ref	EntitiesContainer | EntitiesContainerRef
position	Point3Like
direction	Vector3Like
up?	Vector3Like

Returns

SnapRef

Since

SDK 2.20.0 Protocol 1.17.0

---

snapForRef()

snapForRef(ref): Promise<Snap>

Finds a snap from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	SnapRef	the snap reference

Returns

Promise<Snap>

a promise containing the Snap

---

styleCreateDuplicate()

styleCreateDuplicate(style): StyleRef

Alias of createDuplicateStyle

Deprecated

since SDK 2.30.0, use createDuplicateStyle instead.

Parameters

Parameter	Type
style	Style | StyleRef

Returns

StyleRef

---

stylesLoad()

stylesLoad(options): Promise<StyleRef>

Alias of loadStyle

Deprecated

since SDK 2.30.0, use loadStyle instead.

Parameters

Parameter	Type
options	{ deduplicate?: boolean; resource: ResourceSourceFetch | ResourceSourceDataUrl | ResourceSourceBlob; }
options.deduplicate?	boolean
options.resource	ResourceSourceFetch | ResourceSourceDataUrl | ResourceSourceBlob

Returns

Promise<StyleRef>

Since

SDK 2.26.0 Protocol 1.23.0

---

stylesPurgeUnused()

stylesPurgeUnused(): void

Alias of purgeUnusedStyles

Deprecated

since SDK 2.30.0, use purgeUnusedStyles instead.

Returns

void

Since

SDK 2.26.0 Protocol 1.23.0

---

stylesRemove()

stylesRemove(style): void

Alias of removeStyle

Deprecated

since SDK 2.30.0, use removeStyle instead.

Parameters

Parameter	Type
style	Style | StyleRef

Returns

void

Since

SDK 2.26.0 Protocol 1.23.0

---

stylesSetSelected()

stylesSetSelected(style): void

Alias of setSelectedStyle

Deprecated

since SDK 2.30.0, use setSelectedStyle instead.

Parameters

Parameter	Type
style	Style | StyleRef

Returns

void

Since

SDK 2.26.0 Protocol 1.23.0

---

stylesUpdateSelected()

stylesUpdateSelected(): void

Alias of updateSelectedStyle

Deprecated

since SDK 2.30.0, use updateSelectedStyle instead.

Returns

void

Since

SDK 2.26.0 Protocol 1.23.0

---

tagCreate()

tagCreate(name, parent?): TagRef

Alias of createTag

Deprecated

since SDK 2.30.0, use createTag instead.

Parameters

Parameter	Type
name	string
parent?	TagFolder | TagFolderRef | TagManager

Returns

TagRef

---

tagFolderCreate()

tagFolderCreate(name, parent?): TagFolderRef

Alias of createTagFolder

Deprecated

since SDK 2.30.0, use createTagFolder instead.

Parameters

Parameter	Type
name	string
parent?	TagFolder | TagFolderRef | TagManager

Returns

TagFolderRef

---

tagFolderForRef()

tagFolderForRef(ref): Promise<TagFolder>

Finds a TagFolder from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	TagFolderRef	the tag folder reference

Returns

Promise<TagFolder>

a promise containing the tag folder

---

tagFolderRemove()

tagFolderRemove(ref, parent?): void

Alias of removeTagFolder

Deprecated

since SDK 2.30.0, use removeTagFolder instead.

Parameters

Parameter	Type
ref	TagFolder | TagFolderRef
parent?	TagFolder | TagFolderRef | TagManager

Returns

void

---

tagFoldersForRefs()

tagFoldersForRefs(refs): Promise<readonly TagFolder[]>

Finds TagFolders from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly TagFolderRef[]	the tag folder references

Returns

Promise<readonly TagFolder[]>

a promise containing the tag folders in the order specified

---

tagForRef()

tagForRef(ref): Promise<Tag>

Finds a Tag from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	TagRef	the tag reference

Returns

Promise<Tag>

a promise containing the tag

---

tagRemove()

tagRemove(ref, removeEntities?): void

Alias of removeTag

Deprecated

since SDK 2.30.0, use removeTag instead.

Parameters

Parameter	Type	Default value
ref	Tag | TagRef	undefined
removeEntities	boolean	false

Returns

void

---

tagRemoveFromFolder()

tagRemoveFromFolder(ref, tagFolderRef): void

Alias of removeTagFromFolder

Deprecated

since SDK 2.30.0, use removeTagFromFolder instead.

Parameters

Parameter	Type
ref	Tag | TagRef
tagFolderRef	TagFolder | TagFolderRef

Returns

void

---

tagsForRefs()

tagsForRefs(refs): Promise<readonly Tag[]>

Finds Tags from the supplied references

Deprecated

use entitiesForRefs instead

Parameters

Parameter	Type	Description
refs	readonly TagRef[]	the tag references

Returns

Promise<readonly Tag[]>

a promise containing the tags in the order specified

---

textCreate()

textCreate(ref, text, attachment, vector?): TextRef

Alias of createText

Deprecated

since SDK 2.30.0, use createText instead.

Parameters

Parameter	Type
ref	EntitiesContainer | EntitiesContainerRef
text	string
attachment	TextAttachment
vector?	Vector3Like

Returns

TextRef

Since

SDK 2.22.0 Protocol 1.19.0

---

textForRef()

textForRef(ref): Promise<Text>

Finds a text from the supplied reference

Deprecated

use entityForRef instead

Parameters

Parameter	Type	Description
ref	TextRef	the text reference

Returns

Promise<Text>

a promise containing the Text