Single URL Parameters

The /embed/single endpoint renders a single place or event profile page (SinglePlaceLayout or SingleEventLayout).

Base URL

/embed/single?type=<place|event>&slug=<slug-or-id>

Required Parameters

Parameter	Type	Default	Description
type	string	"event"	"place" or "event"
slug / id	string	-	Slug or UUID of the place/event to display. The component auto-detects a UUID (fetch by id) vs. a slug (fetch by slug). slug is the canonical name; id is accepted as an alias.

Note: load.js forwards the parent page's slug + type automatically via data-forward-params="slug,type", so most embeds only set theme explicitly. The older identifier param is not read — use slug.

Clean host URLs (default on): load.js strips every param it consumed from the host page's address bar (via history.replaceState) after forwarding them onto the iframe — leaving e.g. /event-details/?slug=my-event. This is the default; opt out with data-clean-url="false". data-keep-params (default "slug") controls which consumed params stay visible; stripped values are stashed in sessionStorage so refresh keeps the scope. Shared clean links fall back to the data-url defaults, so hardcode static config (theme, and type=place on place-only pages — type defaults to event) in data-url. Clicking a similar-items card carries scope forward independently: getItemUrl rebuilds the card link with list/boundary/theme (see SingleClient.tsx → CardCarousel), so the onward page stays scoped even with a clean host bar. The embed also reports its current slug to load.js (useEmbedItemIdentity → vibemap-item message), which keeps the host URL's ?slug= pointed at the item actually shown as you navigate between related items — so the clean URL stays shareable.

---

Display Parameters

Parameter	Type	Default	Description
theme / themeName	string	-	Theme slug for styling
showUpdates	boolean	true	Show offer/update badges on places. Pass showUpdates=false to hide them.
smartCrop	boolean	true	ImageKit AI smart crop (fo-auto) + focal point. Set false for deterministic center crop with contain-fit letterbox for extreme aspect ratios.

smartCrop behavior

• smartCrop=true (default) — State 1, the smart crop pipeline:
  • ImageKit URLs use fo-auto in the transform (server-side smart crop).
  • Non-ImageKit URLs use CSS object-fit: cover with object-position from the stored focal point (falls back to center center).
  • Images always fill the container.
• smartCrop=false — State 2, no smart crop:
  • ImageKit delivers native aspect ratio bytes (no h- / no fo- in the URL).
  • Normal-aspect images (ratio 0.8–2.2) use plain object-fit: cover with center center.
  • Extreme-aspect images (portrait < 0.8 or panoramic > 2.2) use contain-fit letterbox: the image is shown whole with object-fit: contain and a blurred copy fills the dead space behind it.

Note that the site-wide hero image grid (HeroImageGrid) ignores the smartCrop prop and always cover-crops using focal point (or center). The smartCrop param affects Card, CardCarousel, and EventsGrid renderings — e.g. the similar-items carousel on the single page.

---

Similar-Items Scope

The single page renders "Similar Places" / "Similar Events" carousels. By default these are scoped globally, but you can constrain them to the same geography as the grid/map the visitor came from. When any of these params are present, similar items are restricted to that scope; otherwise they fall back to global similarity.

load.js (and the internal getItemUrl) forward these params from the originating embed automatically, so a visitor who clicks a card in an Austin map keeps seeing Austin-scoped similar items as they navigate between single pages.

Parameter	Type	Default	Description
list	string	-	List slug. Resolves to the list's boundary (via partner.boundary.slug) the same way the grid/map does.
boundary	string	-	Boundary slug. Similar items are clipped to this boundary's geometry. (Note: on the single page the item's own slug is the identifier param, so always use boundary here to scope similar items.)
organization	string	-	Organization slug used to scope similar items.
latitude / lat	number	-	Center latitude for a proximity (geo-distance) scope. Requires longitude + radius to take effect.
longitude / lng	number	-	Center longitude for a proximity scope. Requires latitude + radius.
radius / distance / dist	number	-	Radius in meters for the proximity scope. Requires latitude + longitude.

Example — keep similar events within a boundary:

/embed/single?type=event&slug=my-event&boundary=austin

Example — proximity-scoped similar items:

/embed/single?type=place&slug=my-place&lat=30.27&lng=-97.74&radius=5000

---

Sticky-Header Offset (scrollToTopOffset)

Applies to data-resize="true" embeds. When a visitor clicks a similar-items card, the next place/event opens in place and load.js scrolls the host page back up so the item's title/hero is in view. If your host page has a sticky or fixed header, the embed's top edge lands underneath it and the title stays covered. Set scrollToTopOffset to your header's height (px) to leave that much gap above the embed after the scroll, so the title clears the header.

Parameter	Type	Default	Description
scrollToTopOffset	number	0	Extra pixels of gap left above the embed when it scrolls to the top after opening a single item. Set to your sticky header's height. Non-negative integers only; 0 rests the embed flush against the viewport top (the original behavior).

Where it's read: Put scrollToTopOffset in the embed's URL params; the embed reads it inside the iframe and forwards it to the loader over postMessage (works on a proxied api.vibemap.com/list/<slug> short link too). If a single view is reached from a grid/map/carousel embed, that embed's scrollToTopOffset already applies — the loader keeps the value across the in-embed navigation — so set it here only when you embed a single profile standalone. (For host-side configuration load.js also honors it on the <script>'s data-url query or a data-scroll-to-top-offset attribute.)

/embed/single?type=event&slug=my-event&scrollToTopOffset=96