FaceRef

A lightweight placeholder for a Face that hasn’t been fully loaded yet.

When you create a face inside a SketchupOperation, the API returns a FaceRef immediately, before SketchUp has finished processing it. You can pass these refs to other operation methods (like applying a material to the face), but if you need the full Face instance — with properties like area, normal, vertices, and edges — you can request it with entityForRef().

Think of a ref as a “claim ticket” — it guarantees a face will exist after the operation commits, but it doesn’t carry the face’s properties yet. A ref is only valid inside the performOperation callback that created it — do not return it or use it after the operation commits.

Example

let model = await SketchUpApi.getActiveModel();
let Color = SketchUpApi.Color;

await model.performOperation(async op => {
  // Create a square face
  const faceRef = op.createFace(model, [
    [0, 0, 0], [100, 0, 0],
    [100, 100, 0], [0, 100, 0],
  ]);
  // Apply a red material using the ref
  const matRef = op.createMaterial('Red');
  op.materialSetColor(
    matRef, new SketchUpApi.Color(255, 0, 0, 255)
  );
  op.drawingElementSetMaterial(faceRef, matRef);
}, 'Create a red square face');

See

Properties

sketchupId

readonly sketchupId: SketchupId

type

readonly type: Face = EntityType.Face

Accessors

typeName

Get Signature

get typeName(): string

Returns a named variant of the type field.

Since

SDK 2.35.0

Returns

string

Methods

toString()

toString(): string

Returns

string