Skip to main content

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​

AttributeDefaultEffect
data-iframe-elrequiredid of the element the iframe goes in.
data-urlrequiredThe embed URL. Older add-event snippets use data-embed-type instead.
data-resizeofftrue 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-height600pxStarting 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-urltruefalse keeps copied parameters in your address bar. See Parameters from your page's URL.
data-keep-paramsslugCopied 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-offset0Pixels to leave above the embed when it scrolls into view. Use your sticky header's height.
data-auto-load-moreofftrue loads more grid cards as the visitor nears the bottom of the embed, instead of waiting for Load More. Needs data-resize.
data-init-modedomload waits for your page's load event before creating the iframe.
data-init-delay0Milliseconds to wait before creating the iframe.
data-no-titleofftrue stops the loader changing your page title and og:/twitter: tags.
data-no-canonicalofftrue stops the loader rewriting your canonical link.
data-no-host-urlofftrue stops the loader adding host_url.
data-no-schemaofftrue stops the loader copying the embed's structured data into your page.
data-no-sitemapofftrue 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.

AttributeValueWhy
srchttps://web.vibemap.com/embed/<route>?...The only host that serves embeds.
titleWhat the embed showsScreen readers announce it.
width100%Embeds fill their container and adapt to its width.
heightA starting height in pixelsUsed until the first resize message, or always if you don't handle it.
styledisplay: block; border: 0;Removes the default border and the gap under inline frames.
allowgeolocationLets 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.

  1. When it loads, the embed posts iframe-ready. The loader ignores resize until then.
  2. Grid, carousel, map-grid and single embeds then post get-viewport. Reply with viewport-dimensions and your window's inner size. A map view uses it to fill 90% of your window's height, unless mapHeight fixes the map's size, and to choose its narrow layout on windows up to 1024 pixels wide.
  3. The embed posts resize with its content height whenever that height changes. Set the iframe to that many pixels.

Messages from the embed​

MessagePayloadYour page should
iframe-readynoneStart handling the messages below.
get-viewportnoneReply 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-listenernoneOptional: 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​

MessagePayloadEffect
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-morenoneLoads 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:

  1. backUrl or parentUrl in your page's URL.
  2. data-back-url or data-parent-url on the script.
  3. The theme's events page.
  4. 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 sets og: and twitter: title, description and image. On a page whose URL has slug or name, it sets an early title from that value.
  • Analytics. With that title, the loader sends one page_view to your Google Analytics or Google Tag Manager, so reports show the item name. data-no-title does not stop this.
  • Canonical link. On a page whose URL has slug or id, 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:

MessageSent byPayload
card-clickedcarousel, map-grid{ embedId, data }: the item
marker-clickedmap-grid{ embedId, data }: the item
view-changedgrid, map-grid{ embedId, view }
filters-changedgrid, map-grid{ embedId, data }: the filter change
polygon-selectedmap-grid{ embedId, data: { polygonIndex } }, null when cleared
event-form-submitted, event-form-messageadd-eventSee Add Event Form
place-form-submitted, place-form-messageadd-placeSee 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.