SnapRef

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

When you create snaps inside a SketchupOperation, the API returns SnapRef objects immediately, before SketchUp has finished processing the geometry. You can often pass these refs to other operation methods, but if you need the full Snap instance, you can request it with entityForRef().

Snaps are custom inference points that tools can snap to — like placing a magnet at a specific location and orientation in the model. Extensions use snaps to guide user interactions.

Think of a ref as a “claim ticket” — it guarantees a snap will exist after the operation commits, but it doesn’t carry the snap’s properties (position, direction, 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

// Create a circle with a snap at its center
let model = await SketchUpApi.getActiveModel();
let { Transformation } = SketchUpApi;

await model.performOperation(async op => {
  const groupRef = op.createGroup(model);
  op.groupSetName(groupRef, 'Snappable Circle');

  // Draw a 20" radius circle inside the group
  op.createCircle(
    groupRef,
    [0, 0, 0], // center (group-local)
    [0, 0, 1], // normal (up)
    20         // radius
  );

  // Add a snap at the group's origin so tools
  // can infer the circle's center
  const snapRef = op.createSnap(
    groupRef,
    [0, 0, 0], // position (group-local)
    [0, 0, 1]  // direction (up)
  );

  // Move the group to [30, 30, 0]
  op.drawingElementsApplyTransformation(
    groupRef, Transformation.translation([30, 30, 0])
  );

  const snap = await op.entityForRef(snapRef);
  console.log(snap.position.x, snap.position.y);
  // => 0 0 (group-local coordinates)
}, 'Create a circle with a snap at its center');

See

Since

SDK 2.20.0 Protocol 1.17.0

Properties

sketchupId

readonly sketchupId: SketchupId

type

readonly type: Snap = EntityType.Snap

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