Map-Grid URL Parameters

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

Table of Contents

• Required Parameters
• Content & Data
• Map Viewport
• Map Display
• Locator / Overview Mini-Map
• 3D & Effects (styleConfig)
• Markers
• Location Dots
• Parking Layer
• Place-Amenity Legend
• Clustering
• Grouping (Co-located Markers)
• Boundary
• Filters
• Views
• Card Display
• Theme
• Banner Ads
• Advanced
• Not URL-Controllable

---

Required Parameters

Parameter	Type	Default	Description
slug / boundary	string	-	Location slug for fetching boundary and data (e.g., "austin", "dc", "westwood")
list	string	-	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

Parameter	Type	Default	Description
type	string	"places"	Content type: "places" or "events"
vibes	string	-	Pipe-separated list of vibes to filter by (e.g., "chill|artsy")
categories	string	-	Pipe-separated list of categories to filter by
tags	string	-	Pipe-separated list of tags to filter by
editorial_categories	string	-	Pipe-separated list of editorial categories to include (aliases: editorial_category, editorialCategory)
editorial_categories__exclude	string	-	Pipe-separated list of editorial categories to exclude (e.g., "evanston-history" or "cat-a|cat-b")
featured	boolean	false	When true, only show featured places/events
strictFilter	boolean	false	When true, applies strict taxonomy filtering (AND logic)
onlyShowPassedTaxonomies	boolean	false	When true, filter chips only show values passed via URL (plus subcategories for hierarchical categories)
dist / radius	number	-	Radius in meters for proximity search
hideNoImageItems	boolean	-	Hide items that don't have images
hideRangedEvents	boolean	false	Hide events with a duration longer than 24 hours
tiers	string	-	Filter by membership tier slugs. Comma-separated (e.g., "basic,premium"). Use "non-member" to show items with no membership tier (null).
ordering / sort	string	"-score_combined"	Sort order for results (see below)

Sort Order (ordering / sort)

Controls how places are sorted in the grid/list.

Value	Description
name	Alphabetical by place name (A-Z)
-score_combined	Default. By relevance/popularity score (highest first)
-vibe_count	By number of vibes (most vibes first)
random	Random order (shuffled on each page load)

---

Map Viewport

Parameter	Type	Default	Description
latitude / lat	number	From boundary	Initial map center latitude
longitude / lng	number	From boundary	Initial map center longitude
zoom	number	From boundary	Initial zoom level (0-22)
bearing	number	0	Map rotation in degrees (0-360)
pitch	number	0	Map tilt in degrees (0-85)
zoomMode	string	"fit-boundary"	Initial zoom behavior: "fit-boundary" (fit to boundary polygon), "fit-markers" (fit to all markers), or "custom" (use explicit lat/lng/zoom)
refitMarkersOnFilterChange	boolean	true	When 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:

Value	Behavior
fit-boundary	Default. Fits the map to the boundary polygon returned by the API
fit-markers	Calculates bounds from all marker coordinates and fits the map to show all markers with padding
custom	Uses 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

Parameter	Type	Default	Description
mapStyle	string	Vibemap default	Mapbox style URL (e.g., "mapbox://styles/mapbox/streets-v12")
mapHeight	number/string	"100%"	Map container height (px or CSS value)
mobileMapHeight	number	-	Map height in px on mobile viewports (does not affect desktop). The iframe still grows to fit the whole component — map and cards.
mobileMaxHeight	number	-	Deprecated alias for mobileMapHeight (kept for back-compat).
mobileBreakpoint	number	768	Viewport width threshold for mobileMapHeight (px)
showBoundary	boolean	true	Show boundary polygon on map
showMarkers	boolean	true	Show place/event markers
showMarkersOutOfBoundary	boolean	Auto	Master toggle: show OOB markers everywhere (auto-enabled with radius/strictFilter). Logged-in users can also toggle via the Filters → Advanced panel.
showMarkersOutOfBoundaryOnMap	boolean	(master)	Show OOB markers on the map; falls back to showMarkersOutOfBoundary
showMarkersOutOfBoundaryInSidebar	boolean	(master)	Show OOB places in the sidebar card list; falls back to showMarkersOutOfBoundary
showMarkersOutOfBoundaryInList	boolean	(master)	Show OOB places in the list/grid view; falls back to showMarkersOutOfBoundary
clipToBounds	boolean	true	Inverse 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).
showMapCards	boolean	true	Show info cards when clicking markers
useLegacyBottomCard	boolean	false	Mobile. Keep the classic single bottom card instead of the new bottom sheet (peek header → Featured + full-list carousel; expands to fullscreen in embeds). Per-customer legacy toggle.
showUserLocation	boolean	false	Ask for the visitor's device location, show their blue-dot marker, and add a recenter button (mobile + desktop). Off by default.
showInlineChips	boolean	true	Mobile. Show a taxonomy chip scroller under the search bar, outside the filters menu.
inlineChipsTaxonomy	string	"category"	Which taxonomy the under-search chips show: category, tag, or vibe.
showDateRangePills	boolean	true	Events. Show date-range preset pills (Today, This Week, All, …) under the search bar and in the filters menu; Custom opens the calendar.
sheetTitle	string	"Explore"	Mobile. Override the bottom-sheet peek-header title (e.g. sheetTitle=Explore%20venues). Falls back to theme.map.sheetTitle, then the default.
sheetDefaultState	string	"peek"	Mobile. Default state of the bottom sheet on load: peek (collapsed) or open (expanded).
showHeat	boolean	true	Show heatmap layer
map3d	boolean	false	Legacy 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.

Parameter	Type	Default	Description
showLocatorMap	boolean	false	Show the locator/overview mini-map inset
locatorOverviewBBox	array	Auto-derived	Custom extent [minLng, minLat, maxLng, maxLat] the overview frames (e.g. a whole state). Omit to auto-derive from boundary + view
locatorInteractive	boolean	true	When 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

Parameter	Type	Default	Description
terrain3d	boolean	false	Enable 3D terrain elevation
terrainExaggeration	number	1.0	Terrain height multiplier (0.1-3.0)
buildings3d	boolean	false	Enable 3D building extrusions
hillshade	boolean	false	Enable hillshade relief shading

Weather Effects

Parameter	Type	Default	Description
fog	boolean	false	Enable atmospheric fog effect
fogDistance	number	10	Fog visibility distance (1-20 km)
snow	number/boolean	false	Snow effect intensity (0-1, or true for 0.5)
rain	number/boolean	false	Rain effect intensity (0-1, or true for 0.5)

Layer Visibility

Parameter	Type	Default	Description
hideLayers	string	-	Comma-separated layer IDs to hide (e.g., "poi-label,road-label")
showLayers	string	-	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

Parameter	Type	Default	Description
markerStyle	string	"mixed"	Marker display style: "mixed", "icons", "images", "only_featured"
markerLabels	string	"hide"	Label display: "hide", "featured", "all"
maxImageMarkers	number	Theme default	Max number of image markers to show
maxIconMarkers	number	Theme default	Max 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.

Parameter	Type	Default	Description
showDots	boolean	false	Enable dots at all GeoJSON locations
dotsColor	string	Theme accent	Dot fill color (hex, e.g., "9B59B6" or "#9B59B6")
dotsRadius	number	4	Dot radius in pixels
dotsOpacity	number	1	Dot opacity (0-1)
dotsStrokeColor	string	-	Optional stroke/outline color for dots
dotsStrokeWidth	number	0	Stroke 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.

Parameter	Type	Default	Description
showParkingLayer	boolean	false	Separate 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.

Parameter	Type	Default	Description
showPlaceLegend	boolean	false	Enable the place-amenity legend
placeLegend	array	Theme default	JSON array of legend items (see shape below). Usually set by theme/WP rather than hand-authored URL
placeLegendTitle	string	Legend	Legend panel title
placeLegendShowTitle	boolean	true	Show the panel title text; false hides it (panel stays collapsible via the header chevron)
placeLegendPosition	string	top-right	top-right | top-left | bottom-right | bottom-left
placeLegendCollapsed	boolean	false	Start the legend collapsed (always starts collapsed on mobile regardless of this)
placeLegendInteractive	boolean	false	Informational by default (a key). true adds checkboxes that show/hide places by amenity + filter the map
placeLegendShowOnCards	boolean	false	Also render each place's matching amenity icons on its cards and atop the item-details description
placeLegendActive	array	all items	Comma-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

Parameter	Type	Default	Description
shouldCluster	boolean	false	Enable marker clustering
clusterRadius	number	Theme default	Pixel radius for clustering (typically 35-80)
clusterMaxZoom	number	Theme default	Max zoom level for clustering (integer, typically 14-18)

---

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).

Parameter	Type	Default	Description
enableGrouping	boolean	true	Enable grouping of co-located markers
groupingTolerance	number	3	Distance in meters within which items are considered co-located
spiderModeMaxItems	number	8	Max items for "spider" expansion (circular spread); larger groups show a scrollable list instead

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

Feature	Grouping	Clustering
Purpose	Items at the same address/venue	Visual decluttering of nearby markers
Tolerance	~3 meters (same building)	35-80 pixels (screen distance)
Expansion	Spider web or scrollable list	Zoom to cluster bounds
Color	Purple	Teal (places) or Red (events)
When	Always (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

Parameter	Type	Default	Description
boundaryFilter	string	-	Filter to specific polygon by name (for MultiPolygon boundaries)
showBoundarySelector	boolean	theme / true	Master 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.
showBoundarySelectorList	boolean	true	Show boundary selector dropdown for MultiPolygon boundaries
boundarySelectorLabel	string	"Boundary"	Custom label for boundary selector (e.g., "Neighborhood", "District")
showHoverPopoverOnPolygon	boolean	theme	Enable the hover popover/tooltip on boundary + overlay polygons. Falls back to theme.map.showHoverPopoverOnPolygon (default false).

Styling

Parameter	Type	Default	Description
boundaryFillColor	string	-	Fill color (hex, e.g., "#ff0000" or "%23ff0000" URL-encoded)
boundaryFillOpacity	number	0	Fill opacity (0-1)
boundaryLineColor	string	-	Line color (hex)
boundaryLineOpacity	number	1	Line opacity (0-1)
boundaryLineWidth	number	2	Line width in pixels

---

Filters

Search

Parameter	Type	Default	Description
search / searchTerm	string	""	Pre-populate the search filter with an initial query

Filter Visibility

Parameter	Type	Default	Description
showFilters	boolean	true	Show filter UI
showVibeFilter	boolean	true	Show vibes filter
showCategoryFilter	boolean	Auto	Show categories filter (auto for places)
showTagFilter	boolean	true	Show tags filter
showAllTags	boolean	false	When true, force the tag filter row on and bypass tagsToInclude/tagsToExclude (URL + theme), showing every tag. Theme equivalent: theme.filters.showAllTags.
tagsToInclude	string	theme	Comma-separated allowlist of tag slugs/names — only these tags appear in the tag filter. Falls back to theme.filters.tagsToInclude. Ignored when showAllTags=true.
tagsToExclude	string	theme	Comma-separated blocklist of tag slugs/names to hide from the tag filter. Falls back to theme.filters.tagsToExclude. Ignored when showAllTags=true.
showSearchFilter	boolean	true	Show search input
showTopLevelFilters	boolean	true	Show filters at top level (vs inside map)
showItemCountOnFilters	boolean	true	Show item counts on filter chips
showTierFilter	boolean	false	Show membership-tier filter chips (filter items by membership tier).
showLogin	boolean	true	Show the login/account button in the filters bar (alias: showLoginButton). Falls back to theme.layout.showLogin.
loginButtonSize	number	32	Avatar size (px) of the login/account button.
visibleCats	number	-	Max categories to show before "Show More" pill (undefined = show all)
visibleVibes	number	-	Max vibes to show before "Show More" pill (undefined = show all)
visibleTags	number	-	Max tags to show before "Show More" pill (undefined = show all)

Filter Behavior

Parameter	Type	Default	Description
filterViewMode	string	"horizontal"	Filter layout: "horizontal" or "tabbed"
filterSelectionMode	string	"auto"	Selection mode: "single", "multiple", "auto"
filterBehavior	string	"trapped"	Navigation behavior when taxonomy filters are passed (see below)
multiSelectTaxonomies	array	[]	JSON array of taxonomy names that allow multi-select
taxonomySortOrder	string	"count"	Sort order per taxonomy (see below)

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:

Value	Description
count	Default. Sort by item count (most items first), then alphabetically
alpha	Alphabetical 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.

Value	Description
trapped	Default. 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.
selected	The passed filter is pre-selected, but user can deselect it to see parent-level filters. Allows escaping the passed taxonomy.
open	Current 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.

Parameter	Type	Default	Description
vibesLabel	string	"Vibes"	Custom display name for the Vibes taxonomy
categoriesLabel	string	"Categories"	Custom display name for the Categories taxonomy
tagsLabel	string	"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

Date Filters (Events)

Parameter	Type	Default	Description
showDateRangeSelector	boolean	true	Show date range selector (events only)
dateFilterOptions	array	["upcoming","today","weekend","next_week","month"]	Available date filter options

Date Boundary (Events)

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

Parameter	Type	Default	Description
dateBoundaryStart	string	-	Events before this date are excluded. Accepts yyyy-MM-dd or relative offset.
dateBoundaryEnd	string	-	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.

Parameter	Type	Default	Description
pastWindow	integer (minutes)	90	Minutes 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.
pastCutoff	ISO 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). Three peer Views are available — Map, Grid, and Calendar — selected by the View toggle. The toggle auto-hides when only one View is available. calendar is Events-only (always stripped for type=places).

Parameter	Type	Default	Description
views	string (CSV, ordered)	grid,calendar,map (events) / map,grid (places)	Ordered list of Available views. Order = toggle order; presence = enabled. Tokens: map, grid, calendar. calendar is always stripped for Places. Duplicates are de-duped; an empty/all-stripped result falls back to grid. Legacy list token → grid. Example: views=grid,calendar,map.
defaultView	string	see note	Starting View. Must be one of the (guarded) Available views, else falls back to the first entry. Values: map, grid, calendar.
initialView	string	"map" (when no views/defaultView set)	Deprecated alias for defaultView; honoured only when defaultView is absent. Now accepts map, grid, calendar. Legacy list → grid. When neither views nor defaultView is passed, the embed preserves its long-standing map-first default.
calendarMonths	number (1–12)	theme calendar.monthsToShow → 1	Number of months the Calendar View renders at once.
calendarCardStyle	string	theme calendar.cardStyle → compact	Calendar event card style: compact (default — small thumbnail + accent time + one-line title, no date badge) or card (full ui-components Card).
calendarMaxPerDay	number	theme calendar.maxEventsPerDay → 4	Max events shown per day cell before a "+N more" link. When omitted, resolves from the active theme's calendar.maxEventsPerDay.

Default View note: When neither views nor defaultView is supplied, the embed starts on Map (back-compat). 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.

Parameter	Type	Default	Description
maxWidth	number/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).
gridColumns	number	3	Number of columns in grid view
shownAtStart	number	99	Number of items shown initially
hideSidebar	boolean	false	Hide the sidebar card list (map view only)
showContentModeToggle	boolean	true (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

Parameter	Type	Default	Description
cardStyle	string	"list"	Card style variant
showVibesOnCards	boolean	true	Show vibes on cards
showTagsOnCards	boolean	false	Show tags on cards
showAddressOnCards	boolean	true	Show address on cards

Deprecated: Use subtitle2Source=address&subtitle2Position=below-title instead.

| descriptionLength | number | - | Max description length. If > 0, shows description | | subtitleSource | string | "none" | Subtitle content: "none", "category", "address", etc. | | subtitleSources | string | - | Comma-separated list of sources to combine for the first subtitle when subtitleSource=custom. First-subtitle analog of subtitle2Sources — same token vocabulary, joined with •. | | subtitlePosition | string | "above-title" | Subtitle position: "above-title" or "below-title" | | subtitle2Source | string | content-type default | Data source for the second subtitle. Default: places="address", events="none". Options: "none", "category", "tag", "vibe", "address", "venue", "date" (date only, e.g. "Jun 15th"), "start_date_time" (date + time, e.g. "Jun 15th • 7:00 PM"), "price", "custom" (combine multiple — see subtitle2Sources) | | subtitle2Sources | string | - | 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" | | subtitle2Position | string | "below-title" | Position of the second subtitle: "above-title" or "below-title" | | showRating | boolean | false | Show ratings on cards | | showBookmark | boolean | false | Show bookmark button | | openSinglePost | boolean | false | Open item detail page on click | | randomizeImages | boolean | false | When true, pick a random image; default uses first/featured | | smartCrop | boolean | true | ImageKit AI smart crop. false → center crop | | linkToExternalUrl | boolean | false | Open card source URL in new tab (grid view). Fallback to permalink. | | showVibesInDetails | boolean | true | Show vibes under hero image in item details panel | | useUpdateImages | boolean | false | When 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. | | showTierBadge | boolean | false | Show the membership-tier badge on cards (e.g. "Premium"). | | usePillLayout | boolean | true | For multi-day events, render the date badge as a horizontal pill (date range). Set false for the stacked calendar-style badge. | | ongoingEventShowNow | boolean | false | For ongoing events (started in the past, still running), show the start as "Now" instead of today's date. | | timeBadges | string | - (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. | | showRecurrenceBadge| boolean | false | Show the recurrence label pill (e.g. "Weekly Wed - Sun") on event cards. Off by default. Falls back to theme.cards.showRecurrenceBadge. | | groupRecurringEvents| boolean | false | Collapse 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. |

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.

Value	Badge label	Matches 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.

Parameter	Type	Default	Description
showUpdates	boolean	false	Enable updates display on cards and detail panels
updatesDisplayMode	string	"badge"	Card display mode: "badge", "text", or "both"
updatesFilterTypes	string	-	Comma-separated types: Update,Offer,Clue,Sponsor,Special
updatesPosition	string	"under-vibes"	Detail panel position (see below)
updatesExpanded	boolean	true	Updates 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

Parameter	Type	Default	Description
theme / themeName	string	"default"	Theme slug for styling (e.g., "dark", "minimal")

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

---

Banner Ads

Parameter	Type	Default	Description
desktopAdPlacement	string	"beside-chips"	Where banner ads appear on wide containers (> 1024px) — see below
mobileAdPlacement	string	"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

Value	Behavior	Desktop	Mobile
above-component	Full-width row outside the widget, above everything	✅	✅
above-search	Full-width row inside the header, above the search bar (pushes search down)	✅	✅
beside-chips	Right of the filter chips, in-header (desktop default)	✅	—
header-bottom	Full-width row inside the header, below all filter UI	✅	✅
below-component	Full-width row outside the widget, below everything	✅	✅
split	Slot 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

---

Advanced

Parameter	Type	Default	Description
heatmap	boolean	true	Enable heatmap functionality
showExplore	boolean	true	Show explore features
showEvents	boolean	true	Show events on map
showPlaces	boolean	true	Show 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.

Parameter	Type	Default	Description
embedInstance	string	-	Optional opaque suffix used to give two otherwise-identical embeds independent admin-override scopes.
hideNoImageItems	boolean	false	Pre-existing public param; logged-in users can also override via the panel.
showMarkersOutOfBoundary	boolean	(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

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.

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, 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

Full Featured Example

/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.