JavaScript

mount() is the framework-independent entry point. You provide a container and a starting intent; the SDK creates the map surface inside it, completes the handshake, and resolves with the handle.

npm install @waylocate/embed

Examples use a demonstration campus. Every snippet on this site addresses ucba, a publicly available campus with the building muntz-hall and the room 170. Substitute your own campus slug once you have one. Slugs for your campus are listed in your Waylocate console, and the addressing rules are in the reference grammar.

Mounting

<div id="map" style="width: 100%; height: 600px"></div>

import { mount } from "@waylocate/embed";

const map = await mount({
  container: "#map",
  campus: "ucba",
  building: "muntz-hall",
  room: "170",
});

container accepts either an element or a CSS selector. The element the SDK creates fills it completely, so give the container the dimensions you want.

Options

Option	Type	Meaning
container	HTMLElement | string	Element or selector to mount into. Required.
campus	string	Campus slug. Required.
building	string	Building to open on load
room	string	Room to select on load, bare or building-qualified. Requires building.
ui	string | string[]	Chrome flags
from	string	Route origin, as a reference
to	string	Route destination, as a reference
nav	"preview" | "live"	Directions mode
permissions	{ geolocation?: boolean }	Capabilities granted to the map surface
className	string	Applied to the element the SDK creates
style	Partial<CSSStyleDeclaration>	Applied to the element the SDK creates
label	string	Accessible name. Defaults to "Campus map".
mapOrigin	string	Origin serving the map. Defaults to https://waylocate.com
timeoutMs	number	How long to wait for the map to answer on connect
commandTimeoutMs	number	Per-command timeout after connecting
signal	AbortSignal	Aborts the mount and removes anything it created

Using the handle

await map.camera.flyTo({ zoom: 18, bearing: 45, duration: 800 });

const stopListening = map.on("selection.changed", (selection, meta) => {
  if (meta.source === "user") openPanel(selection.room);
});

The full surface is documented in controlling the map.

Cancelling and cleaning up

Pass an AbortSignal when the map might become unnecessary before it finishes connecting, which is common in single-page applications where a route can change mid-load. Aborting rejects the pending mount() and removes the partially created surface.

const controller = new AbortController();

mount({ container: "#map", campus: "ucba", signal: controller.signal })
  .then((map) => useMap(map))
  .catch((error) => {
    if (error.code !== "DESTROYED") report(error);
  });

// Later, if the view is discarded:
controller.abort();

Once mounted, map.destroy() performs the same teardown: listeners are detached, in-flight commands reject, and the surface is removed from your container.

Failure

mount() rejects with a WaylocateError. The two you should expect are TIMEOUT, when the map never answered, and INVALID_OPTIONS, when the container selector matched nothing or the campus was empty.

import { mount, WaylocateError } from "@waylocate/embed";

try {
  const map = await mount({ container: "#map", campus: "ucba" });
} catch (error) {
  if (error instanceof WaylocateError && error.code === "TIMEOUT") {
    showFallbackLink();
  }
}

The full list is in errors.

Without a bundler

The package ships a browser build that defines a single global. Everything on this page works identically through it.

<div id="map" style="width: 100%; height: 600px"></div>

<script src="https://unpkg.com/@waylocate/embed"></script>
<script>
  WaylocateEmbed.mount({ container: "#map", campus: "ucba" }).then((map) => {
    map.on("selection.changed", (selection, meta) => {
      if (meta.source === "user") console.log(selection.room);
    });
  });
</script>

The global exposes mount, connect, buildEmbedUrl, and WaylocateError. It does not expose protocol internals.

Pin a version in production. An unpinned CDN URL resolves to the newest release, which is convenient for a prototype and a liability for a deployed page:

<script src="https://unpkg.com/@waylocate/[email protected]/dist/waylocate-embed.global.js"></script>

Next

• Controlling the map for the command surface.
• Existing iframe if your markup already contains the element.