Text

A 3D text label that can float in space or attach to geometry with a leader line.

Text entities are annotations in your model — they label points, edges, faces, or instances. Unlike dimensions, text labels are freeform and don’t measure geometry automatically.

A text entity has a position (point) and can optionally display a leader line pointing to the attachment location. The leader can be hidden, always visible, or auto-hidden based on distance. Arrow styles and line weights customize the visual appearance.

Example

let model = await SketchUpApi.getActiveModel();

// Create a text label with a leader pointing up.
await model.performOperation(op => {
  const textPoint = [100, 100, 0];
  const leaderVector = [0, 0, 50];
  op.createText(
    model,
    'My Label',
    { point: textPoint },
    leaderVector
  );
}, 'Create text label');

// Query it back and inspect its properties.
let texts = await model.entities.get({
  filterBy: { types: ['Text'] }
});
let label = texts[0];

console.log(label.text);
// => "My Label"
console.log(label.point.x, label.point.y, label.point.z);
// => 100 100 0
console.log(label.hasLeader);
// => true
console.log(label.vector);
// => Vector3d { x: 0, y: 0, z: 50 }

See

Extends

BaseDrawingElement

Properties

arrowType

readonly arrowType: TextArrowType

The arrow head style at the leader’s attachment point. Values match SketchUpTextArrowTypeEnum: 0 = None, 1 = Slash, 2 = Dot, 3 = Closed, 4 = Open.

attachedTo

readonly attachedTo: TextAttachedTo | undefined

Describes the geometry this text is attached to, if any. Includes the instance path (for labels inside groups or components) and the attachment point. Undefined for free- floating text.

attributes

readonly attributes: Attributes

The attribute dictionaries attached to this element. Attributes store custom key-value metadata that extensions can read and write.

Inherited from

BaseDrawingElement.attributes

castsShadows

readonly castsShadows: boolean

Whether this element casts shadows onto other geometry.

Inherited from

BaseDrawingElement.castsShadows

displayLeader

readonly displayLeader: boolean

Whether the leader line is currently visible. Leaders can be set to auto-hide when the text is close to the attachment point, so this may differ from hasLeader.

hasLeader

readonly hasLeader: boolean

Whether this text entity has a leader line configured. Leaders connect the text label to a specific point or piece of geometry in the model.

hidden

readonly hidden: boolean

Whether this element is hidden. Hidden elements don’t appear in the viewport unless the user enables “View > Hidden Geometry.”

Inherited from

BaseDrawingElement.hidden

id

readonly id: number

The persistent ID that uniquely identifies this text label.

leaderType

readonly leaderType: TextLeaderType

How the leader line behaves in 3D space. Values match SketchUpTextLeaderTypeEnum: 1 = View (leader stays flat to the screen), 2 = Model (leader is fixed in 3D space and rotates with the model).

lineWeight

readonly lineWeight: number

Thickness of the leader line in pixels, like 1 for thin or 4 for bold. Does not affect the text itself, only the line.

materialRef

readonly materialRef: MaterialRef | undefined

A reference to the material applied to this element, if any. Call getMaterial() to fetch the full Material object with color and texture data.

Inherited from

BaseDrawingElement.materialRef

point

readonly point: Point3d | undefined

The anchor position of the text label in model coordinates. This is where the text box itself is located in 3D space. Can be undefined if the text doesn’t have a fixed position.

receivesShadows

readonly receivesShadows: boolean

Whether this element receives shadows cast by other geometry.

Inherited from

BaseDrawingElement.receivesShadows

tagRef

readonly tagRef: TagRef | undefined

A reference to the tag (formerly “layer”) assigned to this element. Call getTag() to fetch the full Tag object.

Inherited from

BaseDrawingElement.tagRef

text

readonly text: string | undefined

The string content displayed by this text label, like “North Elevation” or “24 inches”. Can be undefined if the text was created without content.

type

readonly type: Text = EntityType.Text

vector

readonly vector: Vector3d | undefined

The direction and length of the leader line, pointing from the text anchor to the attachment point. Undefined if this text has no leader.

Accessors

sketchupId

Get Signature

get sketchupId(): SketchupId

JS API identifier for this text label. Pass it to API methods that accept a sketchupId.

Returns

SketchupId

Overrides

BaseDrawingElement.sketchupId

typeName

Get Signature

get typeName(): string

Returns a named variant of the type field.

Since

SDK 2.35.0

Returns

string

Methods

getBounds()

getBounds(): Promise<BoundingBox>

Fetches the axis-aligned bounding box for this element from SketchUp.

Returns

Promise<BoundingBox>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let box = await element.getBounds();
console.log(box.min.x, box.min.y, box.min.z);
console.log(box.max.x, box.max.y, box.max.z);

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getBounds

getMaterial()

getMaterial(): Promise<Material | undefined>

Fetches the material applied to this element. Returns undefined if the element uses the default material.

Returns

Promise<Material | undefined>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let mat = await element.getMaterial();
if (mat) {
  console.log(mat.name, mat.color.toHex());
}

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getMaterial

getTag()

getTag(): Promise<Tag | undefined>

Fetches the tag assigned to this element. Most elements have a tag — even those on the default “Untagged” tag. Returns undefined only if the tag reference is missing.

Returns

Promise<Tag | undefined>

Example

let model = await SketchUpApi.getActiveModel();
let all = await model.entities.get();
let element = all[0];
let tag = await element.getTag();
if (tag) {
  console.log(tag.name);
}

Since

SDK 2.30.0

Inherited from

BaseDrawingElement.getTag

refresh()

refresh(): Promise<Text>

Re-fetches this text label from SketchUp to get its current state. Because Text is a snapshot, it can become stale if the model changes (e.g., the text string is edited, or the leader is toggled). Call refresh() to get an up-to-date copy.

Returns

Promise<Text>

A new Text reflecting the current model state. Throws if the text has been deleted.

Example

let model = await SketchUpApi.getActiveModel();
let texts = await model.entities.get({
  filterBy: { types: ['Text'] },
});
// Later, after the user makes changes...
let fresh = await texts[0].refresh();
console.log(fresh.text, fresh.displayLeader);

toString()

toString(): string

Returns a string representation of an object.

Returns

string

Show Deprecated

Deprecated

materialId

readonly materialId: number | undefined

Inherited from

BaseDrawingElement.materialId

tagId

readonly tagId: number | undefined

Inherited from

BaseDrawingElement.tagId

bounds

Get Signature

get bounds(): Promise<BoundingBox>

Returns

Promise<BoundingBox>

Inherited from

BaseDrawingElement.bounds