Skip to main content

Carousel URL Parameters

The /embed/carousel endpoint renders a CardCarousel component that displays places or events in a horizontally scrollable carousel layout.

Base URL​

/embed/carousel?slug=<boundary-slug>

Required Parameters​

ParameterTypeDescription
slug OR boundarystringLocation boundary slug (e.g., "austin", "sf", "denver")
liststringAlternative: List slug that provides configuration from Lists API

Note: Either slug/boundary OR list must be provided. When using list, if the list has an associated organization, that organization's boundary will be used automatically.


Content & Data Parameters​

ParameterTypeDefaultDescription
typestring"places"Content type: "places" or "events"
vibesstring-Comma-separated vibe filters (e.g., "chill,artsy")
categoriesstring-Comma-separated category filters
tagsstring-Comma-separated tag filters
categoriesMatch / vibesMatch / tagsMatchstringanyall shows only items that have every category, vibe or tag passed in that group; any shows items with at least one.
editorial_categories or editorial_category or editorialCategorystring-Editorial category filters (always applied server-side).
featuredbooleanfalseWhen true, only show featured places/events
dist / radiusnumber-Radius in meters for proximity (geo-distance) search. Requires latitude + longitude to take effect.
latitude / latnumber-Center latitude for proximity search. Only used when longitude and dist/radius are also set.
longitude / lngnumber-Center longitude for proximity search. Only used when latitude and dist/radius are also set.
hideNoImageItemsbooleanfalseHide items without images
tiersstring-Filter by membership tier slugs. Comma-separated (e.g., "basic,premium"). Use "non-member" for items with no tier.
strictFilterbooleanfalseWhen true, taxonomy filters are applied server-side
ordering / sortstring"-score_combined"Sort order for results (see below)

Sort Order (ordering / sort)​

Controls how places are sorted in the carousel.

ValueDescription
nameAlphabetical by place name (A-Z)
-score_combinedDefault. By relevance/popularity score (highest first)
-vibe_countBy number of vibes (most vibes first)

ParameterTypeDefaultDescription
columns / gridColumnsnumber4Number of visible slides/cards
headerstring-Optional header text above the carousel
showTitlebooleanfalseShow the list's name (or a boundary grid's boundary name) as the embed's <h1> above it. Off, the heading is still in the page for screen readers and crawlers, just not shown.

Card Display Parameters​

ParameterTypeDefaultDescription
showVibesOnCardsbooleantrueShow vibes on cards
showTagsOnCardsbooleanfalseShow tags on cards
showCategoriesOnCardsbooleanfalseShow categories on cards
showDescriptionbooleanfalseShow description on cards
showAddressOnCardsbooleantrueShow address on cards. Deprecated: use subtitle2Source=address&subtitle2Position=below-title instead.
subtitleSourcestring"none"Source for card subtitle: "none", "category", "address", etc.
subtitlePositionstring"above-title"Subtitle position: "above-title" or "below-title"
subtitle2Sourcestringcontent-type defaultData source for the second subtitle. Default: places="address", events="none". Options: "none", "category", "tag", "vibe", "address", "venue", "date" (date only, e.g. "Jun 15th"), "weekday_date" (weekday and date, e.g. "Mon Nov 16"), "start_date_time" (date + time, e.g. "Jun 15th • 7:00 PM"), "price", "custom" (combine multiple — see subtitle2Sources)
subtitleSourcesstring-Comma-separated list of sources to combine for the first subtitle when subtitleSource=custom. First-subtitle analog of subtitle2Sources — same token vocabulary, joined with •.
subtitle2Sourcesstring-Comma-separated list of sources to combine when subtitle2Source=custom. Each token uses the same vocabulary as subtitle2Source (e.g. category, venue, start_date_time). Empty values are skipped; the rest are joined with •. Example: subtitle2Source=custom&subtitle2Sources=venue,start_date_time → "Great Hall • Jun 15th • 7:00 PM"
subtitle2Positionstring"below-title"Position of the second subtitle: "above-title" or "below-title"
showTierBadgebooleanfalseShow the membership-tier badge on cards (e.g. "Premium").
showFeaturedBadgebooleantrueShow the "Featured" badge on featured cards. false hides it; featured items still sort first.
usePillLayoutbooleantrueFor multi-day events, render the date badge as a horizontal pill (date range). Set false for the stacked calendar-style badge.
pillSingleDaybooleanfalseRender single-day event date badges as the horizontal pill too (Oct 8). Combine with usePillLayout=true for pills on every event.
pillShowTimebooleanfalseAppend the start time to single-day pills (Oct 8 · 7PM). Needs pillSingleDay=true. Never shown on multi-day pills, all-day events, or ongoing events.
showDayOfWeekbooleanfalseName the weekday on single-day date badges (Fri Nov 13). Multi-day ranges are unchanged. A list's events.showDayOfWeek theme override sets the default.
ongoingEventShowNowbooleanfalseFor ongoing events (started in the past, still running), show the start as "Now" instead of today's date.
timeBadgesstring- (off)Comma-separated list of time-relative event badges to enable on cards (e.g. today,tonight,weekend). Off by default. Only the single highest-precedence matching badge renders per card. Falls back to theme.cards.timeBadges. See values below.

Time Badges (timeBadges)​

Opt-in, time-relative badges for event cards, computed from each event's start (and optional end) relative to "now". Pass a comma-separated list of types; unknown values are ignored. Only the single highest-precedence match renders per card.

ValueBadge labelMatches when…
ongoing"Ongoing"A multi-day event (≥ 24h span) is currently running
happening-now"Happening Now"The event is currently live (start ≤ now ≤ end; requires an end date)
tonight"Tonight"Starts today, at or after 5pm
today"Today"Starts today
tomorrow"Tomorrow"Starts tomorrow
weekend"This Weekend"Starts during the upcoming Sat–Sun window
this-week"This Week"Starts within today → next 7 days

Precedence is highest-first in the order above — e.g. a 7pm event tonight shows "Tonight" rather than "Today" when both are enabled. Labels can be overridden per theme via theme.cards.timeBadges.

Example: timeBadges=happening-now,today,tonight,weekend


Rating Parameters​

ParameterTypeDefaultDescription
showRatingbooleanfalseShow ratings on cards
ratingShapestring"star"Rating shape: "star" or "dot"
ratingDisplayStylestring"both"Display style: "stars", "number", or "both"
ratingPositionstring"below-title"Position: "above-title", "below-title", "below-address", "next-to-category"
ratingStarSizenumber16Size of rating stars in pixels
ratingStarColorstring"#FFD700"Color of rating stars (hex)
showRatingCountbooleantrueShow the number of ratings

Bookmark Parameters​

ParameterTypeDefaultDescription
showBookmarkbooleanfalseShow bookmark button on cards
bookmarkIconstring"star"Icon type: "bookmark", "heart", or "star"
bookmarkIconColorstring"#FF0000"Color of bookmark icon (hex)
smartCropbooleantrueImageKit AI smart crop (fo-auto). Set false for deterministic center crop
linkToExternalUrlbooleanfalseOpen each card's source URL (event source, place website) in a new tab instead of the internal single-post page. Falls back to the internal permalink when no source URL is set.

Button Parameters​

ParameterTypeDefaultDescription
showButtonbooleanfalseShow action button on cards
buttonTextstring-Custom text for the button

Event-Specific Parameters​

ParameterTypeDefaultDescription
groupRecurringEventsbooleanfalseGroup recurring events to show only next occurrence
collapseConsecutiveRunsbooleantrueShow an event that runs on back-to-back days (e.g. a Wed–Sun exhibit) as one slide. false shows a slide per day. An event's own collapse setting wins. Weekly series follow groupRecurringEvents.
showRecurrenceBadgebooleanfalseShow the recurrence label pill (e.g. "Weekly Wed - Sun") on event cards
hideRangedEventsbooleanfalseHide "ranged" events — those with a duration longer than 24 hours (e.g. multi-day festivals, ongoing exhibits).

Recurring Event Behavior: When groupRecurringEvents=true, events from a recurring series are grouped together, showing only the next occurrence with a badge indicating more dates are available. Clicking the recurring badge navigates to the event series page (/event-series/{id}) where all occurrences can be viewed.

Date Boundary​

Hard date limits that exclude events outside the range, regardless of other filters.

ParameterTypeDefaultDescription
dateBoundaryStartstring-Events before this date are excluded. Accepts yyyy-MM-dd or relative offset.
dateBoundaryEndstring-Events after this date are excluded. Accepts yyyy-MM-dd or relative offset.

Relative offset format: +Nd (days), +Nm (months), +Ny (years). Negative values work too (-7d = 7 days ago). The offset is computed fresh on each page load relative to the current date.

Examples:

# Only show events in the next 14 days
/embed/carousel?slug=austin&type=events&dateBoundaryEnd=%2B14d

# Next 3 months of events
/embed/carousel?slug=austin&type=events&dateBoundaryEnd=%2B3m

# Events between specific dates
/embed/carousel?slug=austin&type=events&dateBoundaryStart=2026-06-01&dateBoundaryEnd=2026-09-01

Note: The + character must be URL-encoded as %2B in query strings.

Past Event Window​

Controls how long after an event's end time it remains visible in the carousel. Default keeps every event visible for 90 minutes after it ends, so events with identical start/end times don't disappear the instant they begin.

ParameterTypeDefaultDescription
pastWindowinteger (minutes)90Minutes after end_date that an event remains eligible. 0 cuts at end. 1440 shows for 1 day. 10080 shows for a week. Overridden by pastCutoff if both are set.
pastCutoffISO 8601 datetime–Absolute floor — only events with end_date >= pastCutoff are shown, e.g. 2026-06-01T00:00:00. Site-local time. Overrides pastWindow when set.

Examples:

# Show events for 6 hours after they end
/embed/carousel?slug=austin&type=events&pastWindow=360

# Show all events from the past week onward
/embed/carousel?slug=austin&type=events&pastWindow=10080

# Show every event ending on/after June 1, 2026
/embed/carousel?slug=austin&type=events&pastCutoff=2026-06-01T00:00:00

Updates Display​

ParameterTypeDefaultDescription
showUpdatesbooleanfalseEnable updates display on cards
updatesDisplayModestring"badge"Display mode: "badge" or "text"
updatesFilterTypesstring-Comma-separated types: update,offer,clue,sponsor,special

Behavior Parameters​

ParameterTypeDefaultDescription
autoScrollSpeednumber0Auto-scroll interval in ms (500–30000). 0 or absent = off.
randomizebooleanfalseShuffle card order on each page load

Auto-scroll behavior: When enabled, the carousel automatically advances slides at the specified interval. It pauses when the user hovers over or interacts with the carousel, then resumes. Values below 500ms (except 0) are ignored.

Examples:

# Auto-scroll every 3 seconds
/embed/carousel?slug=austin&autoScrollSpeed=3000

# Randomized order with auto-scroll
/embed/carousel?slug=austin&autoScrollSpeed=4000&randomize=true

# Just randomized order, no auto-scroll
/embed/carousel?slug=austin&randomize=true

Theme Parameter​

ParameterTypeDefaultDescription
theme / themeNamestringthe list's theme, else "default"Theme slug for styling. Omit it with list= to use the list's own theme.

Category Names (categoryLabels)​

Renames single categories (and tags, vibes) on this carousel only, wherever the theme's category names show. The Map and Calendar builders write all three; Hub auto embeds write categoryLabels from the names picked in Manage auto embeds.

ParameterTypeDefaultDescription
categoryLabelsJSONnoneURL-encoded {"<slug_unique>": "<name>"}. Beats the list's theme_overrides and the theme's Taxonomies names. Blank or non-string names are skipped.
tagLabelsJSONnoneURL-encoded {"<tag slug>": "<name>"}. Same layering as categoryLabels, for tags.
vibeLabelsJSONnoneURL-encoded {"<vibe name>": "<name>"}. Same layering as categoryLabels, for vibes.

Not map-grid's categoriesLabel, which renames the Categories filter heading.

# Show "food" as "Eats" and "entertainment_music" as "Live sets"
/embed/carousel?slug=austin&categoryLabels=%7B%22food%22%3A%22Eats%22%2C%22entertainment_music%22%3A%22Live%20sets%22%7D

Vibe and Tag Names (vibeLabels, tagLabels)​

Rename single vibes and tags on this carousel only, as categoryLabels does for categories. Hub auto embeds set them from Manage auto embeds (VA#6771); Vibemap writes tag slugs, since a tag's slug can't be worked out from its name. Blank or non-string names are skipped.

ParameterTypeDefaultDescription
vibeLabelsJSONnoneURL-encoded {"<vibe name>": "<name>"}. Beats the list's theme_overrides and the theme's Taxonomies names.
tagLabelsJSONnoneURL-encoded {"<tag slug>": "<name>"}, keyed by slug, not name. Beats the list's theme_overrides and the theme's Taxonomies names.

Not map-grid's vibesLabel / tagsLabel, which rename the filter headings. A tag that reaches the embed as a bare string, with no slug, keeps its own name.

# Show the vibe "cozy" as "Snug" and the tag "Arts & Culture" (slug arts-and-culture) as "Culture"
/embed/carousel?slug=austin&vibeLabels=%7B%22cozy%22%3A%22Snug%22%7D&tagLabels=%7B%22arts-and-culture%22%3A%22Culture%22%7D

Sticky-Header Offset (scrollToTopOffset)​

Applies to data-resize="true" embeds. When a visitor clicks a carousel card, the single 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.

ParameterTypeDefaultDescription
scrollToTopOffsetnumber0Extra 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, alongside the others — it works on a proxied api.vibemap.com/list/<slug> short link too, because the embed reads it inside the iframe and forwards it to the loader over postMessage. The value is retained across the in-embed card→single navigation, so you set it once on the carousel embed and it also applies to the single/similar-item views opened from it. (For host-side configuration load.js also honors it on the <script>'s data-url query or a data-scroll-to-top-offset="100" attribute.)

/embed/carousel?slug=austin&scrollToTopOffset=96

Example URLs​

/embed/carousel?slug=austin&type=places
/embed/carousel?slug=dc&type=events&groupRecurringEvents=true
/embed/carousel?slug=la&columns=5
/embed/carousel?list=my-curated-list&columns=4
/embed/carousel?slug=sf&header=Featured%20Places

Filtered by Editorial Category​

/embed/carousel?slug=austin&editorial_categories=best-coffee-shops
/embed/carousel?slug=austin&type=events&featured=true

With Ratings Displayed​

/embed/carousel?slug=denver&showRating=true&ratingDisplayStyle=both&ratingPosition=below-title

With Bookmarks and Buttons​

/embed/carousel?slug=nyc&showBookmark=true&bookmarkIcon=heart&showButton=true&buttonText=View%20Details

Hide Items Without Images​

/embed/carousel?slug=sf&hideNoImageItems=true
/embed/carousel?slug=nyc&type=places&columns=4&header=Top%20Spots&showVibesOnCards=true&showAddressOnCards=true&showRating=true&hideNoImageItems=true&theme=default

PostMessage Events​

The embed communicates with the parent window via postMessage:

Event TypeDescriptionData
"card-clicked"User clicked a card{ embedId: "carousel", data: <item> }

Example Parent Window Handler​

window.addEventListener("message", (event) => {
if (event.data.embedId === "carousel") {
switch (event.data.type) {
case "card-clicked":
console.log("Card clicked:", event.data.data);
// Navigate to detail page, open modal, etc.
break;
}
}
});

Message Origin​

Embed messages may arrive from either of these origins:

  • https://web.vibemap.com — when the embed is loaded directly
  • https://api.vibemap.com — when the embed is loaded via a Vibemap list link (/list/<slug>) or short link (/s/<slug>), which reverse-proxies the embed page through the API host

Parent-window listeners should filter by payload (event.data.embedId and event.data.type) rather than event.origin. The example handler above already follows this pattern.

If you must check event.origin, accept BOTH https://web.vibemap.com AND https://api.vibemap.com.


Embedding​

Basic iframe Embed​

<iframe
src="https://vibemap.com/embed/carousel?slug=austin&type=places"
width="100%"
height="350"
frameborder="0"
style="border: none;"
></iframe>

With Custom Header​

<iframe
src="https://vibemap.com/embed/carousel?slug=austin&header=Discover%20Austin"
width="100%"
height="400"
frameborder="0"
style="border: none;"
></iframe>

Responsive Embed​

<div style="width: 100%; max-width: 1200px; margin: 0 auto;">
<iframe
src="https://vibemap.com/embed/carousel?slug=austin"
width="100%"
height="350"
style="border: none;"
></iframe>
</div>

Notes​

  • The carousel automatically adjusts the number of visible cards based on container width
  • Navigation arrows appear only when there are more items than can fit on screen
  • Cards are displayed in vertical orientation with a consistent "basic" style variant
  • For events, enabling groupRecurringEvents will show only the next upcoming occurrence of each recurring event series

Analytics Opt-Out (analytics)​

ParameterTypeDefaultDescription
analyticsstringonSet to off (also false, 0, no) to stop the embed loading analytics for that page load

Vibemap embeds load a Google Tag Manager container to measure how visitors use maps, cards and filters. analytics=off prevents it entirely — the container is never added to the page and no events are sent. The embed itself is unaffected.

/embed/carousel?list=downtown-erie&type=events&analytics=off

Where it's read: either the embed URL or the upstream URL behind a proxied short link. A customer embed usually loads through api.vibemap.com/list/<slug>, which fetches the real embed URL server-side while the browser keeps the clean short link — so analytics=off works whether you add it to the short link or bake it into the list's embed configuration.

This is independent of any analytics your own site loads, and independent of the WordPress plugin's Vibemap Settings → Features → Enable Analytics toggle, which governs Vibemap blocks rendered directly into a WordPress page.