Skip to main content

Vibemap Embeds

Vibemap provides several embeddable components that can be integrated into any website via iframe. Each embed type is designed for specific use cases and can be extensively customized via URL parameters.

Available Embeds​

EmbedDescriptionBest For
Map-GridCombined map and grid views with toggleFull-featured place/event discovery
CarouselHorizontal scrolling cardsFeatured content showcase
GridFilterable grid layoutContent browsing and filtering

Common Features​

All embeds support:

  • Theming - Customizable appearance via the theme parameter
  • Filtering - Filter by vibes, categories, tags, and search terms
  • Content Types - Display places or events with type=places or type=events
  • Featured Content - Show only featured items with featured=true
  • PostMessage Events - Communication with parent window for integration
  • Responsive Design - Adapts to container size

Quick Start​

1. Choose Your Embed Type​

  • Use Map-Grid for a full discovery experience with map and list views
  • Use Carousel for showcasing featured content in a compact format
  • Use Grid for a filterable browsing experience

2. Add Required Parameters​

All embeds require either a slug (boundary) or list parameter:

/embed/map-grid?slug=austin # Boundary-based
/embed/carousel?list=my-list # List-based

3. Customize with URL Parameters​

Add optional parameters to customize the experience:

/embed/map-grid?slug=austin&type=events&showVibeFilter=true&theme=dark

Use featured=true to filter and display only featured places or events:

/embed/carousel?slug=austin&type=events&featured=true
/embed/grid?slug=sf&type=places&featured=true
/embed/map-grid?slug=denver&featured=true

When featured=true is set, only items marked as featured in the Vibemap system will be displayed. When omitted or set to false, all items are shown.

Embedding Methods​

Basic iframe​

<iframe
src="https://vibemap.com/embed/map-grid?slug=austin"
title="Map of things to do in Austin"
width="100%"
height="600"
frameborder="0"
style="border: none;"
></iframe>

A bare iframe gives your page none of the embed's structured data: search engines credit it to the embed's own address. Use the script below to bring it onto your page. Give a bare iframe a title that says what it shows; screen readers announce the frame by it.

Auto-Resizing Script​

For dynamic height adjustment:

<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/map-grid?slug=austin"
></script>

Leave out data-resize (and set data-height="800") for a fixed-height box. Either way the script copies the embed's structured data into your page.

Loading and Page Layout​

The script holds the embed's space on your page from the moment it runs, at the height the embed opens at, so the content below stays put when the embed appears. With data-resize="true" the embed then grows or shrinks to fit what it shows.

An embed in the first screenful loads straight away. One further down the page loads as the visitor scrolls toward it, so it no longer competes with your page's own content for the network.

Script attributeWhat it does
data-heightThe height the embed opens at, and keeps without data-resize. A bare number means pixels; any CSS length works (80vh). Defaults to 600px, or 850px for an embed that opens on the calendar view.
data-min-heightA floor the embed never shrinks below, even with data-resize.
data-aspect-ratioShapes the box instead of fixing its height, e.g. 16/9. Without data-height the embed fills the box.
data-loadingeager or lazy overrides the choice between loading at once and loading on scroll.
data-init-mode="visible"Creates the embed only when it comes within 200px of the screen; until then the page holds its space. Use it for embeds far down long pages.
<div id="vibemap-embed"></div>
<script
src="https://web.vibemap.com/load.js"
data-iframe-el="vibemap-embed"
data-url="https://web.vibemap.com/embed/grid?list=downtown-events"
data-height="900"
data-init-mode="visible"
></script>

For a bare iframe, set height and, if it sits below the first screenful, loading="lazy" yourself.

Frame Title​

Screen readers announce an embed by its iframe's title. The script names the frame after what it shows: the list's name, or the event or place a detail view shows, as soon as the embed reports it. Until then the title says what kind of embed it is, such as "Events", "Map of places" or "Event details". To choose the name yourself, set data-iframe-title; the script then never changes it.

<div id="vibemap-embed"></div>
<script
src="https://web.vibemap.com/load.js"
data-iframe-el="vibemap-embed"
data-url="https://web.vibemap.com/embed/grid?list=downtown-events"
data-iframe-title="Things to do downtown"
></script>

Structured Data on Your Page​

Every script embed copies the embed's schema.org JSON-LD (an Event or LocalBusiness per item, plus an ItemList for list embeds) into your page's <head>, so search engines that run JavaScript credit the events to your page.

  • It follows the visitor. When a card opens a detail view inside the embed, the list's markup is replaced by the item's, or removed if the new view has none.

  • No duplicates. Two embeds showing the same item add one copy; a re-run of the snippet or a reload of the embed replaces its markup instead of adding more.

  • Only from Vibemap. The script accepts markup only from the embed's own address and vibemap.com. A third-party page opened inside the embed cannot write into yours. The same rule covers the tab title, description and address-bar updates a detail view sends.

  • Your own markup is never touched. Only the tags the script added (data-vibemap-schema) are replaced or removed, including on destroy().

  • Credited to the item's address on your site. On a single-item page such as /event-details/?slug=jazz-night, an event the embed would otherwise credit to the bare /event-details/ page is credited to /event-details/?slug=jazz-night instead, and follows the visitor to related items. A theme whose cards open your own item pages already credits those.

  • Your organization as publisher. When the embed sits on your own site (the site your theme's events page or Open to Page links point to), the markup describes that page: a WebPage with the list (or the item) as its main entity, pointing at your Organization and WebSite by the @ids Yoast and Rank Math use (https://your-site/#organization, #website). It never defines those nodes, a page name or breadcrumbs itself, so your SEO plugin's own stay as they are. Two list embeds on one page each keep their own list.

  • Recurring events as a series and as events. A recurring event's page carries its EventSeries plus an Event for each of its next ten dates, each linked to the series by superEvent; a date's own page carries that date's Event.

  • Times with their zone. Event start and end times carry the venue's UTC offset (2026-11-14T20:00:00-08:00), the same instant the page shows; all-day events give only the date.

Crawlers that do not run JavaScript never see this markup. On WordPress, the Vibemap plugin writes it into your page's HTML on the server instead.

Clean Host-Page URLs (on by default, opt out with data-clean-url="false")​

When a card in a list embed opens a customer-hosted detail page, the link carries scope params (type, list, boundary, theme, …) so the detail embed's similar-items carousel stays scoped to the originating list. That leaves a long query string in the visitor's address bar.

load.js cleans this up by default: after forwarding the consumed params onto the iframe, it strips them from the host's address bar using history.replaceState. No attribute is required — the snippet below is the standard one:

<div id="vibemap-single"></div>
<script
src="https://web.vibemap.com/load.js"
data-iframe-el="vibemap-single"
data-resize="true"
data-url="https://web.vibemap.com/embed/single?theme=my-theme"
data-forward-params="slug,type"
></script>

A visitor arriving at /event-details/?slug=jazz-night&type=event&list=my-list&boundary=my-city&theme=my-theme ends up with /event-details/?slug=jazz-night in the address bar — the embed still receives the full scope.

Notes:

  • Opt out with data-clean-url="false" — use this only when the host page itself reads those params, or when you want the full URL to stay shareable.
  • Only params load.js consumed are removed. The host page's own params (utm_*, gclid, …) and the #hash are never touched.
  • data-keep-params (default "slug") is a comma-separated list of consumed params that should stay in the URL. slug stays by default because it is the page's identity — a shared or bookmarked link needs it.
  • Stripped values are stashed in sessionStorage (keyed to the page path), so a refresh keeps the same scope. On a shared clean link the stash is absent and the embed falls back to the data-url defaults — put everything static (e.g. theme, type=place on a place detail page) in data-url so shared links render fully.
  • Cleaning the host bar never breaks the onward journey: when a visitor clicks a card in the detail page's similar-items carousel, the embed rebuilds that card's link with the scope params (list/boundary/theme) itself, so the next page stays branded and list-scoped even though the host URL is clean.
  • The host URL's slug stays accurate as the visitor navigates. Similar-items navigation happens inside the iframe, so the embed reports each item's slug back to load.js, which updates ?slug= in place (via replaceState). A shared or refreshed link therefore always points at the item currently shown — not the one the visitor first landed on. Only params already in the host URL are touched (so a clean URL keeps just slug; a full URL also tracks type).

Host-Page Takeover Opt-Outs (data-no-*)​

To make a customer's own page rank and share well, load.js writes a few things into the host document on behalf of the embed. Every one of them is on by default and can be switched off individually — set the attribute to the exact string "true"; anything else (including omitting it) leaves the behaviour on.

AttributeTurns off
data-no-title="true"All host page-metadata writes: document.title, the MutationObserver that defends it against the host's own late title writes, the <meta name="description">, and the og:/twitter: title/description/image tags.
data-no-canonical="true"The <link rel="canonical"> on single-item host pages: the per-item one for a page carrying ?slug= or ?id=, and the self-referencing one a page with no canonical gets (its own URL minus embed, scope and tracking params such as embedded, theme and utm_*).
data-no-schema="true"The structured data copied from the embed into the host <head> (see Structured Data on Your Page). Use it when your page already publishes markup for the same events.
data-no-host-url="true"Appending host_url= to the embed URL, which lets the embed credit the customer's page: Google indexes the embed as part of that page, and the structured data names it.

The flags are per script tag, not per page: one block can opt out while the customer's other blocks on the same page keep the default behaviour.

The embed trusts host_url only when its site (the same host, its www. twin or a subdomain) appears in the Events Link or Open to Page of the embed's theme or its list's theme, both set in the Hub. Any other host_url gets noindex, follow, indexifembedded and no canonical, so a copied embed link can't point search engines at someone else's site. Google still indexes the embed as part of the page that frames it. An embed opened with no host_url stays indexable.

data-no-sitemap is retired and ignored. Older versions of the script added a hidden list of links to each item; search engines treat hidden links shipped in a widget as spam, so the script no longer adds it. Item URLs still reach search engines through the structured data.

When to use data-no-title​

Leave it off unless your page manages its own metadata. Use it when the host is a single-page app (Remix, Next, Nuxt, …) that commits a <title> and og: tags per route: load.js is injected once and its shared registry then lives for the rest of the browser session, so a title or og tag it writes on one route is still there several client-side navigations later.

<div id="vibemap-single"></div>
<script
src="https://web.vibemap.com/load.js"
data-iframe-el="vibemap-single"
data-resize="true"
data-url="https://web.vibemap.com/embed/single?theme=my-theme"
data-no-title="true"
></script>

Two things are deliberately not affected:

  • The corrected analytics pageview still fires. Without it the host's GA hit carries whatever generic title the template rendered (often the raw slug); load.js still forwards one corrected page_view per embed, still preferring the exact title the embed reports once hydrated over the slug-derived guess. Only the DOM writes are suppressed. To stop the pageview, turn analytics off (below).
  • The <link rel="canonical"> and JSON-LD have their own flags above. data-no-title covers page metadata for humans and unfurlers; those cover structured data for crawlers.

Turning analytics off​

Add analytics=off to the embed URL, or data-analytics="off" to the script tag. Either one stops the embed's own Vibemap analytics and the corrected page_view that load.js sends to your page's Google Analytics or Tag Manager. false, 0 and no work too. With analytics on, the embed's clicks, filters and shares reach your own GA4 or Tag Manager: see Embed Analytics in Your Google Analytics.

<script
src="https://web.vibemap.com/load.js"
data-iframe-el="vibemap-single"
data-url="https://web.vibemap.com/embed/single?theme=my-theme"
data-forward-params="slug,type"
data-analytics="off"
></script>

Single-page-app hosts: call destroy() on unmount​

An SPA that re-renders its DOM on client-side navigation destroys the embed's container without telling load.js. Call the registry's teardown from your unmount path so listeners, timers and injected nodes go with it:

useEffect(() => () => window.VibemapEmbed?.destroy("vibemap-single"), [])

destroy() hands the tab title back to the host only if an embed actually took it over — a grid embed, a form embed or one running with data-no-title leaves document.title exactly as it found it, so unmounting cannot clobber a title your router has already committed for the next route.

Search Engines and AI Crawlers​

The cards are in the page's HTML. Grid, Map & Grid and Carousel embeds send their first page of cards with the page itself, before any JavaScript runs: each card's link, title, date, venue and image. A Map & Grid that opens on its map sends the cards of the map's side list, and the map itself loads in the browser. A boundary grid (?boundary=) or a location grid (latitude, longitude, dist) does the same, with the list of items as structured data, as list embeds already had. Crawlers that skip JavaScript, AI crawlers among them, read your events and places, and visitors see cards at once rather than a loading shimmer. The page also carries one heading, the list's name (a location grid's: the area its items share), for screen readers, with each card titled one level beneath it; it shows on screen when you add ?showTitle=true.

What the page sends is what the embed shows. A list narrowed with strictFilter=true and tags, categories or vibes, or with editorial_categories or featured=true, asks the API for the matching items only. Taxonomy params also preselect filter chips, which narrow the cards again in the browser, unless strictFilter=true comes with filterBehavior=open or a param names several terms. The page sends the cards that categories and vibes chips keep, and its structured data lists only them; a calendar-first embed paints its month from the same rows. A tags chip depends on a tag list only the browser loads, so the page sends no cards and lists no items for it rather than items the chip will hide. If the Vibemap API is slow, the page stops waiting after a few seconds and the embed loads its items in the browser. An embed of an event, place or list that doesn't exist or isn't public still answers with its own "not found", marked noindex, follow with no canonical.

So is the item on a detail page. The single-item embed (/embed/single) sends the event or place with the page: its name as the heading, the date as a machine-readable date, the venue's address, the description, the main photo and the ticket and website links. The embed's own title and description are the item's. The pages a card opens inside the embed (/event/<slug>, /place/<slug>) arrive the same way, and one for an item that was removed or isn't approved answers "not found" (404) instead of an empty page. A recurring event's page of dates (/event-series/<id>), which its "more dates" badge opens, sends its title, description and a linked card per upcoming date, and names the event's own page as its canonical.

Calendar, RSS and Markdown copies. Every events list has a calendar and an RSS feed, and every event and place a Markdown copy for AI assistants: see Feeds and Markdown.

Google credits your page. When the script frames an embed on your site, it tells Google, and only Google, noindex, indexifembedded: Google indexes the embed's events and places as part of your page instead of ranking the embed's own address. A framed embed names no canonical: beside that noindex, a canonical pointing at your page could lead Google to drop your page too. The structured data the script copies onto your page credits it instead. Other search engines and AI crawlers don't support indexifembedded, so for them the embed stays indexable at its own address. An embed opened on its own (a short link, say) stays indexable everywhere, and a single-item embed then names the item's page as its canonical: yours when your theme's Open to Page sends cards to your site.

A sitemap of your item pages. Each list has one at https://web.vibemap.com/sitemaps/lists/<list-slug>.xml, with every item in the list, not just the first page, at the same URLs the cards link to. Add it to your site's robots.txt so search engines accept it for your domain:

Sitemap: https://web.vibemap.com/sitemaps/lists/events-downtown-san-jose.xml

The URLs are your own pages when your theme's Open to Page sends cards to your site; otherwise they are Vibemap's.

Empty detail pages stay out of search. A single-item page shows no item when it is opened without one (your /event-details/ page itself, with no ?slug= or ?id= in its address or the embed's data-url) or when its item was deleted or unpublished. load.js marks such a page noindex, follow, so search engines drop it but still follow its links. A deleted item's mark lifts once the visitor opens a real item in the embed. It works whatever you named the page, in a frame or in inline mode, and needs no setup. It never applies when the page's address or data-url names a published item, nor to list embeds. Google reads it after running JavaScript. If your bare page shows a default item, opt out with data-no-robots="true".

The Embed SEO companion for WordPress. A small plugin that prints the embed's structured data and its items into your page's own HTML, and gives each item detail page (/event-details/?slug=…) its own canonical URL, title and description, all before any JavaScript runs. That is how crawlers that skip JavaScript read your events and places on your domain. The items show as a plain listing in the embed's spot until the live embed replaces it, and the embed's structured data replaces the companion's once it arrives (in a frame or in inline mode), so nothing appears twice. Ask your Vibemap contact to set it up.

Two things only your site can fix: a detail-page template whose SEO plugin prints one slug-less canonical for every item (the companion fixes this on WordPress), and a firewall that blocks AI crawlers (check Cloudflare's "Block AI bots" setting and your robots.txt).

PostMessage Communication​

Embeds tell the page that holds them what the visitor does with postMessage. Every message carries type; the embed-specific ones also carry embedId ("grid", "map-grid", "carousel", "add-event", "venue-events"...).

typeSent byWhenPayload
view-changedgrid, map-gridThe visitor switches viewview: "map", "grid", "list" or "calendar"
filters-changedgrid, map-gridA filter or search changesdata: the changed filters
card-clickedmap-grid (cards in the map view), carouselA card is clickeddata: the item
marker-clickedmap-gridA map marker is clickeddata: the item
polygon-selectedmap-gridA boundary polygon is picked or cleareddata.polygonIndex (null when cleared)
event-form-submittedadd-event, venue-eventsAn event is submitteddata: the submission result
resizeevery embedThe content height changesheight in pixels
vibemap-analyticsevery embedAny tracked interactionevent and properties: see Embed Analytics

Grid cards are ordinary links to the item's page, so the grid embed sends no card-clicked: listen for its navigation instead. With the script embed, load.js handles resize for you and re-dispatches event-form-submitted on the container as a vibemap:event-submitted DOM event.

Embeds are served from https://web.vibemap.com, and list short links from https://api.vibemap.com, so check the origin before trusting a message:

window.addEventListener("message", (event) => {
if (!/^https:\/\/(web|api)\.vibemap\.com$/.test(event.origin)) return;

switch (event.data?.type) {
case "card-clicked":
console.log("Item clicked:", event.data.data);
break;
case "view-changed":
console.log("View changed:", event.data.view);
break;
case "filters-changed":
console.log("Filters updated:", event.data.data);
break;
}
});

Data Sources​

Boundary-Based (slug)​

Uses a geographic boundary to fetch places/events:

?slug=austin
?slug=san-francisco
?slug=denver

The boundary determines:

  • Geographic area for content
  • Initial map viewport
  • Boundary polygon display

List-Based (list)​

Uses a curated list for content and configuration:

?list=best-coffee-austin
?list=weekend-events-sf

Lists can provide:

  • Pre-defined filters
  • Custom theme settings
  • Specific item selection

Parameter Precedence​

URL parameters always override defaults:

  1. URL Parameters (highest priority)
  2. List Configuration (if using list)
  3. Theme Defaults
  4. Built-in Defaults (lowest priority)

This allows you to use list-based configuration while overriding specific settings via URL.