Skip to content

Change Log

Fill in feature gaps of Vector3d and Point3d, as well as improving ergonomics.

Ergonomic Point3d and Vector3d Inputs

Anywhere the SDK accepts a Point3Like or Vector3Like — points, vectors, transformations, planes, rays — you can now also pass a {x, y, z?} object or an [x, y] tuple, with z defaulting to 0. Previously only a full [x, y, z] tuple or a Point3d/Vector3d instance was accepted.

New create() Factory Methods

Added consistent create() factories across the geometry classes:

New Ray3d Class

Added Ray3d, representing an immutable ray (or line) in 3D space, to support the new line-intersection methods on Point3d below.

New Point3d Methods

New Vector3d Methods

  • with() — returns a copy with selected x/y/z values replaced
  • fromLinearCombination() — combines two vectors using weighted coefficients
  • isSameDirectionAs() — true if two vectors point the same way (unlike isParallel, doesn’t match anti-parallel vectors)
  • isUnitVector() — true if the vector’s length is (approximately) 1

New Plane Methods

Renamed Methods

Every rename below is backward compatible: the previous name remains available as a deprecated alias and will continue to work until the next major version. Deprecated aliases log a one-time deprecation warning to the console.

  • Vector3d.parallel() → isParallel()
  • Vector3d.fromVector3Like() / fromVector2Like() → Vector3d.create()
  • Point3d.fromPoint3Like() / fromPoint2Like() → Point3d.create()
  • Plane.fromPlaneLike() → Plane.create()
  • Plane.distance() → Plane.distanceToPoint()

Note: toString() on Point3d, Vector3d, and Plane now omits brackets around the coordinates — e.g. Point3d(1,2,3) instead of Point3d([1,2,3]).

Migration Example:

// Old way (deprecated)
let v = Vector3d.fromVector3Like([1, 2, 3]);
let onPlane = plane.distance(point) < 0.001;
// New way (SDK 2.37.0)
let v = Vector3d.create([1, 2, 3]);
// or with the relaxed input shapes:
let v2 = Vector3d.create({ x: 1, y: 2 });
let onPlane = plane.distanceToPoint(point) < 0.001;

Updated third party libraries in ts code

Bug Fixes

  • Ensure examples can be pasted into the console and do not contain deprecated calls.
  • Remove accidental deprecation warning logged when calling model.getActiveSectionPlanes();

Bug Fixes

  • Fix an issue where the client was sending invalid dataURLs to SketchUp when loading certain resources via http.

Bug Fixes

Operation Queuing Support

Added support for queuing concurrent operation requests instead of immediately failing with an error. This is useful when handling rapid asynchronous requests from UI interactions or external systems.

Global Configuration:

Per-Operation Configuration:

Error Handling:

  • TimeoutError - New error class thrown when a queued operation exceeds its timeout

Migration Example:

// Enable operation queuing globally
await SketchUpApi.connect({
whenOperationInProgress: 'queue'
});
// Or configure per-operation
const model = await SketchUpApi.getActiveModel();
await model.performOperation(
(op) => op.modelSetAttribute('test', 'key', 'value'),
'My Operation',
{ whenOperationInProgress: 'queue' }
);
// Or with a timeout
await model.performOperation(
(op) => op.modelSetAttribute('test', 'key', 'value'),
'My Operation',
{
whenOperationInProgress: {
queueUpTo: { millis: 5000 }
}
}
);

Bug Fixes

Fixed an issue where stale object references could still communicate with SketchUp after a call to SketchUpApi.disconnect(). This was problematic because the model ID may change between disconnect/reconnect and global settings may not apply correctly.

Modal Dialog Buttons You Label Yourself:

  • ModalInputCustomAction — pass an array of these as a modal’s actions where the four shorthand sets ('ok', 'okcancel', 'yesno', 'yesnocancel') cannot say what the buttons actually do.

Each action becomes a button, in the order you list them, and the action on the response is the id of whichever one the user clicked. Dismissing the dialog still answers 'cancel'.

const answer = await SketchUpApi.ui.getModalInput({
title: 'Network Error',
message: 'We could not reach the server.',
actions: [
{ id: 'retry', label: 'Retry' },
{ id: 'cancel', label: 'Cancel', style: 'secondary' },
],
});
if (answer.action === 'retry') {
console.log('The user wants another try');
}

The shorthand sets are unchanged, so existing calls to getModalInput() need no edits.

API Naming Consistency Improvements

Removed the Sketchup prefix from various classes and types to improve consistency and align the SDK naming conventions. The old names remain available as deprecated aliases and will continue to work until the next major version. Deprecated aliases log a one-time deprecation warning to the console.

Renamed Classes and Types:

toString Methods

All publicly exposed classes now include a consistent toString() method that returns minimal but useful information for debugging and logging. This includes entity classes, references, and key types throughout the API.

Geometric Array Methods

Renamed Ruby-inspired to_a methods to the more idiomatic JavaScript toArray() across geometric classes for improved consistency with JavaScript naming conventions.

Camera API Improvements

Enhanced the Camera API for better immutability and consistency:

  • Camera can now be constructed from another Camera instance or from a CameraData interface
  • Methods that previously accepted SketchupCamera now accept CameraData or Camera
  • Mutable Camera methods have been deprecated in favor of immutable alternatives
  • Scene.getCamera() now returns a Camera instance instead of SketchupCamera

Unified find* Methods

Refactored lookup methods across multiple APIs to use a consistent find* naming convention that returns optional values instead of throwing errors.

Previous methods like getValue(), getValueWithPath(), getClassificationValue(), getTagByName(), and getTagFolderByName() remain as deprecated aliases.

Migration Example:

// Old way (deprecated - Sketchup prefix)
const entityType: SketchupEntity = 'Face';
const drawingProps: SketchupDrawingElementProperties = { hidden: true };
const edgeProps: SketchupEdgeProperties = { hidden: true };
// New way (SDK 2.35.0)
const entityType: EntityType = 'Face';
const drawingProps: DrawingElementPropertiesUpdate = { hidden: true };
const edgeProps: EdgePropertiesUpdate = { hidden: true };
// Geometric array methods
// Old way (deprecated)
const arr = point.to_a();
// New way (SDK 2.35.0)
const arr = point.toArray();
// Camera construction
const newCamera = new Camera(existingCamera);
// Unified find* methods
// Old way (deprecated)
const value = attributes.getValue('dict', 'key');
const tag = await tagManager.getTagByName('MyTag');
// New way (SDK 2.35.0)
const value = attributes.findValue('dict', 'key');
const tag = await tagManager.findTag('MyTag');
// Model attribute lookup
// Old way (deprecated)
const color = model.attributes.getValue('colors', 'primary');
const colorOrDefault = model.attributes.getValueOrDefault('colors', 'primary', 'black');
// New way (SDK 2.35.0)
const color = model.attributes.findValue('colors', 'primary');
const colorOrDefault = model.attributes.findValue('colors', 'primary', { defaultValue: 'black' });

Bug Fix

Fixed an inconsistency in the SketchupComponentScaling type where the disableRedBluePlane property did not follow the naming pattern of the other plane properties (disableGreenBlue and disableRedGreen).

The property has been renamed to disableRedBlue to match the existing pattern. The old property name remains available as a deprecated alias and will continue to work with a one-time deprecation warning logged to the console.

Migration:

// Old way (deprecated)
operation.definitionSetNoScaleMask(defRef, {
disableRedBluePlane: true
});
// New way (SDK 2.34.3)
operation.definitionSetNoScaleMask(defRef, {
disableRedBlue: true
});

Renamed EntitiesBuilder Methods:

Every rename below is backwards compatible: the previous name remains available as a deprecated alias and will continue to work until the next major version. Deprecated aliases log a one-time deprecation warning to the console.

Migration Example:

// Old way (deprecated)
builder.faceCreate(outerLoop);
// New way (SDK 2.34.0)
builder.createFace(outerLoop);

Bug Fix

Fixed a long-standing type inference bug where readonly arrays representing points or vectors (for example a readonly [number, number, number] tuple) could not be passed to EntitiesBuilder.createFace(), EntitiesBuilder.createEdge(), and other APIs that accept a Point3Like or Vector3Like.

Enums that previously had to be reached through a nested namespace, or passed as raw numbers, are now exposed directly on SketchUpApi for pure JavaScript usage.

Edge Usage Type Exposed:

The edge usage type filter used when bulk-updating edge properties is now part of the public API.

const model = await SketchUpApi.getActiveModel();
await model.performOperation(operation => {
operation.entitiesSetEdgeProperties(
model,
SketchUpApi.EdgeUsageType.Shared, // or 'Shared'
{ hidden: true },
);
}, 'Hide all shared edges');

Rendering Option Enums Moved onto SketchUpApi:

SketchUpApi.RenderingOptions is deprecated. Each of its enums is now exposed directly on SketchUpApi, and accessing one through RenderingOptions logs a one-time deprecation warning to the console. The old path remains functional until the next major version.

Migration Example:

// Old way (deprecated)
await model.updateRenderingOptions({
EdgeType: SketchUpApi.RenderingOptions.EdgeType.Sketchy,
});
// New way (SDK 2.33.0)
await model.updateRenderingOptions({
EdgeType: SketchUpApi.EdgeType.Sketchy,
});
  • Renamed Extension class to UI.
  • Exposed .getModalInput function on the UI class.

Changed the build artifact name and npm package name to sketchup-js-api.

Continuing the get* naming convention adopted in 2.30.0, extending it to file and image export methods.

Every rename below is backwards compatible: the previous name remains available as a deprecated alias and will continue to work until the next major version. Deprecated aliases log a one-time deprecation warning to the console.

export* Methods Renamed with a get Prefix:

Migration Example:

// Old way (deprecated)
const skpDataUrl = await model.export();
const skmDataUrl = await material.export();
const textureDataUrl = await material.texture.export('png', { colorize: true });
// New way (SDK 2.30.3)
const skpDataUrl = await model.getSkp();
const skmDataUrl = await material.getSkm();
const textureDataUrl = await material.texture.getImage('png', { colorize: true });

Added a renderOptions parameter to SketchupView.getScreenshot() for controlling additional rendering behavior such as shadows, annotations, watermarks, and axes in exported screenshots.

Note: renderOptions is not available when connected to the Ruby version of the JSA backend. Use Platform.supportsScreenshotRenderOptions to check for support.

Aligning naming of classes and methods with their Ruby equivalent. Improving consistency of function names.

Every rename below is backwards compatible: the previous name remains available as a deprecated alias and will continue to work until the next major version. Deprecated aliases log a one-time deprecation warning to the console. See Naming and Versioning for the conventions being adopted.

Renamed Classes and Types:

stream* Methods Renamed to observe*:

Streaming methods have been renamed to observe* and now return an ObserverHandle.

Async Accessors Renamed with a get Prefix:

Asynchronous accessors now consistently start with get.

SketchupOperation Method Renaming:

Operation methods now follow the convention that creation methods start with create, removal methods start with remove, resource loading methods start with load, and component-definition methods are prefixed definition* (previously component*) and instance methods instance*. The most notable renames:

  • Creation: createFace, createFaceFromEdges, createEdge, createGroup, createInstance, createMaterial, createDefinition, createImage, createScene, createTag, createTagFolder, createSectionPlane, createSnap, createText, createArc, createCircle, createCurve, createNgon, createDimensionLinear, createDimensionRadial, createDuplicateStyle
  • Removal: removeStyle, removeMaterial, removeDefinition, removeScene, removeTag, removeTagFromFolder, removeTagFolder
  • Purge: purgeUnusedStyles, purgeUnusedMaterials, purgeUnusedDefinitions
  • Resource loading (async): loadMaterial, loadDefinition
  • Component definitions: definitionSetName, definitionSetDescription, definitionSetToFaceCamera, definitionSetToCutOpening, definitionSetNoScaleMask, definitionSetShadowsToFaceSun, definitionSetToSnapTo, definitionAddClassification, definitionRemoveClassification, definitionSetClassificationValue
  • Component instances: instanceSetName, instanceSetLocked, instanceSetTransformation, instanceApplyTransformation, instanceSetGluedTo
  • Styles: setSelectedStyle, updateSelectedStyle

Migration Example:

// Old way (deprecated)
const definition: Component = await model.components().then((c) => c[0]);
const materials = await model.materials();
const handle = model.streamSelectionMetadata((meta) => console.log(meta));
operation.faceCreate(entities, points);
operation.componentSetName(definition, 'Chair');
// New way (SDK 2.30.0)
const definition: ComponentDefinition = await model
.getDefinitions()
.then((d) => d[0]);
const materials = await model.getMaterials();
const handle: ObserverHandle = model.observeSelectionMetadata((meta) =>
console.log(meta)
);
operation.createFace(entities, points);
operation.definitionSetName(definition, 'Chair');

Implemented unified, type-safe entity filtering system that replaces type-specific query methods with a single, powerful Entities API.

The new entity filtering system provides compile-time type inference, better composability, and a more consistent API surface. All existing type-specific methods (.faces(), .groups(), .edges(), etc.) are deprecated but remain functional with backward compatibility.

New Unified Entity API:

New Filter Types:

  • EntityFilter - Union type for all entity filters
  • EntityTypeFilter - Filter by entity type(s) using string literals or enums
  • EntityAttributeFilter - Filter by attribute dictionary values
  • EntityTagFilter - Filter by tag assignment
  • EntityVisibilityFilter - Filter by visibility state
  • EntityAndFilter, EntityOrFilter, EntityNotFilter - Logical filter combinators

Type-Safe Queries:

  • EntityQuery<Filter> - Standard query interface with type inference
  • EntityTypeForFilter<Filter, Default> - Utility type that infers return types from filters at compile-time

New Scene Methods:

Enhanced Methods with Filter Support:

Deprecated Methods:

The following type-specific query methods are deprecated in favor of the unified entities.get() API:

On SketchupModel: groups(), faces(), edges(), componentInstances(), images(), dimensionLinears(), dimensionRadials(), curves(), constructionPoints(), constructionLines(), snaps(), texts(), sectionPlanes(), activeSectionPlanes(), getActiveSectionPlane()

On Component: groups(), faces(), edges(), componentInstances(), images(), dimensionLinears(), dimensionRadials(), curves(), constructionPoints(), constructionLines(), snaps(), texts(), sectionPlanes(), curves(), getActiveSectionPlane()

On Group: groups(), faces(), edges(), componentInstances(), images(), dimensionLinears(), dimensionRadials(), curves(), constructionPoints(), constructionLines(), snaps(), texts(), sectionPlanes()

On Scene: activeSectionPlanes() - use getActiveSectionPlanes() instead

Migration Example:

// Old way (deprecated)
const faces = await model.faces();
const redGroups = await model.groups({
filter: 'attribute',
dictionaryName: 'my_dict',
attributeName: 'color',
attributeValue: 'red'
});
// New way (SDK 2.29.0)
const faces = await model.entities.get({ filterBy: { types: ['Face'] } });
const redGroups = await model.entities.get({
filterBy: {
and: [
{ types: ['Group'] },
{
attribute: {
dictionaryName: 'my_dict',
attributeName: 'color',
attributeValue: 'red'
}
}
]
}
});
// Type inference works automatically
const edges = await model.entities.get({ filterBy: { types: ['Edge'] } });
// TypeScript knows `edges` is `Edge[]`

Added API version reporting to improve diagnostics.

New Properties:

  • apiVersion - Returns the version of the JavaScript API

Implemented Coordinate Reference System (CRS) Location API for geospatial mapping of SketchUp models to real-world coordinates.

The CRS Location API enables integration between SketchUp’s local coordinate system and standardized geospatial coordinate reference systems (typically EPSG codes). This feature supports bidirectional coordinate transformations, allowing models to be positioned accurately in real-world GIS workflows and mapping applications.

Feature Availability: SketchUp Desktop version 27 or later

CRS Location API:

Implemented event-driven communication for bidirectional messaging between SketchUp and the client.

Event System:

  • Send Event - Send custom events from client to SketchUp
  • On Event - Register handlers for events from SketchUp

Web Extension Support:

  • Extension - Handle commands triggered by Web Extension menus and toolbars
  • su:command event - Automatically sent when Web Extension commands are triggered

New Types:

  • EventHandle - Handle returned by event registration, can be used to remove the handler
  • EventHandler<T> - Type for event handler functions
  • CommandEvent - Event payload for Web Extension command events

Size Reduction:

  • Internal refactors reduced bundle size by 4KB
  • Changed the target es version to ES2022 reduced bundle size by 40KB

Bug Fix

On ipad we cannot reliably detect when a page is being unloaded, this resulted in “already.connected” errors occurring. To address this there is a new connection option replaceAlreadyConnected which defaults to True. When true this will disconnect and reconnect upon receiving this error.

Implemented Styles support

Style Queries:

Style Operations:

New Types:

  • Style - Represents a SketchUp style with rendering option settings
  • StyleRef - Reference to a style entity
  • ActiveStyleInfo - Metadata about the currently active style
  • SelectedStyle - Selected style with its active state information
  • SketchupStyleLoadError - Error type for style loading failures

Enhanced Face capabilities with UV queries, area calculations, connectivity queries, and texture management

Face UV Queries:

Face Area Queries:

Face Connectivity:

Face Operations:

Geometry Utilities:

New Types:

  • FacePointClassification enum - Classification for points relative to faces
  • UVRequest / UVResponse - Types for UV coordinate queries
  • UVTileResponse - Type for UV tile information

Internal improvements for vertex encoding

When both client and server support protocol version 1.21.1, vertices are now encoded using persistent IDs instead of entity IDs. This provides more stable vertex references across model operations.

The Vertex.sketchupId property now returns a persistent ID when supported by both client and server.

  • Reduce warnings when updating extensions that use the Ruby Library.

Bug Fix

When SketchUp reloads extensions it is unsafe to blindly require “tempfile”. Instead only load it if the class does not exist.

Implemented Rendering Options support

Model Rendering Options:

Scene Rendering Options:

Implemented Curve, ArcCurve, and Dimension entity support

Curve Creation:

ArcCurve Creation:

Dimension (General):

Linear Dimensions:

Radial Dimensions:

Improved Type Safety:

  • Enhanced entityForRef to provide proper type inference for all entity references
  • Added EntityFor<T> utility type for mapping entity references to their concrete types

Deprecated Methods:

The following type-specific *ForRef methods are now deprecated in favor of the unified, type-safe entityForRef method:

  • componentForRef - use entityForRef instead
  • componentInstanceForRef - use entityForRef instead
  • edgeForRef - use entityForRef instead
  • faceForRef - use entityForRef instead
  • groupForRef - use entityForRef instead
  • imageForRef - use entityForRef instead
  • materialForRef - use entityForRef instead
  • sceneForRef - use entityForRef instead
  • tagForRef - use entityForRef instead
  • tagFolderForRef - use entityForRef instead
  • drawingElementForRef - use entityForRef instead
  • sectionPlaneForRef - use entityForRef instead
  • constructionPointForRef - use entityForRef instead
  • constructionLineForRef - use entityForRef instead
  • snapForRef - use entityForRef instead
  • textForRef - use entityForRef instead

These methods will continue to work but may be removed in a future major version.

Fix a crash on Windows related to open file handles while an application is running.

Implemented Text entity support

See example

Reduced visible surface area of SDK in pure JavaScript hiding details such as the protocol and communicator.

Marked some variables with an _ prefix, these will be available for debugging purposes but in general should not be accessed.

Image Entity support:

Entity glueing support:

Model improvements:

Improved type safety:

  • All entity reference classes now include a type field for better type discrimination

Implemented Snap support

See example

New Tools API for monitoring and controlling SketchUp tools:

Component instance change streaming:

Improve SDK around options by providing typed wrappers for the known providers.

Breaking Changes

  • Removed model.options.custom this was never intended to be exposed in SU and nothing should be using it.

Bugfix: Removed loading section_plane_queries.rb which doesn’t exist

  • Transform the planeLike to plane before reaching backend
  • Expose Color class via SketchUpApi.Color
  • Fix initialization order bugs in certain environments
  • Allow for the communicator type to be set explicitly
  • Added SketchUpApi export from index.ts so that consuming applications written in typescript no longer need to reach into window.Sketchup
  • Added window.SketchUpApi for pure JS application usage
  • Added a deprecation warning when accessing window.Sketchup or (Sketchup) from the browser

Implemented selection support

Implemented transform by ID support

Bug Fixes

  • Setting the shadow info “useSunForAllShading” on 2026.1 was not working due to a decoding issue.
  • Add better debug information when entity building fails with errors inside of SketchUp.
  • Fixed a bug when trying to delete an attribute dictionary that does not exist on an entity that has never had any attributes. As a workaround clients should do the following for older backends.
// check that the parent dictionary has subdictionaries before trying to delete
if (operation.model.attributes.getAttributesOfDictionary('dictionary')) {
operation.modelDeleteAttributes(['dictionary', 'subdictionary']);
}

Implemented texture support

Implemented export and import for materials

Implemented PBR property support

Added support for transparent operations

Implemented model exporting as skp file see Example

Implemented scene supported

Added optional scene parameter to all Shadow Info operations

Implemented Camera

Implemented View Screenshot

Implemented View Info

Implemented construction points

Implemented construction lines

Implemented component loading

Implemented IFC classification

Hosted static resources

  • BugFix Fix a crash when deleting an attribute from a dictionary that does not exists
  • Resolve queued connection requests on error
  • Replace use of deprecated window.onunload with beforeunload
  • First public revision available on sketchup-virtual-npm