Integration

There are four ways to embed a Waylocate map. They are not four products. They are four ways of doing the same thing, and the first three all end up holding the same WaylocateMap handle described in how the embed works.

Pick one based on how much of the element lifecycle you want to own.

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.

Compare

React

You render a component. The SDK owns the element inside it, and props keep the map in sync as your state changes.

import { CampusMap } from "@waylocate/embed/react";

<CampusMap
  campus="ucba"
  building="muntz-hall"
  room="170"
  className="h-[600px] w-full"
  onSelectionChange={(selection, meta) => {
    if (meta.source === "user") openPanel(selection.room);
  }}
/>

Nothing in your JSX names a transport. If the way the map is delivered changes, this code does not.

Full guide

JavaScript

You hand over a container. The SDK creates the element, connects, and gives you the handle.

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

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

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

Works in any framework, and from a <script> tag with no bundler.

Full guide

Existing iframe

Your markup already contains the <iframe>, perhaps because a template or CMS produced it. You build the URL and attach to the element you already have.

import { buildEmbedUrl, connect } from "@waylocate/embed";

const iframe = document.getElementById("map");
iframe.src = buildEmbedUrl({ campus: "ucba", building: "muntz-hall" });

const map = await connect({ iframe });

From connect() onward the handle is identical to the other two.

Full guide

Static iframe

No JavaScript at all. The URL sets the initial view, and the visitor takes it from there.

<iframe
  src="https://waylocate.com/ucba/muntz-hall/170?embed=1"
  style="width: 100%; height: 600px; border: 0"
  title="Campus map"
  allow="clipboard-write; geolocation"
></iframe>

There is no handle, so your page cannot command the map or observe it.

Full guide

Which to use

	Ships an element	Needs a bundler	Gives you a handle
React	The SDK does	Usually	Yes, plus declarative props
JavaScript	The SDK does	No	Yes
Existing iframe	You do	No	Yes
Static iframe	You do	No	No

Two questions settle it in practice.

Do you need to command the map or react to it? If not, use the static iframe. It has no JavaScript to load, no failure modes, and no upgrade path to worry about.

Does the element already exist in markup you do not control? If so, use the existing-iframe path. Otherwise let the SDK create it, because that is the one choice that insulates you from changes to how the map is delivered.

Moving between them

The paths are compatible by design. A static iframe becomes a controllable one by adding a host parameter to its URL and calling connect() on the element. An existing-iframe integration becomes a mount() integration by deleting the element from your markup and passing its parent as the container. The commands and events do not change in either direction.

Next

Once you have a handle, controlling the map covers what you can do with it.