Embedding and sizing
Every Vibemap embed is a page under https://web.vibemap.com/embed/. Put it on your site one of two ways:
- The loader script (recommended). It creates the iframe, sizes it to its content, and handles full-screen panels, Back, scroll position, your page title and structured data.
- A plain iframe. You write the sizing code yourself, and the rest only if you need it.
Use web.vibemap.com. vibemap.com/embed/... does not serve embeds.
The loader script
<div id="vibemap-embed"></div>
<script
src="https://web.vibemap.com/load.js"
data-iframe-el="vibemap-embed"
data-resize="true"
data-url="https://web.vibemap.com/embed/grid?slug=san-francisco&type=places&shownAtStart=12"
></script>
The script puts an iframe inside the element named by data-iframe-el. Give each embed on a page its own container id and its own script tag.
Loader attributes
| Attribute | Default | Effect |
|---|---|---|
data-iframe-el | required | id of the element the iframe goes in. |
data-url | required | The embed URL. Older add-event snippets use data-embed-type instead. |
data-resize | off | true sizes the iframe to its content. It also turns on full-screen panels, scroll-to-top, scroll restore on Back and structured data. Without it the loader still handles Back, the page title, the form DOM events and parameters from your page's URL. |
data-height | 600px | Starting height, or the fixed height without data-resize. A bare number is pixels; any CSS length works. |
data-forward-params | - | Comma-separated parameters to copy from your page's URL onto the embed URL, such as slug,type on a detail page. |
data-clean-url | true | false keeps copied parameters in your address bar. See Parameters from your page's URL. |
data-keep-params | slug | Copied parameters that stay in your address bar. |
data-back-url or data-parent-url | - | Where Back goes when there is no history to go back to. |
data-scroll-to-top-offset | 0 | Pixels to leave above the embed when it scrolls into view. Use your sticky header's height. |
data-auto-load-more | off | true loads more grid cards as the visitor nears the bottom of the embed, instead of waiting for Load More. Needs data-resize. |
data-init-mode | dom | load waits for your page's load event before creating the iframe. |
data-init-delay | 0 | Milliseconds to wait before creating the iframe. |
data-no-title | off | true stops the loader changing your page title and og:/twitter: tags. |
data-no-canonical | off | true stops the loader rewriting your canonical link. |
data-no-host-url | off | true stops the loader adding host_url. |
data-no-schema | off | true stops the loader copying the embed's structured data into your page. |
data-no-sitemap | off | true stops the loader adding a hidden list of item links to your page. |
data-embed-type | - | Older snippets: add-event with no data-url builds the Add Event Form URL from data-param-<name> attributes. |
A plain iframe
This iframe sizes itself to the embed and supports the map and full-screen panels:
<iframe
id="vibemap-embed"
src="https://web.vibemap.com/embed/grid?slug=san-francisco&type=places&shownAtStart=12"
title="Places in San Francisco"
width="100%"
height="800"
style="display: block; border: 0;"
allow="geolocation"
></iframe>
<script>
(function () {
var frame = document.getElementById("vibemap-embed");
var locked = null;
window.addEventListener("message", function (event) {
var msg = event.data;
if (event.source !== frame.contentWindow || !msg) return;
if (msg.type === "resize" && msg.height && !locked) {
frame.style.height = msg.height + "px";
} else if (msg.type === "get-viewport") {
frame.contentWindow.postMessage({
type: "viewport-dimensions",
width: window.innerWidth,
height: window.innerHeight,
scrollY: window.scrollY
}, "*");
} else if (msg.type === "lock-viewport") {
if (msg.lock && !locked) {
locked = { height: frame.style.height, scrollY: window.scrollY };
frame.style.position = "fixed";
frame.style.top = frame.style.left = "0";
frame.style.width = "100vw";
frame.style.height = "100vh";
frame.style.zIndex = "9999";
document.body.style.overflow = "hidden";
} else if (!msg.lock && locked) {
frame.style.position = frame.style.top = frame.style.left = frame.style.zIndex = "";
frame.style.width = "100%";
frame.style.height = locked.height;
document.body.style.overflow = "";
window.scrollTo(0, locked.scrollY);
locked = null;
}
}
});
})();
</script>
A plain iframe does not get scroll restore, your page title or structured data. Add host_url yourself. On a single embed, answer the Back messages or add backButton=false; see Back.
With no script at all, the iframe keeps its height and grid views scroll inside it.
Recommended iframe attributes
| Attribute | Value | Why |
|---|---|---|
src | https://web.vibemap.com/embed/<route>?... | The only host that serves embeds. |
title | What the embed shows | Screen readers announce it. |
width | 100% | Embeds fill their container and adapt to its width. |
height | A starting height in pixels | Used until the first resize message, or always if you don't handle it. |
style | display: block; border: 0; | Removes the default border and the gap under inline frames. |
allow | geolocation | Lets the map ask for the visitor's location. The loader sets it too. |
Don't add sandbox. The embed needs scripts, storage, forms and links that open in your page.
Automatic height
Embeds talk to your page with window.postMessage. Each message is an object with a type.
- When it loads, the embed posts
iframe-ready. The loader ignoresresizeuntil then. - Grid, carousel, map-grid and single embeds then post
get-viewport. Reply withviewport-dimensionsand your window's inner size. A map view uses it to fill 90% of your window's height, unlessmapHeightfixes the map's size, and to choose its narrow layout on windows up to 1024 pixels wide. - The embed posts
resizewith its content height whenever that height changes. Set the iframe to that many pixels.
Messages from the embed
| Message | Payload | Your page should |
|---|---|---|
iframe-ready | none | Start handling the messages below. |
get-viewport | none | Reply with viewport-dimensions. |
resize | { embedId, height } | Set the iframe height to height pixels. Ignore it while a full-screen panel is open. |
lock-viewport | { lock } | true: pin the iframe over the whole window and stop your page scrolling. false: put the iframe back and restore the scroll position. |
vibemap-scroll-to-top | { offset } | If the iframe's top is above offset pixels from the top of the window, scroll so it rests there. |
vibemap-embed-config | { scrollToTopOffset } | Keep the offset for vibemap-scroll-to-top messages that carry none. |
vibemap-save-scroll | { key } | Store your page's scroll position under key. |
vibemap-restore-scroll | { key } | Once the iframe is tall enough, scroll back to the position stored under key, then delete it. |
vibemap-can-go-back-query | { fallbackUrl } | Reply with vibemap-can-go-back-result. |
vibemap-navigate-back | { fallbackUrl } | Go back in your page's history, or to fallbackUrl if there is none. |
request-load-more-listener | none | Optional: post vibemap-load-more when the visitor scrolls near the iframe's bottom. |
vibemap-title | { title, description, image } | Optional: use them for your page title and share tags. |
vibemap-item | { slug, itemType } | Optional: keep your URL's slug on the item shown. |
vibemap-jsonld | { schemas } | Optional: add each string to your <head> as a <script type="application/ld+json">. |
Messages to the embed
| Message | Payload | Effect |
|---|---|---|
viewport-dimensions | { width, height, scrollY } | Answers get-viewport. |
vibemap-can-go-back-result | { canGoBack } | Answers vibemap-can-go-back-query. false hides Back. With no answer in half a second, the button shows. |
vibemap-load-more | none | Loads the next set of grid cards. |
Full-screen panels
Photo lightboxes and the phone filter panel cover the whole screen. In an iframe that has grown to fit a long grid, a panel pinned to the frame would sit far below the visitor's view, so the embed posts lock-viewport with lock: true. The loader then pins the iframe over the window and stops your page scrolling. On lock: false it restores the iframe's size and your scroll position.
Scroll to top and Back
Scroll to top
When a place or event opens inside the embed, it posts vibemap-scroll-to-top so the item's title is in view. The loader scrolls only when the embed's top is already above the resting line, so an embed at the top of a fresh page doesn't move. If your page has a sticky header, set scrollToTopOffset=<header height> on the embed URL, or data-scroll-to-top-offset on the script. Grids, carousels and maps pass their scrollToTopOffset to the loader when they load, so it still applies after a card opens.
Back
The single embed shows Back only when there is somewhere to go. The button goes back inside the frame when the visitor got there inside the embed. Otherwise it asks your page with vibemap-navigate-back. The loader then goes back in your page's history when the visitor arrived from your own site, or opens the first of these that is set:
backUrlorparentUrlin your page's URL.data-back-urlordata-parent-urlon the script.- The theme's events page.
- The last page on your site the visitor came from.
If none is set, it goes back in history anyway.
Hide the button with backButton=false on the embed URL or your page's URL.
Scroll restore
When a grid or map card opens inside the embed, the embed posts vibemap-save-scroll. When the visitor comes back, it posts vibemap-restore-scroll, and the loader returns your page to the saved position as the grid regrows. If that takes more than a moment, the loader covers the page with Taking you back to where you were… and gives up after 12 seconds.
host_url
The loader adds host_url, your page's address without its query string or hash, to grid, carousel, map-grid and single embed URLs and to Vibemap short links. The embed uses it as its canonical URL, so search engines credit your page rather than web.vibemap.com. A single embed also uses it in its structured data, and prefers the theme's detail-page address when the theme sets one.
The loader never replaces a host_url already in data-url. In a plain iframe, add it yourself, URL-encoded:
https://web.vibemap.com/embed/grid?slug=san-francisco&type=places&host_url=https%3A%2F%2Fyour-site.com%2Fplaces%2F
Parameters from your page's URL
When your page's URL has any of these parameters, the loader copies them onto the embed URL: list, boundary, organization, cities, theme, latitude, lat, longitude, lng, radius, distance, dist, backButton, backUrl and parentUrl. Name others with data-forward-params. A parameter already in data-url always wins. The loader does not copy disclaimer, so a link to your page can't change or hide your event notice; to change the notice on an event page of your own site, put disclaimer in that page's data-url.
The loader then removes the copied parameters from your address bar, except those in data-keep-params, and remembers them for a refresh in the same tab. data-clean-url="false" turns this off.
Your page's title and structured data
The loader changes your page only where noted, and each change has an opt-out in Loader attributes:
- Title and share tags. A single embed reports its item. The loader sets your tab title to
Item name — Your page title, keeps it if your page later overwrites it, and setsog:andtwitter:title, description and image. On a page whose URL hasslugorname, it sets an early title from that value. - Analytics. With that title, the loader sends one
page_viewto your Google Analytics or Google Tag Manager, so reports show the item name.data-no-titledoes not stop this. - Canonical link. On a page whose URL has
slugorid, the loader points your canonical link at that item's address, unless the link already names an item. - Structured data. With
data-resize, the loader copies the embed's schema.org JSON-LD into your<head>, and for lists adds a visually hidden list of links to each item.
These run in the browser, so crawlers that don't run JavaScript never see them.
Embed events
Embeds also report what visitors do:
| Message | Sent by | Payload |
|---|---|---|
card-clicked | carousel, map-grid | { embedId, data }: the item |
marker-clicked | map-grid | { embedId, data }: the item |
view-changed | grid, map-grid | { embedId, view } |
filters-changed | grid, map-grid | { embedId, data }: the filter change |
polygon-selected | map-grid | { embedId, data: { polygonIndex } }, null when cleared |
event-form-submitted, event-form-message | add-event | See Add Event Form |
place-form-submitted, place-form-message | add-place | See Add Place Form |
The loader also fires the form messages as DOM events on your container: vibemap:event-submitted, vibemap:place-submitted and vibemap:form-message.
<script>
window.addEventListener("message", (event) => {
if (event.data?.embedId !== "map-grid") return;
if (event.data.type === "card-clicked") {
console.log("Card:", event.data.data);
}
});
</script>
Messages come from https://web.vibemap.com, or from https://api.vibemap.com when the embed URL is a Vibemap short link. Check embedId and type, or compare event.source with your iframe's contentWindow, rather than event.origin.