Capabilities
If you’re evaluating the SketchUp JavaScript API or migrating from the Ruby API, this page summarizes what the JSA supports today, what’s coming, and what’s fundamentally different.
The JSA covers the majority of core modeling operations — creating and querying geometry, managing materials, working with scenes and cameras, and reading/writing attributes. For the most common workflows (reading model data, creating drawing elements, managing materials and tags), you’ll find near-complete coverage. Where gaps exist, they tend to be in advanced features like boolean operations, overlays, or low-level view drawing.
Reading the Model
Section titled “Reading the Model”The JSA provides full access to the model tree. You can query entities at any level — from the root model down through groups and components — and access their properties, geometry data, and relationships.
- Traverse the model hierarchy: model → entities → groups/components → nested entities
- Query all drawing element types: edges, faces, curves, groups, component instances, images, construction geometry, dimensions, text, section planes, and snaps
- Access entity properties: geometry (vertices, normals, planes), visibility, tags, materials
- Find entities by ID (persistent or entity ID)
- Get model metadata: name, GUID, bounds, number of faces
- Access the active path for editing within groups/components
- Stream real-time selection changes and tool state
**Key JSA classes: ** SketchupModel, Face, Edge, ComponentDefinition, ComponentInstance, Group
Writing the Model
Section titled “Writing the Model”All model modifications happen through operations — atomic units of work that support undo/redo. The JSA can create almost every type of drawing element.
- Create edges, faces, curves, arcs, circles, and n-gons
- Create groups, component instances, construction lines/points, section planes, dimensions, text, images, and snaps
- Modify properties: transform, material, tag, visibility, shadows
- Delete/erase drawing elements
- Bulk transformations on multiple elements
- Entity Builder for high-performance batch creation (replacement for Ruby’s
add_faces_from_mesh) - PushPull faces, FollowMe, weld edges into curves
- Load components from URLs, purge unused definitions
- Manage scenes: create, update, reorder, set properties
**Key JSA classes: ** SketchupOperation, EntitiesBuilder
Attributes
Section titled “Attributes”Full support for reading and writing attribute dictionaries on any entity that supports them. This is essential for extensions that store custom data on model entities.
- Get/set/delete individual attributes by dictionary path and key
- Enumerate all dictionaries and their key-value pairs
- Delete entire attribute dictionaries
- Works on: model, drawing elements, materials, scenes, tags, styles, textures, and vertices
**Key JSA classes: ** Attributes, AttributeDictionary
UI and Extension Integration
Section titled “UI and Extension Integration”The JSA takes a fundamentally different approach to UI compared to the Ruby API. Rather than programmatically creating menus and toolbars at runtime, JSA extensions declare their UI through a manifest file.
- Manifest-based UI: Menus, toolbars, context menus, and window configuration are declared in
manifest.json - Window types: headless, floating, modal or sidebar.
- Commands: Define once, reference from menus, toolbars, and context menus
- Tools: The JSA supports programmatic tool interaction — clear the active tool, place components, and stream tool state changes
- Selection: Full read/write access to the selection, including streaming changes
- View: Access camera, screenshots, view info, and rendering options
More info on the manifest system is coming soon. See the Manifest page for current documentation.
Where it differs from Ruby: Ruby’s UI::HtmlDialog, UI::Toolbar, and UI.menu are replaced entirely by the
manifest system. JSA extensions run in iframes and communicate via message passing rather than direct API calls.
Geometry Utilities
Section titled “Geometry Utilities”The JSA provides geometry primitives comparable to Ruby’s Geom module. Points and vectors are immutable (unlike
Ruby’s mutable versions), which is more natural in JavaScript.
- Point3d: addition, subtraction, distance, equality comparison
- Vector3d: dot product, cross product, normalize, reverse, parallel/perpendicular checks, length, axes
- Transformation: rotation, scaling, translation, axes, interpolation, inverse, composition — all factory methods supported
- BoundingBox: add, contains, center, dimensions, intersect
Not yet available: Point2d (basic ops only), Vector2d, Transformation2d, PolygonMesh, UTM/LatLong conversions, and several Point3d utility methods (distance_to_line, project_to_plane, etc.)
**Key JSA classes: ** Point3d, Vector3d, Transformation, BoundingBox
Not Yet Supported
Section titled “Not Yet Supported”These are the major areas where the JSA does not yet have coverage:
- Tools — We have prototyped first-class Tools support (custom tools that interact with the viewport, handle mouse events, and draw overlays), but it is not yet available in the production version of the JSA. You can add basic tool icons to toolbars that trigger events via the manifest system.
- Observers/Callbacks — Most entity-level observers are not implemented. The JSA provides streaming APIs for selection, tools, camera, and options changes, but per-entity observation is not available. You can manually handle most model changes with streamActiveModel. See also streamSelectionMetadata, streamCamera, streamToolChanges, streamOptionsChanges, streamRenderingOptions, streamActivePath, streamViewInfo, and streamInstanceChanges.
- Boolean Operations — union, subtract, trim, intersect, outer_shell on groups/components
- Overlays — The overlay system is not yet exposed
- Environments — HDRI environment support is planned for a future release
- 3D Text —
add_3d_textis not yet available - View Drawing —
draw,draw2d,draw_line, etc. are unlikely due to the async architecture - PickHelper / InputPoint — Hit-testing and inference are under investigation
- File System Access — The JSA runs in a sandboxed web context. Export operations return data URLs rather than writing to disk.
- Line Styles — Not yet exposed
- PolygonMesh — Use EntitiesBuilder instead
Reference: Ruby API Class Coverage
Section titled “Reference: Ruby API Class Coverage”The tables below show the status of each Ruby API class in the JSA. Status is based on the proportion of meaningful
methods (excluding Ruby-only constructs like valid?, inspect, to_s) that have a JSA equivalent.
Drawing Elements
Section titled “Drawing Elements”| Ruby Class | Status | JSA Equivalent | Notes |
|---|---|---|---|
| ArcCurve | ✅ Supported | ArcCurve | Full geometric properties (center, radius, angles, normal) |
| ComponentInstance | ✅ Supported | ComponentInstance | Transform, properties, lock supported; booleans and explode are future |
| ConstructionLine | ✅ Supported | ConstructionLine | Full coverage |
| ConstructionPoint | ✅ Supported | ConstructionPoint | Full coverage |
| Curve | ✅ Supported | Curve | All core methods available |
| DimensionLinear | ✅ Supported | DimensionLinear | Full coverage of all dimension properties |
| DimensionRadial | ✅ Supported | DimensionRadial | Full coverage |
| Edge | ✅ Supported | Edge | Core properties supported; graph-traversal methods (faces, common_face) are future |
| Face | ✅ Supported | Face | Excellent coverage including pushpull, followme, UVs, texture positioning |
| Group | ✅ Supported | Group | Core ops work; boolean operations and explode are future |
| Image | ✅ Supported | ImageEntity | Dimensions, transform, origin, export all work |
| SectionPlane | ✅ Supported | SectionPlane | Activate, name, plane, symbol all work |
| Snap | ✅ Supported | Snap | Position, direction, up vector |
| Text | ✅ Supported | Text | All properties and leader types |
Model and Collections
Section titled “Model and Collections”| Ruby Class | Status | JSA Equivalent | Notes |
|---|---|---|---|
| Classifications | ✅ Supported | — | Load/unload schemas, get/set classification values |
| ComponentDefinition | 🟡 Partial | ComponentDefinition | Properties and entities work; save_as, boolean ops are future |
| DefinitionList | ✅ Supported | — | Accessed via model.components(); create, load, remove, purge all work |
| Entities | ✅ Supported | — | No direct class; accessed via model/group/component .entities() |
| EntitiesBuilder | ✅ Supported | EntitiesBuilder | High-performance batch creation |
| Layers | ✅ Supported | TagManager | Create, remove, organize into folders; purge is future |
| Materials | ✅ Supported | — | Full CRUD via model.materials() and operations |
| Model | 🟡 Partial | SketchupModel | Core queries and operations work; advanced features (raytest, geo, import/export) are future |
| Pages | ✅ Supported | — | Create, navigate, and modify scenes; accessed via model.view.scenes() |
| Selection | ✅ Supported | Selection | Add, remove, toggle, clear, invert, stream changes |
| Styles | ✅ Supported | — | Load from URL, remove, purge unused, get/set active style, update selected style. Style name and description are read/write. |
Materials and Textures
Section titled “Materials and Textures”| Ruby Class | Status | JSA Equivalent | Notes |
|---|---|---|---|
| Color | 🟡 Partial | Color | RGBA read works; immutable in JSA; utility methods (blend, to_a) are future, though you can easily do these in pure JS |
| Material | ✅ Supported | Material | Full PBR support: color, texture, metallic, roughness, normal, AO. Reading/writing UVs is also supported. |
| Texture | 🟡 Partial | Texture | Properties accessible; export as data URL; size manipulation is future |
Attributes
Section titled “Attributes”| Ruby Class | Status | JSA Equivalent | Notes |
|---|---|---|---|
| AttributeDictionaries | ✅ Supported | Attributes | Full enumeration and access |
| AttributeDictionary | ✅ Supported | AttributeDictionary | Full CRUD on keys and values |
View and Camera
Section titled “View and Camera”| Ruby Class | Status | JSA Equivalent | Notes |
|---|---|---|---|
| Camera | ✅ Supported | Camera | All orientation and lens properties |
| Page | ✅ Supported | Scene | Camera, properties, visibility, rendering options, animation settings |
| RenderingOptions | ✅ Supported | RenderingOptions | Read and update rendering options; stream changes |
| ShadowInfo | ✅ Supported | ShadowInfo | Fully typed object with property accessors and setters |
| View | 🟡 Partial | — | Camera get/set, screenshots, viewport info work; drawing methods and pick helpers are not available |
Tags (Layers)
Section titled “Tags (Layers)”| Ruby Class | Status | JSA Equivalent | Notes |
|---|---|---|---|
| Layer | 🟡 Partial | Tag | Name, color, visibility; line styles and page behavior are future |
| LayerFolder | ✅ Supported | TagFolder | Create, rename, move, visibility, enumerate children |
Geometry Utilities
Section titled “Geometry Utilities”| Ruby Class | Status | JSA Equivalent | Notes |
|---|---|---|---|
| BoundingBox | ✅ Supported | BoundingBox | add, contains, center, dimensions, intersect |
| Point2d | 🟡 Partial | — | Basic arithmetic only; most methods are future |
| Point3d | 🟡 Partial | Point3d | Core ops (add, subtract, distance, equality); immutable; projection methods are future |
| PolygonMesh | ❌ Not yet | — | Use EntitiesBuilder instead |
| Transformation | ✅ Supported | Transformation | All factory methods (rotation, scaling, translation, axes, interpolate); immutable |
| Transformation2d | ❌ Not yet | — | Planned for a future release |
| Vector2d | ❌ Not yet | — | Planned for a future release |
| Vector3d | ✅ Supported | Vector3d | dot, cross, normalize, parallel, perpendicular, length, axes, reverse |
Not Applicable in JSA
Section titled “Not Applicable in JSA”These Ruby classes don’t have (or need) a JSA equivalent:
| Ruby Class | Reason |
|---|---|
| Importer | No file system access in the JSA sandbox |
| Set | JavaScript has native Set |
| Skp | No file system access in the JSA sandbox |