Embedding
Embedding lets you place a Topologis view inside your own website.
Embeds use the same view model as shared links, but the delivery method is different. Instead of opening a hosted /view/{viewId} page, your site loads a script for a specific view and mounts the map into a container element on your page.
How embeds work
Embedding always starts from a view.
The embed runtime loads that view’s current saved settings, including its layers, filter behavior, style choices, tooltip settings, and embed layout options. If you need to control what the embedded map looks like first, configure the view before you copy the embed code. For the full view model, see Views.
Copy the embed script
Open the view you want to embed and use the Embed section in the view settings. Topologis generates a script tag for that view that looks like this:
<script src="EDGE_URL/embed/VIEW_ID/topologis.js" defer></script>Use the exact script the editor gives you. It has the right view ID baked in and points to the embed runtime that fetches the published map.
Add the container element
After the script, add the container element that will hold the map:
<div id="VIEW_ID"></div>The container’s id must match the view ID, since the runtime looks for that exact element before it mounts. If the container is missing, or the id doesn’t match, the embed has nowhere to render and you’ll see an empty space where the map should be.
Choose an embed size
Embed sizing lives on the view, not in the script. The Embed section gives you three aspect ratios to pick from: Landscape, Square, and Portrait.
Pick based on where the map will live on the page. Landscape is the right default for a hero-style or full-width section. Square works in card layouts and grid tiles. Portrait is unusual but right when the map sits next to a tall column of text.
Aspect ratio and fill options
The same Embed section has two fill toggles, Fill width and Fill height, that decide how the map sits in its container.
If exactly one is on, the aspect ratio you picked above takes over the other dimension. If both are on, the aspect ratio is ignored and the map fills the container in both directions.
Fill width is the safe default for most pages. Only turn Fill height on as well when the surrounding layout actually gives the map a known height. Otherwise the embed can collapse to nothing.
Allowed hosts
Embeds are protected by an allowed-host check.
Before an embed is allowed to load, Topologis matches the requesting page’s host against the list in the dashboard Allowed Hosts page. If the host isn’t on the list, the embed script shows a Topologis error panel instead of the map.
The check is strict: it matches by hostname only, ignores port numbers, and doesn’t expand to other subdomains. Treat example.com and www.example.com as different hosts and add both if you serve the page from either.
Testing your embed
After adding the script, container, and allowed host entry, load the page where the map should appear.
Check these basics first:
- The embedded view is the one you intended to publish
- The script tag and container both use the same view ID
- The current site host has been added to the allowed host list
- The view has been saved after any recent changes
If those conditions are correct, the map should load into the container on your page.
Troubleshooting embeds
If the embed does not work, start with the most likely failure points.
If you see a Topologis error message inside the embed area, the host check is the first thing to verify. If the page shows no map, confirm that the container exists and that its id exactly matches the view ID from the generated embed code.
If the map loads but looks wrong, the issue is usually in the view rather than the embed code. Recheck the view’s enabled layers, style choices, filters, camera, and embed size settings. If you are comparing a shared link and an embed, remember that both are driven by the same underlying view, while host restrictions only apply to the embed path.