@gospace-ai/floorplan

A lightweight JavaScript/TypeScript SDK for embedding the gospace Floorplan (hosted at https://floorplan.gospace.app) inside your app.
It handles secure messaging to the hosted floorplan, passes configuration (location/layer/space selections), and emits events (e.g., when a user clicks a space).

---

Features

- Framework‑agnostic — Works with Nuxt, Vue, React, Next, Svelte, or plain HTML/JS.
- Hosted UI — Renders an interactive floorplan from https://floorplan.gospace.app.
- Typed API — First‑class TypeScript types.
- Secure messaging — Uses postMessage to exchange only the data the iframe needs.
- Event API — Subscribe to floorplan events (e.g., SPACE_CLICKED).

---

Installation

$3

``bash
npm install @gospace-ai/floorplan


or


yarn add @gospace-ai/floorplan
pnpm add @gospace-ai/floorplan
`

$3

Use a public npm CDN such as jsDelivr or unpkg:

`html








`

The UMD build exposes a global: gospaceFloorplan.FloorplanSDK.

---

Security & Tokens

- The SDK requires a short‑lived access_token (not an API key).
- Generate tokens server‑side (e.g., via the gospace API SDK/back end) and pass them to your frontend.
- Do not embed API keys in client code or expose them to the browser.

---

Content Security Policy (CSP)

Allow the floorplan host to be framed by your app. You can add either an HTTP header or a meta tag:

HTTP header (recommended):

`
Content-Security-Policy: frame-ancestors 'self' https://floorplan.gospace.app;
`

Meta tag (fallback):

`html
http-equiv="Content-Security-Policy"
content="frame-ancestors 'self' https://floorplan.gospace.app"
/>
`

---

Quick Start

$3

`html





http-equiv="Content-Security-Policy"
content="frame-ancestors 'self' https://floorplan.gospace.app"
/>











`

---

$3

`ts
import { FloorplanSDK } from "@gospace-ai/floorplan";

const ACCESS_TOKEN = "";

const sdk = new FloorplanSDK({
key: "floorplan-container", // id of a DOM element you control
access_token: ACCESS_TOKEN, // short-lived token from your server
location_id: "location_123",
// Optional:
// layer_id: "layer_abc",
// zone_id: "zone_1234",
// room_id: "room_5678",
// spaces: ["space_1", "space_2"],
// url: "https://floorplan.gospace.app",
// class_name: "my-iframe",
// title: "Office floorplan",
// dark_mode: true
});

sdk.on("SPACE_CLICKED", ({ space_id }) => {
// Handle the user clicking a specific space on the floorplan
console.log("Space clicked:", space_id);
});

sdk.init();
`

CommonJS:

`js
const { FloorplanSDK } = require("@gospace-ai/floorplan");

const sdk = new FloorplanSDK({
/ ...options... /
});
sdk.on("SPACE_CLICKED", ({ space_id }) => console.log(space_id));
sdk.init();
`

---

$3

`tsx
import { useEffect, useRef } from "react";
import { FloorplanSDK } from "@gospace-ai/floorplan";

export default function FloorplanEmbed() {
const ref = useRef(null);

useEffect(() => {
if (!ref.current) return;

const sdk = new FloorplanSDK({
key: "floorplan-container",
access_token: "",
location_id: "location_123",
});

sdk.on("SPACE_CLICKED", ({ space_id }) => {
console.log("Space clicked:", space_id);
});

sdk.init();

// If the SDK exposes a cleanup method in future, call it here.
// return () => sdk.destroy?.();
}, []);

return (
id="floorplan-container"
ref={ref}
style={{ width: "100%", height: 640 }}
/>
);
}
`

---

$3

`vue



`

---

Configuration

| Property | Type | Description | Required |
| -------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------| -------- |
| url | string | Full iframe URL (default: https://floorplan.gospace.app) | No |
| key | string | ID of the container element that will host the iframe | Yes |
| access_token | string | Short‑lived access token for authentication (generate server‑side) | Yes |
| location_id | string | Location ID for the floorplan | Yes |
| layer_id | string | Optional layer ID | No |
| zone_id | string | Optional zone ID, allows to highlight and zoom into the given zone 🚧 (beta) | No |
| room_id | string | Optional room ID, allows to zoom into the given room 🚧 (beta) | No |
| spaces | (string \| SpaceCustomization)[] | Optional array of space IDs or customization objects to highlight | No |
| class_name | string | Optional CSS class for the iframe | No |
| title | string | Optional accessibility title (applied to the iframe) | No |
| dark_mode | boolean | Optional dark mode flag | No |
| events | FloorPlanEvents[] | Optional allows to receive floorplan events for an entity, if not provides only SPACE_CLICKED will be received 🚧 (beta) | No |
| entity_events| FloorPlanEntityType[] | Optional allows to receive floorplan events for provided entity (depends on existence of events) 🚧 (beta) | No |
| custom_loader| string | Optional allows inject custom HTML loader | No |
| zoom | string | Optional allows to auto zoom into painted spaces | No |
| primary_color| string | Optional allows to provide line color (hex color) | No |


> Note: The container element referenced by key must exist and have a visible height/width; otherwise, the iframe may appear collapsed.

---

Types


`typescript
type SpaceCustomization = {
id: string; // Space identifier
color?: string; // Optional fill color (hex)
opacity?: number; // Optional opacity value (0-1)
border?: {
color: string; // Border color (hex)
lineWidth?: number; // Optional border width in pixels
};
};

type FloorPlanEvents =
| 'click'
| 'right-click'
| 'double-click'
| 'hover'
| 'blur'
| 'plan-right-click'
| 'outside-click'

/**
* Can be used to place custom tooltips, context menus etc., values are relative to the iframe position and window position
*/
export type Center = {
x: number;
y: number;
relativeX?: number;
relativeY?: number;
};

/**
* Floor Plan events (advanced)
*/
type FloorPlanEntityType = 'SPACE' | 'WALL_PERIMETER' | 'ROOM' | 'AREA';

interface FloorPlanEntity = {}> {
id: string;
type: FloorPlanEntityType;
center?: Center;
properties?: T & { locationId: string; layerId: string };
}

/**
* @important Metadata is on build progress to provide only useful information
*/
type SpaceMetadata = unknown;
type RoomMetadata = unknown;
type WallPerimeterMetadata = unknown;

type FloorPlanEntityMetadata = SpaceMetadata | RoomMetadata | WallPerimeterMetadata;

type FloorPlanEvent = {
event: FloorPlanEvents;
id: string; // This is entity event ID could be Space, Room etc
metadata: FloorPlanEntity
}

type SpaceClickedEvent = {
space_id: string;
};
`

Events

The SDK emits events via sdk.on(event, handler).

Currently documented:

`ts
// Usage
sdk.on("SPACE_CLICKED", ({ space_id }: SpaceClickedEvent) => {
console.log("Space clicked:", space_id);
});

// or

sdk.on('FLOOR_PLAN_ENTITY', (event: FloorPlanEvent) => {
console.log('Event type:', event.type);
console.log('Event entity id:', event.id);
console.log('Event entity type:', event.metadata.type);
})
`
sdk

> Additional events may be introduced over time. Check the SDK release notes/changelog for newly available events.

---

Styling & Layout Tips

- The SDK injects an