TextRef

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

When you create text labels inside a SketchupOperation, the API returns TextRef objects immediately, before SketchUp has finished processing. You can pass these refs to other operation methods (like setting the arrow type or leader style), but if you need the full Text instance, you can request it with entityForRef().

Text entities are labels that point to a location in 3D space. They can float freely (screen text) or attach to geometry with a leader line.

Think of a ref as a “claim ticket” — it guarantees a text entity will exist after the operation commits, but it doesn’t carry the text’s properties (string content, attachment point, 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 Point3d = SketchUpApi.Point3d;

await model.performOperation(async op => {
  // Create a text label at a point in space
  const textRef = op.createText(
    model,
    'Hello, SketchUp!',
    { point: new Point3d(50, 50, 0) },
    [0, 0, 30] // leader vector (points up)
  );

  const text = await op.entityForRef(textRef);
  console.log(text.text);
  // => "Hello, SketchUp!"
}, 'Create a text label');

See

Properties

type

readonly type: Text = EntityType.Text

Accessors

sketchupId

Get Signature

get sketchupId(): SketchupId

Returns

SketchupId

the sketchupId of this text reference

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