Tectly Editor Widget

The widget embeds our floor plan editor into your web page so your users can review and edit the geometry Tectly extracts. It renders as an iframe inside a container of your choice on your site.

The widget loads a single Tectly project. Whether to upload a floor plan to that project from your backend before mounting is up to you — users will land directly on the editor. Otherwise the widget prompts the user to upload a plan themselves.

Installation

npm i @tectly/widget

Or via CDN — the package exposes a TectlyWidget global:

<script src="https://unpkg.com/@tectly/widget"></script>

Quick start

<div id="tectly-container"></div>

import { TectlyWidget } from "@tectly/widget";

const widget = new TectlyWidget({ token: "my-project-scoped-session-token" });

widget.start("#tectly-container");

Authentication

The widget authenticates with a project-scoped session token that you can issue from your backend.

curl -X POST https://platform.tectly.com/projects/{id}/issue-session-token \
    -H "Authorization: Bearer <your-account-token>"

WARNING

Never pass your account bearer token to the client. It can access every project in your account. Always issue a project-scoped session token server-side.

Integration flow

Configuration

Option	Type	Required	Description
token	string	Yes	A project-scoped session token. See Authentication.
environmentUrl	string	No	The Tectly environment. Defaults to https://sandbox.platform.tectly.com. Use https://platform.tectly.com for production.
origin	string	No	Override the parent origin used to validate postMessage traffic. Defaults to window.location.origin; only set this if the parent's effective origin differs (e.g. nested iframes or a reverse proxy).
options	object	No	Editor customization. color sets the main accent color (hex string). hideHeaderActions: true hides the Save and Export buttons in the editor header (useful when you provide your own controls via save() and your backend).

API

Method	Description
start(container: string | HTMLElement)	Mount the editor iframe into container, given as a CSS selector or DOM element. Calling start() twice on the same instance is a no-op and logs a warning.
destroy()	Remove the iframe, tear down the message bridge, and clear all event listeners.
save()	Ask the editor to persist the current floor plan. Emits saved on success or error on failure; only call once connected has fired.
getData()	Get the current data from the floor plan editor. The result is normalized and can be traversed beginning at the floors.
on(event, callback) / off(event, callback)	Subscribe or unsubscribe from events.

You can mount multiple widget instances on the same page — each owns its own iframe and message channel.

Events

Event	Payload	Description
connected	—	The editor has loaded and is ready to receive commands.
saved	—	Emitted after save() completes successfully. The widget surfaces save errors in its UI.
error	{ name: string; message: string }	Emitted when the editor encounters an error.

widget.on("connected", () => console.log("Editor ready."));
widget.on("saved", () => console.log("Floor plan saved."));
widget.on("error", (error) => console.error(`[Tectly]: ${error}`));

Framework examples

import { TectlyWidget } from "@tectly/widget";

const widget = new TectlyWidget({
  token: "my-project-scoped-session-token",
});

widget.start("#tectly-container");

document
  .querySelector("#save-button")
  ?.addEventListener("click", () => widget.save());