Skip to main content

Map-Grid URL Parameters

Complete reference for all URL parameters supported by the map-grid embed page.

Table of Contents​


Required Parameters​

ParameterTypeDefaultDescription
slug / boundarystring-Location slug for fetching boundary and data (e.g., "austin", "dc", "westwood")
liststring-Alternative to slug. List slug that provides configuration from the Lists API

Note: Either slug (or boundary) or list should be provided:

  • slug: Fetches boundary and places within that geographic area
  • list: Fetches list configuration which may include an organization (boundary), search filters, and theme settings

When using list:

  • If the list has an organization, its slug is used as the boundary
  • If the list has no organization, places are fetched globally using the list's filters and the map centers on markers
  • URL parameters override list configuration (e.g., ?list=foo&editorialCategory=bar uses bar instead of list's default)

Content & Data​

ParameterTypeDefaultDescription
typestring"places"Content type: "places" or "events"
vibesstring-Pipe-separated list of vibes to filter by (e.g., "chill|artsy")
categoriesstring-Pipe-separated list of categories to filter by
tagsstring-Pipe-separated list of tags to filter by
editorial_categories or editorial_category or editorialCategorystring-Pipe-separated list of editorial categories to include
editorial_categories__excludestring-Pipe-separated list of editorial categories to exclude (e.g., "evanston-history" or "cat-a|cat-b")
featuredbooleanfalseWhen true, only show featured places/events
strictFilterbooleanfalseWhen true, applies strict taxonomy filtering (AND logic). The server-rendered cards and structured data hold only the items the URL's taxonomy chips keep, and none for a tags chip, which depends on a tag list only the browser loads
categoriesMatch / vibesMatch / tagsMatchstringanyWith strictFilter, all shows only items that have every category, vibe or tag passed in that group; any shows items with at least one. The Map and Calendar builders write them from Only show → Any | All.
onlyShowPassedTaxonomiesbooleanfalseWhen true, each filter row shows only the values passed via URL or set on the list (plus subcategories of a passed category); a row with none passed keeps all its chips
flatSubcategoriesbooleanfalseWhen true, the category chips are every subcategory side by side instead of top-level categories to drill into
dist / radiusnumber-Radius in meters for proximity search
hideNoImageItemsboolean-Hide items that don't have images
hideWithImageItemsbooleanfalseThe inverse: show only items without an image. hideNoImageItems wins when both are on.
hideRangedEventsbooleanfalseHide events with a duration longer than 24 hours
tiersstring-Filter by membership tier slugs. Comma-separated (e.g., "basic,premium"). Use "non-member" to show items with no membership tier (null).
ordering / sortstring"-score_combined"Sort order for results (see below)

Sort Order (ordering / sort)​

Controls how places are sorted in the grid/list.

ValueDescription
nameAlphabetical by place name (A-Z)
-score_combinedDefault. By relevance/popularity score (highest first)
-vibe_countBy number of vibes (most vibes first)
randomRandom order (shuffled on each page load)

Map Viewport​

ParameterTypeDefaultDescription
latitude / latnumberFrom boundaryInitial map center latitude
longitude / lngnumberFrom boundaryInitial map center longitude
zoomnumberFrom boundaryInitial zoom level (0-22)
bearingnumber0Map rotation in degrees (0-360)
pitchnumber0Map tilt in degrees (0-85)
zoomModestring"fit-boundary"Initial zoom behavior: "fit-boundary" (fit to boundary polygon), "fit-markers" (fit to all markers), or "custom" (use explicit lat/lng/zoom)
mobileLatitude / mobileLongitude / mobileZoomnumber- (fit markers)Where the map opens on phones (≤ the mobile breakpoint). Needs all three; beats zoomMode and latitude/longitude/zoom on phones only. Without them phones frame every marker. The builder's "Use this view on phones" writes them.
refitMarkersOnFilterChangebooleantrueWhen true and zoomMode="fit-markers", re-zoom to fit markers whenever filters change

Zoom Mode Details​

The zoomMode parameter controls how the map determines its initial viewport:

ValueBehavior
fit-boundaryDefault. Fits the map to the boundary polygon returned by the API
fit-markersCalculates bounds from all marker coordinates and fits the map to show all markers with padding
customUses explicit latitude, longitude, and zoom parameters; ignores boundary/marker bounds

Example - Fit to markers with auto-refit:

/embed/map-grid?slug=austin&zoomMode=fit-markers&refitMarkersOnFilterChange=true

Map Display​

ParameterTypeDefaultDescription
mapStylestringVibemap defaultMapbox style URL (e.g., "mapbox://styles/mapbox/streets-v12")
baseMapEditsjson-Base-map color and visibility edits for the mapStyle. The Hub's map builder writes this value; copy it from the builder rather than writing it by hand.
mapHeightnumber/string"100%"Map container height (px or CSS value)
mobileMapHeightnumber-Map height in px on mobile viewports (does not affect desktop). The iframe still grows to fit the whole component — map and cards.
mobileMaxHeightnumber-Deprecated alias for mobileMapHeight (kept for back-compat).
mobileBreakpointnumber768Viewport width threshold for mobileMapHeight (px)
panHintstringoffHow the map treats a one-finger drag or a page scroll over it: cooperative (Mapbox's two-finger / Ctrl-scroll gestures), custom (a "drag to explore" hint) or off.
cooperativeGesturesbooleanfalseDeprecated alias: cooperativeGestures=true is panHint=cooperative.
showBoundarybooleantrueShow boundary polygon on map
showMarkersbooleantrueShow place/event markers
showMarkersOutOfBoundarybooleanAutoMaster toggle: show OOB markers everywhere (auto-enabled with radius/strictFilter). Logged-in users can also toggle via the Filters → Advanced panel.
showMarkersOutOfBoundaryOnMapboolean(master)Show OOB markers on the map; falls back to showMarkersOutOfBoundary
showMarkersOutOfBoundaryInSidebarboolean(master)Show OOB places in the sidebar card list; falls back to showMarkersOutOfBoundary
showMarkersOutOfBoundaryInListboolean(master)Show OOB places in the list/grid view; falls back to showMarkersOutOfBoundary
clipToBoundsbooleantrueInverse of showMarkersOutOfBoundary — clipToBounds=false is equivalent to showMarkersOutOfBoundary=true. Convenience flag for "show everything outside the boundary too." showMarkersOutOfBoundary wins if both are set. Forced to true for list + disjoint MultiPolygon boundaries (requires client-side clipping).
showMapCardsbooleantrueShow info cards when clicking markers
showCardsbooleantrueShow the sidebar card list beside the map. showCards=false shows just the map.
useLegacyBottomCardbooleanfalseMobile. Keep the classic single bottom card instead of the new bottom sheet (peek header → one full-list carousel, plus any sheetRows; expands to fullscreen in embeds). Per-customer legacy toggle.
showUserLocationbooleanfalseAsk for the visitor's device location, show their blue-dot marker, and add a recenter button (mobile + desktop). Off by default.
showInlineChipsbooleantrueMobile. Show a taxonomy chip scroller under the search bar, outside the filters menu.
inlineChipsTaxonomystring"category"Which taxonomy the under-search chips show: category, tag, or vibe.
showDateRangePillsbooleantrueEvents. Show date-range preset pills (Today, This Week, All, …) under the search bar and in the filters menu; Custom opens the calendar.
sheetTitlestring"Explore"Mobile. Override the bottom-sheet peek-header title (e.g. sheetTitle=Explore%20venues). Falls back to theme.map.sheetTitle, then the default.
sheetRowsstring—Mobile. Extra carousel rows above the full list, comma-separated: featured, ongoing (events), category (the top 3 categories). Off by default; falls back to theme.map.sheetSections.
sheetDefaultStatestring"open"Mobile. Default state of the bottom sheet on load: open (expanded) or peek (collapsed). Maps saved in the builder before the default changed keep peek.
fullscreenbooleantrueMobile. Show the button that expands the embed to fill the screen. false hides it.
fullscreenHeaderTextstring"Back to site"Mobile. Label of the bar across the top in fullscreen; tapping it exits. Falls back to theme.map.fullscreenHeaderText.
showHeatbooleantrueShow heatmap layer
heatmapDimensionstring-Focus the heatmap on one term: vibe, category or tag. Needs heatmapTerm.
heatmapTermstring-The vibe, category or tag slug the heatmap counts, e.g. heatmapDimension=vibe&heatmapTerm=chill. Needs heatmapDimension.
showVibeCloudbooleanfalseShow a word cloud of the vibes on the places in view.
showTransitbooleantheme / falseShow the base map's transit layers (every style layer with "transit" in its id). Falls back to theme.map.showTransit.
showOverlaysbooleantrueShow the image overlays published on the boundary (e.g. a site plan or festival map). false hides them.
map3dbooleanfalseLegacy 3D mode (use terrain3d instead)

Mobile Map Height: On some mobile devices the default 90%-viewport height makes the map too tall (e.g. screen.availHeight doesn't account for browser chrome). Use mobileMapHeight to set the map's height in pixels when the parent viewport is narrower than mobileBreakpoint (default 768px). Unlike a fixed iframe cap, the iframe still grows to fit the whole component — the map plus the cards below it — so nothing is cropped or forced into an inner scrollbar. Desktop is unaffected. mobileMaxHeight is a deprecated alias that now behaves identically.

# Render the map 350px tall on mobile (cards still show in full below it)
/embed/map-grid?slug=austin&mobileMapHeight=350

# 400px map for viewports under 1024px
/embed/map-grid?slug=austin&mobileMapHeight=400&mobileBreakpoint=1024

Locator / Overview Mini-Map​

An inset "you are here" mini-map that frames a zoomed-out overview (e.g. a whole state/region) and draws a box showing the main map's current viewport. When interactive, the box is draggable and the overview is click-to-recenter, panning the main map.

ParameterTypeDefaultDescription
showLocatorMapbooleanfalseShow the locator/overview mini-map inset
locatorOverviewBBoxarrayAuto-derivedCustom extent [minLng, minLat, maxLng, maxLat] the overview frames (e.g. a whole state). Omit to auto-derive from boundary + view
locatorInteractivebooleantrueWhen true, the viewport box is draggable and the overview is click-to-recenter; false makes it display-only
/embed/map-grid?slug=corpus-christi&showLocatorMap=true&locatorInteractive=false&locatorOverviewBBox=[-100,25.3,-94.5,30.2]

3D & Effects (styleConfig)​

These parameters control Mapbox GL terrain, weather effects, and layer visibility.

Terrain​

ParameterTypeDefaultDescription
terrain3dbooleanfalseEnable 3D terrain elevation
terrainExaggerationnumber1.0Terrain height multiplier (0.1-3.0)
buildings3dbooleanfalseEnable 3D building extrusions
hillshadebooleanfalseEnable hillshade relief shading

Weather Effects​

ParameterTypeDefaultDescription
fogbooleanfalseEnable atmospheric fog effect
fogDistancenumber10Fog visibility distance (1-20 km)
snownumber/booleanfalseSnow effect intensity (0-1, or true for 0.5)
rainnumber/booleanfalseRain effect intensity (0-1, or true for 0.5)

Layer Visibility​

ParameterTypeDefaultDescription
hideLayersstring-Comma-separated layer IDs to hide (e.g., "poi-label,road-label")
showLayersstring-Comma-separated layer IDs to show (overrides theme defaults)

Common Layer IDs: poi-label, road-label, transit-label, water-label, place-label, building, road, landuse


Markers​

ParameterTypeDefaultDescription
markerStylestring"mixed"Marker display style: "mixed", "icons", "images", "only_featured"
markerLabelsstring"hide"Label display: "hide", "featured", "all"
markerColorstringTheme accentDefault color for marker icons (hex, e.g., "#4A90E2" or "4A90E2")
markerTaxonomyColorsstring-Custom color overrides for categories or tags (e.g. category:food:#FF5A5F,tag:coffee:#8B5CF6)
maxImageMarkersnumberTheme defaultMax number of image markers to show
maxIconMarkersnumberTheme defaultMax number of icon markers to show

Location Dots​

Shows small dots at every GeoJSON location regardless of clustering, marker limits, or other display restrictions. Useful for showing the full extent of data when markers are limited.

ParameterTypeDefaultDescription
showDotsbooleanfalseEnable dots at all GeoJSON locations
dotsColorstringTheme accentDot fill color (hex, e.g., "9B59B6" or "#9B59B6")
dotsRadiusnumber4Dot radius in pixels
dotsOpacitynumber1Dot opacity (0-1)
dotsStrokeColorstring-Optional stroke/outline color for dots
dotsStrokeWidthnumber0Stroke width in pixels (only applies if color is set)

Example - Show Dots with Custom Styling​

/embed/map-grid?slug=austin&showDots=true&dotsColor=4a90e2&dotsRadius=3&dotsOpacity=0.5

Parking Layer​

Separates parking items into a dedicated map layer rendered below regular markers. Parking items are detected by category (slugs starting with parking, e.g., parking, parking-charging, parking-private). When disabled, parking items are treated like any other place.

ParameterTypeDefaultDescription
showParkingLayerbooleanfalseSeparate parking items into a dedicated layer below regular markers

Example - Show Parking Layer​

/embed/map-grid?slug=austin&showParkingLayer=true

Place-Amenity Legend​

A legend of amenity items (custom icon + label) keyed to a value on a configurable place field (e.g. a beach map with restrooms / parking / lifeguard). It is informational by default — a key, with no checkboxes and no filtering. Set placeLegendInteractive=true to turn it into a filter: each item becomes a checkbox that toggles the matching place markers on/off — OR + "hidden unless matched" (only places matching at least one checked item are shown), filtering map, grid, and calendar together, and composing with the normal taxonomy filters (AND). Distinct from the Mapbox style-layer legend (showLegend).

The legend definition (items) is normally supplied by the org theme (theme.map.placeLegend) or the WordPress block. URL params can also carry it, but a hand-authored URL usually just controls runtime state.

Independently of interactivity, placeLegendShowOnCards=true surfaces each place's matching amenity icons on its cards and at the top of the item-details description.

ParameterTypeDefaultDescription
showPlaceLegendbooleanfalseEnable the place-amenity legend
placeLegendarrayTheme defaultJSON array of legend items (see shape below). Usually set by theme/WP rather than hand-authored URL
placeLegendTitlestringLegendLegend panel title
placeLegendShowTitlebooleantrueShow the panel title text; false hides it (panel stays collapsible via the header chevron)
placeLegendPositionstringtop-righttop-right | top-left | bottom-right | bottom-left
placeLegendCollapsedbooleanfalseStart the legend collapsed (always starts collapsed on mobile regardless of this)
placeLegendInteractivebooleanfalseInformational by default (a key). true adds checkboxes that show/hide places by amenity + filter the map
placeLegendIncludeLayersbooleanfalseLists the map's layer toggles in this legend, under the amenity rows, instead of a separate Layers card. Needs showPlaceLegend=true
layerLabelsstring—Renames layers in the legend as Original=New, comma-separated (Walking path=Trail,Piazza=Plaza). Matches the original name ignoring case
placeLegendShowOnCardsbooleanfalseAlso render each place's matching amenity icons on its cards and atop the item-details description
placeLegendActivearrayall itemsComma-separated item ids that start checked (control state without redefining items)

Legend item shape (placeLegend entry):

{
"id": "restrooms", // stable id (used by placeLegendActive)
"label": "Restrooms", // row label
"icon": "https://…", // optional custom image; falls back to `color` swatch
"color": "#2563eb", // optional swatch color when no icon
"field": "tags", // place field to match (tags | categories | vibes | attributes | …)
"values": ["restrooms"], // slugs/names matched on `field` (OR)
"match": "exact" // "exact" (default) or "prefix" (e.g. "parking" → "parking-private")
}

Example - Beach amenities legend (control which start active)​

/embed/map-grid?slug=corpus-christi&showPlaceLegend=true&placeLegendActive=restrooms,parking

Example - Interactive filter legend with icons on cards​

/embed/map-grid?slug=corpus-christi&showPlaceLegend=true&placeLegendInteractive=true&placeLegendShowOnCards=true

Clustering​

ParameterTypeDefaultDescription
shouldClusterbooleanfalseEnable marker clustering
clusterRadiusnumberTheme defaultPixel radius for clustering (typically 35-80)
clusterMaxZoomnumberTheme defaultMax zoom level for clustering (integer, typically 14-18)
useVectorTileDotsbooleantruePlaces-only. Load the dots layer from the ES vector-tile endpoint instead of the full boundary-wide place list; off falls back to the pre-migration items-based rendering
showNumberedMarkersbooleanfalseNumber each pin to match the same number on its card, like a printed map's legend. Forces shouldCluster off — a single pin can't carry one stable number for a bundle of many places.
numberedMarkerStylestring"numbers"Marker display style when showNumberedMarkers is true: "numbers" (display number inside pin circle without icon, standard for printed maps) or "icons_with_numbers" (display category icon with a numbered badge, standard for digital maps).

Grouping (Co-located Markers)​

Groups markers that are at the same location (e.g., multiple events at the same venue). When clicked, groups expand to show individual items using either "spider" mode (circular spread) or "list" mode (scrollable popup).

ParameterTypeDefaultDescription
enableGroupingbooleantrueEnable grouping of co-located markers
groupingTolerancenumber3Distance in meters within which items are considered co-located
spiderModeMaxItemsnumber8Max items for "spider" expansion (circular spread); larger groups show a scrollable list instead
maxGroupMarkersnumbertheme map.maxGroupMarkers → 32Most group markers drawn in view at once; the densest groups, and the open or selected one, win. 0 removes the cap.

How Grouping Works​

  1. Detection: Items within groupingTolerance meters of each other are grouped together
  2. Display: Groups show a purple marker with a count badge indicating the number of items
  3. Expansion modes:
    • Spider mode (≤ spiderModeMaxItems): Items spread out in a circle around the centroid with connecting lines
    • List mode (> spiderModeMaxItems): A scrollable popup appears with all items listed
  4. Collapse: Click the X button at the centroid (spider mode) or close the popup (list mode)

Grouping vs Clustering​

FeatureGroupingClustering
PurposeItems at the same address/venueVisual decluttering of nearby markers
Tolerance~3 meters (same building)35-80 pixels (screen distance)
ExpansionSpider web or scrollable listZoom to cluster bounds
ColorPurpleTeal (places) or Red (events)
WhenAlways (co-located items exist)When zoomed out

Both features can be enabled simultaneously - clustering happens at zoom-out levels, grouping handles co-located items at any zoom level.


Boundary​

Display​

ParameterTypeDefaultDescription
boundaryFilterstring-Filter to specific polygon by name (for MultiPolygon boundaries)
polygonIndexnumber-For a boundary with several polygons, select one on load by zero-based index and show only the items inside it. Visitors can change the selection in the boundary selector.
showBoundarySelectorbooleantheme / trueMaster toggle for the whole boundary selector UI. false hides it entirely (regardless of polygon/layer count). URL param wins, then theme.map.showBoundarySelector, then true.
showBoundarySelectorListbooleantrueShow boundary selector dropdown for MultiPolygon boundaries
boundarySelectorLabelstring"Boundary"Custom label for boundary selector (e.g., "Neighborhood", "District")
boundarySelectAccentColorstringtheme accentColour of the boundary selector's buttons and popup (hex, e.g. ff6600). Falls back to the theme's accent colour.
showHoverPopoverOnPolygonbooleanthemeEnable the hover popover/tooltip on boundary + overlay polygons. Falls back to theme.map.showHoverPopoverOnPolygon (default false).
boundaryBuffernumbertheme / 0Tolerance in metres. An item within this distance of the boundary counts as inside it. URL param wins, then theme.map.boundaryBufferMeters, then 0 (exact).

Boundary Buffer (boundaryBuffer)​

Official neighbourhood polygons run down the middle of streets, so a venue that everyone — including its own neighbourhood tag — considers part of the neighbourhood can sit just outside the line. boundaryBuffer widens the filter by a tolerance in metres so those venues are kept.

It does not widen the drawn boundary: the map still outlines the true polygon. Only the inside/outside test is forgiving.

?boundaryFilter=Chinatown&boundaryBuffer=100

Applies everywhere the boundary is enforced — markers, sidebar, grid, the "Showing X of Y" count, and the Events/Venues toggle — so every surface agrees.

Picking a value. Buffers grow area fast, and bleed from the neighbouring district grows with it. Measured against SF Live's Chinatown polygon (2,605 events, 26 rows exactly inside):

BufferRows keptOf the newly added, tagged for this neighbourhood
026—
50290 of 3
1007440 of 48
150207heavy bleed from adjacent districts

100m recovered every venue whose own tag claimed the neighbourhood (a venue 57m outside, across the street) without dragging in the district next door. Start around 100 and check what appears rather than assuming a bigger number is safer.

Styling​

ParameterTypeDefaultDescription
boundaryFillColorstring-Fill color (hex, e.g., "#ff0000" or "%23ff0000" URL-encoded)
boundaryFillOpacitynumber0Fill opacity (0-1)
boundaryLineColorstring-Line color (hex)
boundaryLineOpacitynumber1Line opacity (0-1)
boundaryLineWidthnumber2Line width in pixels
boundaryLineDashstringtheme → solidLine style: solid, dashed or dotted

Filters​

ParameterTypeDefaultDescription
search / searchTermstring""Pre-populate the search filter with an initial query
searchModestring"hybrid"hybrid adds a server-side fuzzy search over the same items to the in-browser match; client matches the loaded items only. Falls back to theme.filters.searchMode.

Filter Visibility​

ParameterTypeDefaultDescription
showFiltersbooleantrueShow filter UI
showVibeFilterbooleantrueShow vibes filter
showCategoryFilterbooleanAutoShow categories filter (auto for places)
showTagFilterbooleantrueShow tags filter
showAllTagsbooleanfalseWhen true, force the tag filter row on and bypass tagsToInclude/tagsToExclude (URL + theme), showing every tag. Theme equivalent: theme.filters.showAllTags.
hideAllCategoriesPillbooleanfalseWhen true, remove the "All Categories" pill from the category row.
hideAllTagsPillbooleanfalseWhen true, remove the "All Tags" pill from the tag row.
tagsToIncludestringthemeComma-separated allowlist of tag slugs/names — only these tags appear in the tag filter. Falls back to theme.filters.tagsToInclude. Ignored when showAllTags=true.
tagsToExcludestringthemeComma-separated blocklist of tag slugs/names to hide from the tag filter. Falls back to theme.filters.tagsToExclude. Ignored when showAllTags=true.
categoriesToIncludestringthemeComma-separated allowlist of category names, slugs or slug_unique values. Only these, with their subcategories, appear in the category filter; an included subcategory keeps its parent as the way in. Falls back to theme.filters.categoriesToInclude.
categoriesToExcludestringthemeComma-separated blocklist of categories to hide from the category filter, subcategories included. Falls back to theme.filters.categoriesToExclude. Beats categoriesToInclude.
vibesToIncludestringthemeComma-separated allowlist of vibe names/slugs — only these appear in the vibe filter. Falls back to theme.filters.vibesToInclude.
vibesToExcludestringthemeComma-separated blocklist of vibe names/slugs to hide from the vibe filter. Falls back to theme.filters.vibesToExclude.
showSearchFilterbooleantrueShow search input
showTopLevelFiltersbooleantrueShow filters at top level (vs inside map)
showItemCountOnFiltersbooleantrueShow item counts on filter chips
showTierFilterbooleanfalseShow membership-tier filter chips (filter items by membership tier).
showLoginbooleantrueShow the login/account button in the filters bar (alias: showLoginButton). Falls back to theme.layout.showLogin.
loginButtonSizenumber32Avatar size (px) of the login/account button.
visibleCatsnumber5Max categories to show before "Show More" pill (default: 5, 0 = show all)
visibleVibesnumber-Max vibes to show before "Show More" pill (undefined = show all)
visibleTagsnumber5Max tags to show before "Show More" pill (default: 5, 0 = show all)

Filter Behavior​

ParameterTypeDefaultDescription
filterViewModestring"horizontal"Filter layout: "horizontal" or "tabbed"
filterSelectionModestring"auto"Selection mode: "single", "multiple", "auto"
filterBehaviorstring"trapped"Navigation behavior when taxonomy filters are passed (see below)
multiSelectTaxonomiesarray[]JSON array of taxonomy names that allow multi-select
taxonomySortOrderstring"count"Sort order per taxonomy (see below)
categoryOrderlistthemeComma-separated category slugs (slug_unique) to show first in the category filter, in this order. The rest keep the taxonomySortOrder sort. Overrides theme.filters.categoryOrder.
vibeOrderlistthemeComma-separated vibe slugs to show first in the vibe filter, in this order. Overrides theme.filters.vibeOrder.
tagOrderlistthemeComma-separated tag slugs to show first in the tag filter, in this order. Overrides theme.filters.tagOrder.

Taxonomy Sort Order (taxonomySortOrder)​

Controls how filter chips are sorted within each taxonomy. Default is count (most items first).

Format: "taxonomy:order,taxonomy:order" — comma-separated key:value pairs

Values:

ValueDescription
countDefault. Sort by item count (most items first), then alphabetically
alphaAlphabetical sorting (theme order → color → A-Z)

Examples:

# All taxonomies alphabetical
taxonomySortOrder=vibes:alpha,categories:alpha,tags:alpha

# Categories by count, vibes alphabetical
taxonomySortOrder=categories:count,vibes:alpha

# Just change tags to alphabetical (others stay as count)
taxonomySortOrder=tags:alpha

Filter Behavior Values (filterBehavior)​

Controls how users can navigate taxonomy hierarchies when a taxonomy filter is passed via URL with strictFilter=true.

ValueDescription
trappedDefault. User is locked within the passed taxonomy. Only the passed category/vibe/tag and its children are shown. User cannot navigate to parent/sibling taxonomies.
selectedThe passed filter is pre-selected, but user can deselect it to see parent-level filters. Allows escaping the passed taxonomy.
openCurrent behavior - all taxonomies from returned items are shown, regardless of what was passed.

Important Notes:

  • Only applies when strictFilter=true. Without strictFilter, the parameter is ignored and behavior defaults to open.
  • If multiple taxonomy values are passed (e.g., ?categories=shop,food), behavior automatically switches to open.
  • Applies to all taxonomy types: categories (hierarchical), vibes (flat), and tags (flat).

Taxonomy Labels​

Customize the display names for taxonomy sections in the filters UI.

ParameterTypeDefaultDescription
vibesLabelstring"Vibes"Custom display name for the Vibes taxonomy
categoriesLabelstring"Categories"Custom display name for the Categories taxonomy
tagsLabelstring"Tags"Custom display name for the Tags taxonomy

Examples:

# Rename "Vibes" to "Feel"
/embed/map-grid?slug=austin&vibesLabel=Feel

# Rename all taxonomies
/embed/map-grid?slug=austin&vibesLabel=Mood&categoriesLabel=Types&tagsLabel=Keywords

# Partial override (only change Vibes, others keep defaults)
/embed/map-grid?slug=austin&vibesLabel=Tags

Geography Filter (showGeoFilter)​

A Region filter that narrows the items to a city, county, neighborhood, area or address. It appears in the Grid, List and Calendar views, not the Map view.

ParameterTypeDefaultDescription
showGeoFilterbooleantheme / falseShow the Region filter. Falls back to theme.filters.showGeoFilter.
geoFilterLabelstring"Region"Heading of the Region filter.
geoFilterTypeslistallComma-separated tabs to offer: cities, counties, neighborhoods, boundaries (shown as "Area"), addresses. A tab with no options is hidden.
geoFilterDefaultTypestring-Tab open on load, from the geoFilterTypes values. Without it, City opens when it has options, else the first tab that does.
geoFilterAllowUserTypeSwitchbooleantrueShow the tabs so visitors can switch type. false locks the filter to the default tab.
geoFilterAddressSearchEnabledbooleantrueOn the Address tab, offer an address search with a distance picker (1, 5, 10 or 25 mi).
geoFilterOptionsToIncludelist-Comma-separated option names or slugs. Only these appear.
geoFilterOptionsToExcludelist-Comma-separated option names or slugs to hide.

Category Names (categoryLabels)​

Renames single categories (and tags, vibes) on this map 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 categoriesLabel, which renames the Categories filter heading. A theme's legacy filters.category_names still wins in the filter row.

# Show "food" as "Eats" and "entertainment_music" as "Live sets"
/embed/map-grid?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 map 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 vibesLabel / tagsLabel, which rename the filter headings. A theme's legacy filters.tag_names still wins in the filter row's tag chips. 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/map-grid?slug=austin&vibeLabels=%7B%22cozy%22%3A%22Snug%22%7D&tagLabels=%7B%22arts-and-culture%22%3A%22Culture%22%7D

Date Filters (Events)​

ParameterTypeDefaultDescription
showDateRangeSelectorbooleantrueShow date range selector (events only)
initialDateFilterstring"" (no limit)Pre-selects the date picker on load with a rolling/preset window the visitor can still widen or change. One of: today, weekend, next_7_days (rolling: today → today+6), next_week (calendar Mon–Sun), month, quarter, half_year, year. Empty = show all. Unlike dateBoundaryStart/End, this is a default selection, not a hard limit.
dateFilterOptionsarray["upcoming","today","weekend","next_week","month"]Available date filter options
ParameterTypeDefaultDescription
layoutModestringdefaultsidebar-left / sidebar-right put a sidebar column beside the grid cards. Pair with showTopLevelFilters=false to move the filters into it.
showMiniCalendarbooleanfalseEvents only, sidebar layouts only. A month calendar at the bottom of the sidebar. The active date filter is drawn as a band; days with events get a dot; past days are disabled. Click a day to filter to it, then click a second day to extend to a range (the date field follows). Click the first day again, or "Clear", to restore the previous range.

Example: ?slug=king-of-prussia&type=events&views=grid&layoutMode=sidebar-left&showTopLevelFilters=false&showMiniCalendar=true

Date Boundary (Events)​

Hard date limits that exclude events outside the range, regardless of user filter selections.

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/map-grid?slug=austin&type=events&dateBoundaryEnd=%2B14d

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

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

# Events from today through end of year
/embed/map-grid?slug=austin&type=events&dateBoundaryStart=%2B0d&dateBoundaryEnd=%2B1y

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. 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/map-grid?slug=austin&type=events&pastWindow=360

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

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

Views​

The map-grid embed renders the shared Combo controller (ADR-0004). Peer Views are available — Map, Grid, Calendar, and List (Events only) — selected by the View toggle. The toggle auto-hides when only one View is available. calendar is Events-only (always stripped for type=places); list is also Events-only (degrades to grid for type=places).

ParameterTypeDefaultDescription
layoutstring"map-grid"Preset layout mode configuring the embed layout and starting view: "grid" (cards grid), "list" (chronological feed), or "map-grid" (split interactive map & grid). Sets the starting view unless explicitly overridden by defaultView.
viewsstring (CSV, ordered)grid,calendar,map (events) / map,grid (places)Ordered list of Available views. Order = toggle order; presence = enabled. Tokens: map, grid, list, calendar. calendar is always stripped for Places; list degrades to grid for Places. Duplicates are de-duped; an empty/all-stripped result falls back to grid. Example: views=grid,calendar,map.
defaultViewstringsee noteStarting View. Must be one of the (guarded) Available views, else falls back to the first entry. Values: map, grid, list, calendar (list and calendar are Events-only).
initialViewstring"map" for Places, "grid" for Events (when no views/defaultView set)Deprecated alias for defaultView; honoured only when defaultView is absent. Accepts map, grid, list, calendar (list and calendar are Events-only; for Places list degrades to grid).
calendarMonthsnumber (1–12)theme calendar.monthsToShow → 1Number of months the Calendar View renders at once.
calendarCardStylestringtheme calendar.cardStyle → compactCalendar event card style: compact (default — small thumbnail + accent time + one-line title, no date badge) or card (full ui-components Card).
calendarMaxPerDaynumbertheme calendar.maxEventsPerDay → 4Max events shown per day cell before a "+N more" link. When omitted, resolves from the active theme's calendar.maxEventsPerDay.
calendarMaxPerDayMobilenumbertheme calendar.maxEventsPerDayMobile → 8The same cap on phones.

Default View note: When neither views nor defaultView is supplied, a Places embed starts on Map (back-compat) and an Events embed (type=events) on Grid. Supply defaultView (or the deprecated initialView) to choose a different landing View; supplying views/defaultView lets the Combo's content-type default decide (first entry of views).

Calendar View behaviour (ADR-0005): In Calendar View the global date filter is bypassed and its date-range chip is hidden — month navigation is the date control. Taxonomy / vibe / category / search filters still apply. The date-filter value is preserved and re-applies when switching back to Grid or Map.

ParameterTypeDefaultDescription
maxWidthnumber/string-Cap the whole widget width and center it within its parent. Number → px; any CSS length/expression passes through verbatim (800px, 90vw, calc(100% - 40px)). Leave unset to fill the container. In calc() URL-encode spaces and %: maxWidth=calc(100%25%20-%2040px).
gridColumnsnumber3Number of columns in grid view
shownAtStartnumber99Number of items shown initially
showTitlebooleanfalseShow the list's name (a boundary grid's boundary name, a location grid's area) as the embed's <h1> above it. Off, the heading is still in the page for screen readers and crawlers, just not shown.
hideSidebarbooleanfalseHide the sidebar card list (map view only)
showContentModeTogglebooleantrue (events) / false (places)Show Events/Venues toggle. Users can switch between viewing events and venues with event counts. Defaults to true when type=events.

Max Width: maxWidth constrains the entire embed (map, cards, header) rather than just the map, and centers it with margin-inline: auto. Use it to keep a wide embed readable on full-bleed pages. It differs from mapHeight/maxMapHeight, which size only the map container.

# Cap the embed at 1100px and center it
/embed/map-grid?slug=austin&maxWidth=1100

# Responsive cap leaving 40px gutters
/embed/map-grid?slug=austin&maxWidth=calc(100%25%20-%2040px)

Card Display​

ParameterTypeDefaultDescription
cardStylestring"list"Card style variant
compactCardsbooleanfalseDenser card layout — smaller image, tighter padding and type, so more cards fit on screen
printSizestring"normal"Card and print size preset: "postcard" (4" × 6"), "letter" (8.5" × 11"), "a4", "a3", or "normal"
showCardHeaderbooleanfalseStory header & brand bar above cards or across the top of the map
cardHeaderLayoutstring"above-cards"Header layout: "top-bar" (bar across the top with logo, title, copy, QR) or "above-cards" (stacked in sidebar above cards)
cardHeaderLogostring-Image URL for brand/organization logo
cardHeaderLogoLinkstring-Optional URL to open when clicking the logo
cardHeaderTitlestring-Headline text for the story header
cardHeaderDescriptionstring-Storytelling copy explaining how the map works and guiding visitors
cardHeaderScrollablebooleantrueWhen true, description scrolls smoothly if content exceeds maximum height
cardHeaderMaxHeightnumber-Custom maximum pixel height for description copy
showQrCodebooleanfalseGenerate vector QR code for printed map directing to digital version
qrCodeUrlstringcurrent URLTarget link for QR code (defaults to digital map URL; can override to custom website)
qrCodeLabelstring"Scan for digital map"Label caption displayed with QR code
qrCodeMetricTagstring"utm_source=qr&utm_medium=print&utm_campaign=map"UTM parameters appended to QR destination for scan attribution
showOverlayLayersbooleantrueToggle custom GeoJSON overlay layers (e.g. bike networks, transit, boundaries, trails)
overlayLineColorstring-Color override for overlay line features
overlayLineWidthnumber2Line thickness for overlay features in pixels (1–12px)
overlayLineOpacitynumber0.6Line opacity for overlay features (0.1–1.0)
showVibesOnCardsbooleantrueShow vibes on cards
showTagsOnCardsbooleanfalseShow tags on cards
showAddressOnCardsbooleantrueShow address on cards. Deprecated: use subtitle2Source=address&subtitle2Position=below-title instead.
descriptionLengthnumber-Max description length. If > 0, shows description
showTaglineOnCardsbooleanfalseShow each place's tagline (short_description) as the card text; a place without one shows its description
showDescriptionOnCardsbooleantheme / falseShow the description on cards. Ignored when descriptionLength is set. Falls back to theme.cards.showDescriptionOnCards.
subtitleSourcestring"none"Subtitle content: "none", "category", "address", etc.
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 •.
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", "tagline" (the place's short_description), "custom" (combine multiple — see subtitle2Sources)
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"
showRatingbooleanfalseShow ratings on cards
ratingSourcestring"aggregate"Which rating cards show: aggregate (Vibemap's), google, yelp or tripadvisor
ratingDisplayStylestring"both"Rating display: "stars", "number" or "both"
priceBadgePositionstring"none"Where the price badge sits: image-top-left, image-top-right, image-bottom-left, image-bottom-right, body-above-title, body-below-title or none. With none, a free item still gets a "Free" badge at the image's bottom left.
placeholderVariantstringtheme → circlesPattern on a card with no photo: circles, stripes, lines or neutral
showBookmarkbooleanfalseShow bookmark button
bookmarkIconstring"star"Bookmark icon: "bookmark", "heart" or "star"
openSinglePostbooleanfalseOpen item detail page on click
randomizeImagesbooleanfalseWhen true, pick a random image; default uses first/featured
useCategoryIconPlaceholdersbooleantheme / falseOn a place card with no photo, show its category or amenity icon instead of the generic placeholder. true here or in theme.cards.useCategoryIconPlaceholders turns it on.
smartCropbooleantrueImageKit AI smart crop. false → center crop
linkToExternalUrlbooleanfalseOpen card source URL in new tab (grid view). Fallback to permalink.
showVibesInDetailsbooleantrueShow vibes under hero image in item details panel
showSimilarItemsbooleantrueShow the "Similar Places" / "Similar Events" carousel in the item details panel. showSimilarItems=false hides it — see below
disclaimerstringthemeEvents only. Text of the notice in the event details panel, replacing the partner's disclaimer set in the Hub. An empty value (disclaimer=) hides the notice. Cards pass it on to the Vibemap event page they open, but not to an event page on your own site. The Hub writes it when a calendar embed overrides the notice.
showSuggestEditbooleanthemeShow the "Suggest Edit" button in the item details panel. Unset follows the theme's permissions.allow_edit_requests (off by default); ?edit=1 also turns it on. The map builder's "Visitors can suggest an edit" switch writes it.
useUpdateImagesbooleanfalseWhen true, use the first image from a place's updates/offers/specials as the card display image (instead of the place's own photos). Pairs with the Updates Display feature below.
showTierBadgebooleanfalseShow the membership-tier badge on cards (e.g. "Premium").
accentColorstringtheme accentOverrides the theme accent on this map only: card dates, badges and buttons (hex, e.g. "#1E40AF" or "1E40AF"). Anything else falls back to the theme. The builder's Cards → Colors → "Accent color" writes it.
cardDescriptionSizestringthemeDescription text size on cards: sm (13px), md (15px), lg (17px), xl (19px). Other values are ignored. The builder's Cards → Description size writes it.
cardTitleColorstringthemeListing name on each card (hex). Overrides the theme's cards.title_color. The builder's Cards → Colors writes it.
cardBackgroundColorstringtheme surfaceCard background and its tag chips (hex). Applies to this map's cards only. The builder's Cards → Colors writes it.
cardTextColorstringtheme textBody text on cards (hex). The builder's Cards → Colors writes it.
cardDetailColorstringtheme mutedSecondary card lines: category, venue, address (hex). The builder's Cards → Colors writes it.
filterBackgroundColorstringtheme surfaceBackground of the search/filter panel and its chips (hex). The builder's Filters → Colors writes it.
filterTextColorstringtheme textText of the filter panel and its chips (hex). The builder's Filters → Colors writes it.
filterSelectedColorstringtheme accentFill of selected filter chips (hex); their text picks a readable contrast. The builder's Filters → Colors writes it.
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.
showRecurrenceBadgebooleanfalseShow the recurrence label pill (e.g. "Weekly Wed - Sun") on event cards. Off by default. Falls back to theme.cards.showRecurrenceBadge.
groupRecurringEventsbooleanfalseCollapse each recurring event series to a single card showing its next occurrence. Off by default. Applies across all three views: the grid/list view shows a "See X more dates" affordance, and the map view (markers + sidebar) collapses each series to its next occurrence too. The calendar keeps every occurrence on its own day. Falls back to theme.cards.groupRecurringEvents.
collapseConsecutiveRunsbooleantrueShow an event that runs on back-to-back days (e.g. a Wed–Sun exhibit) as one card. false shows a card per day. An event's own collapse setting wins. Weekly series follow groupRecurringEvents.

Similar Items in the Details Panel (showSimilarItems)​

The item details panel (the drawer that opens when a visitor clicks a marker, or drills into a venue) ends with a "Similar Places" / "Similar Events" carousel. It is on by default. showSimilarItems=false removes it from both panel states — the clicked-marker panel and the venue drill-down panel.

/embed/map-grid?list=my-list&showSimilarItems=false

showSimilarItems=0 works too: every documented boolean accepts 0/1 (see BOOLEAN_PARAMS in web/src/utils/embedUtils.ts).

It gates the fetch, not the render. Setting it false disables the /search/{places,events}/similar/ queries outright rather than hiding a rendered section, so you also save the round-trip. (The panel only renders the carousel when it has data, so starving the query is what hides it.)

It is per-embed — it does not travel. showSimilarItems is not in SCOPE_PARAM_KEYS (hooks-shared/src/utils/paramUtils.ts) or in load.js's DEFAULT_SCOPE_FORWARD_PARAMS, so unlike list / boundary / theme it is not carried onto the single place/event page a visitor opens from a card. To turn the carousel off there too, set it on that page's embed as well — or, if the host page carries the param in its own URL, add data-forward-params="showSimilarItems" to the <script> tag.

No equivalent for "Events at this Venue". That carousel is always fetched for places (useEventsByPlaceSlug, ungated) — see Not URL-Controllable.

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

Updates Display​

Show offers, specials, clues, and updates from places on cards and in the details panel.

ParameterTypeDefaultDescription
showUpdatesbooleanfalseEnable updates display on cards and detail panels
updatesDisplayModestring"badge"Card display mode: "badge" or "text"
updatesFilterTypesstring-Comma-separated types: update,offer,clue,sponsor,special
updatesPositionstring"under-vibes"Detail panel position (see below)
updatesExpandedbooleantrueUpdates section expanded by default in detail panels

Update Types:

  • Update - General updates and announcements
  • Offer - Special offers and discounts
  • Clue - Hints and tips (e.g., for scavenger hunts)
  • Sponsor - Sponsored content
  • Special - Special events or limited-time promotions

Updates Position Values: under-vibes, under-description, before-hours, before-links, after-links

Example - Show Offers Only:

/embed/map-grid?slug=austin&showUpdates=true&updatesFilterTypes=offer&updatesDisplayMode=badge

Theme​

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

Themes can provide defaults for many parameters above, reducing URL complexity.


ParameterTypeDefaultDescription
desktopAdPlacementstring"beside-chips"Where banner ads appear on wide containers (> 1024px) — see below
mobileAdPlacementstring"above-component"Where banner ads appear on narrow containers (<= 1024px) — see below

Banner ads are configured per-theme (via the theme parameter) or per-block in WordPress; both placement params can also be set directly on the URL. The two settings draw from one shared anchor vocabulary — the container-width breakpoint (1024px) decides which one is in effect, so you can place ads differently on desktop vs. mobile.

Anchor vocabulary​

ValueBehaviorDesktopMobile
above-componentFull-width row outside the widget, above everything✅✅
above-searchFull-width row inside the header, above the search bar (pushes search down)✅✅
beside-chipsRight of the filter chips, in-header (desktop default)✅—
header-bottomFull-width row inside the header, below all filter UI✅✅
below-componentFull-width row outside the widget, below everything✅✅
splitSlot 1 → above-component, Slot 2 → below-component (mobile only)—✅

beside-chips needs horizontal room, so if it's selected on a narrow container it degrades to header-bottom. The above-component / below-component / split anchors render outside the widget container, so they do not affect the map height (e.g., a 700px map stays 700px; ads take additional space).

Legacy values (still accepted, normalized on read): above → above-component, below → below-component, header → header-bottom.

# Custom request: two ads in one row above the search bar, in the header (desktop)
/embed/map-grid?slug=austin&theme=lynnwood&desktopAdPlacement=above-search

# Different placement per breakpoint: beside chips on desktop, stacked above on mobile
/embed/map-grid?slug=austin&theme=lynnwood&desktopAdPlacement=beside-chips&mobileAdPlacement=above-component

# Split on mobile: one ad above the component, one below
/embed/map-grid?slug=austin&theme=lynnwood&mobileAdPlacement=split

Visitor Feedback​

Feedback mode lets visitors tap the map to drop a pin and leave a note. It adds a prompt across the top of the map and a bar of pin types along the bottom.

With the built-in form, pins stay in the visitor's browser for that visit; the embed does not save them. To collect responses, set feedbackProvider=tally and feedbackFormId to your Tally form. The form receives the pin's lat, lng, pin_type and location_label as URL parameters.

ParameterTypeDefaultDescription
feedbackbooleanfalseTurn on feedback mode. The other feedback* parameters apply only when it is on.
feedbackTitlestring-Small heading above the prompt.
feedbackSubtitlestring"Tap the map to leave feedback"Prompt across the top of the map.
feedbackHelperTextstring-Hint under the pin buttons. By default it changes with the number of pins placed.
feedbackPresetstring"thumbs"Pin types: thumbs (Thumbs Up / Thumbs Down), chill_dicey (Chill / Dicey) or civic (Highlight / Hazard / Idea).
feedbackPositiveLabelstringpresetLabel of the first pin type.
feedbackNegativeLabelstringpresetLabel of the second pin type.
feedbackCommunitybooleantrueShow placed pins on the map, with an on/off toggle. false hides both.
feedbackFilterbooleanfalseShow chips that filter the pins by type.
feedbackUpvotingbooleantrueShow an "Agree with this spot" button on a placed pin.
feedbackPhotosbooleantrueAdd a photo-link field to the built-in form.
feedbackProviderstring"native"tally opens your Tally form in place of the built-in form. Any other value uses the built-in form.
feedbackFormIdstring-Your Tally form ID. Needs feedbackProvider=tally.
/embed/map-grid?slug=austin&feedback=true&feedbackPreset=civic&feedbackSubtitle=Where%20should%20we%20add%20a%20bench%3F

Advanced​

ParameterTypeDefaultDescription
heatmapbooleantrueEnable heatmap functionality
showExplorebooleantrueShow explore features
showEventsbooleantrueShow events on map
showPlacesbooleantrueShow places on map

Admin Display Settings (logged-in users only)​

The Advanced panel exposed in the Filters bar to logged-in users surfaces display toggles that change what appears in the embed:

  • Show unapproved — drops is_approved=true from API queries
  • Show closed places — drops is_closed=false (places only)
  • Hide items without images
  • Min completeness score
  • Show items outside boundary (map-grid only — overrides the existing showMarkersOutOfBoundary cascade)

These are admin-only and intentionally have no URL surface. The toggles exist solely in the Advanced panel for logged-in users. User overrides are persisted per-embed-instance in localStorage. Cascade for resolution: user override (panel) > theme default > code default.

The persistence scope is keyed by a hash of themeName + type + listId + cityId + boundary + embedInstance. Two identically-configured iframes on the same host page share state by design; pass embedInstance=foo (URL param) to force separation.

ParameterTypeDefaultDescription
embedInstancestring-Optional opaque suffix used to give two otherwise-identical embeds independent admin-override scopes.
hideNoImageItemsbooleanfalsePre-existing public param; logged-in users can also override via the panel.
showMarkersOutOfBoundaryboolean(theme/auto)Pre-existing public param (see Map Display); logged-in users can also override via the panel.

Developer guide for adding a new admin display toggle: web/src/hooks/useAdvancedDisplaySettings.ts.


Not URL-Controllable​

The following features require complex configuration that cannot be easily passed via URL parameters:

Complex Objects​

  • Custom layer paint/layout properties - Layer styling beyond visibility requires nested objects
  • Custom GeoJSON boundaries - Must be fetched from API via slug
  • Custom combined taxonomies - Complex hierarchical taxonomy configurations
  • Custom filters array - Advanced filter configurations with custom logic

Runtime Features​

  • Selected items state - Managed internally based on user interaction
  • Search term state - User input, not initial URL param
  • Current view state - Changes as user toggles map/grid
  • Focused/hovered items - Managed by user interaction
  • "Events at this Venue" carousel - Always fetched for places in the details panel (useEventsByPlaceSlug, ungated). There is no showVenueEvents param; the only way to suppress it is the per-place membership-tier feature show_venue_events: false

Theme-Dependent​

  • Tooltip styling - Controlled by theme's map.boundaryTooltip config
  • Clear button styling - Controlled by theme's map.boundaryClearButton config
  • Accent colors - Controlled by theme's accent property
  • Card themes - Controlled by theme's cards configuration

API-Dependent​

  • Specific item IDs - Cannot pre-select specific items by ID via URL
  • Custom boundary data - Must use slug to fetch boundary from API
  • Taxonomy term details - Fetched from API, including colors and hierarchy

Sticky-Header Offset (scrollToTopOffset)​

Applies to data-resize="true" embeds. When a visitor scrolls down and clicks a card (in the grid, calendar, or a map popup), 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 map-grid 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/map-grid?slug=austin&scrollToTopOffset=96

Example URLs​

Basic Places Map​

/embed/map-grid?slug=austin&type=places

Events with Filters​

/embed/map-grid?slug=dc&type=events&showVibeFilter=true&showDateRangeSelector=true

3D Terrain with Snow​

/embed/map-grid?slug=denver&terrain3d=true&terrainExaggeration=1.5&snow=0.7

Clustered Markers with Custom Boundary Style​

/embed/map-grid?slug=sf&shouldCluster=true&clusterRadius=50&boundaryLineColor=%23ff6600&boundaryLineWidth=3

Grid View with Custom Columns​

/embed/map-grid?slug=la&initialView=grid&gridColumns=4&shownAtStart=20

Rain Effect with Hidden Labels​

/embed/map-grid?slug=seattle&rain=0.6&hideLayers=poi-label,road-label
/embed/map-grid?slug=nyc&type=places&terrain3d=true&buildings3d=true&shouldCluster=true&showVibesOnCards=true&boundaryLineColor=%234a90e2&boundaryLineWidth=2&markerLabels=featured&theme=dark

Notes​

  1. Boolean parameters accept: true, false, 1, 0, "true", "false"
  2. Colors can be passed without the # prefix (e.g., dotsColor=ff0000 or dotsColor=%23ff0000)
  3. Arrays are comma-separated strings (e.g., vibes=chill,artsy)
  4. Theme defaults - Many parameters have theme-based defaults; only specify to override
  5. Parameter precedence: URL params > Theme defaults > Built-in defaults

PostMessage Events​

The /embed/map-grid embed communicates with the parent window via window.parent.postMessage(payload, '*'). Common payload type values include card-clicked, marker-clicked, view-changed, polygon-selected, and filters-changed. All payloads include an embedId: "map-grid" field.

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 === "map-grid" and event.data.type) rather than event.origin.

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


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/map-grid?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.