TagRef

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

When you create tags inside a SketchupOperation, the API returns TagRef objects immediately, before SketchUp has finished processing. You can pass these refs to other operation methods (like assigning the tag to geometry), but if you need the full Tag instance, you can request it with entityForRef().

Tags (formerly called “layers”) control visibility of drawing elements. Assign a tag to geometry, then toggle it in the Tags panel to show or hide that geometry.

Think of a ref as a “claim ticket” — it guarantees a tag will exist after the operation commits, but it doesn’t carry the tag’s properties (name, color, visibility, 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 tag and give it a color
  const tagRef = op.createTag('Furniture');
  op.tagSetColor(tagRef, new SketchUpApi.Color(76, 175, 80));

  // Assign the tag to a face
  const faceRef = op.createFace(model, [
    [0, 0, 0], [48, 0, 0],
    [48, 48, 0], [0, 48, 0],
  ]);
  op.drawingElementSetTag(faceRef, tagRef);

  const tag = await op.entityForRef(tagRef);
  console.log(tag.name);
  // => "Furniture"
}, 'Create a tag and assign it');

See

Properties

sketchupId

readonly sketchupId: SketchupId

type

readonly type: Tag = EntityType.Tag

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