MaterialRef

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

When you create a material inside a SketchupOperation, the API returns a MaterialRef immediately, before SketchUp has finished processing it. You can pass these refs to other operation methods (like applying the material to a face), but if you need the full Material instance, you can request it with entityForRef().

Think of a ref as a “claim ticket” — it guarantees a material will exist after the operation commits, but it doesn’t carry the material’s properties (color, texture, etc.) 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 material — returns a MaterialRef
  // instantly, before SketchUp processes it.
  const matRef = op.createMaterial('Ocean');

  // You can use the ref right away to set
  // properties on the new material.
  op.materialSetColor(
    matRef, new SketchUpApi.Color(0, 119, 190, 255)
  );

  // And apply it to a face.
  const faceRef = op.createFace(model, [
    [0, 0, 1], [100, 0, 1],
    [100, 100, 1], [0, 100, 1],
  ]);
  op.drawingElementSetMaterial(faceRef, matRef);

  // But reading material properties (like its
  // name) requires resolving to a full Material.
  const mat = await op.entityForRef(matRef);
  console.log(mat.name, mat.color.toHex());
  // => "Ocean" "#0077BEFF"
}, 'Create a blue face');

See

Properties

sketchupId

readonly sketchupId: SketchupId

type

readonly type: Material = EntityType.Material

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