Grid URL Parameters
The /embed/grid endpoint renders an EventsGrid component that displays places or events in a filterable grid layout.
Base URL
/embed/grid?slug=<boundary-slug>
Required Parameters
| Parameter | Type | Description |
|---|---|---|
slug OR boundary | string | Location boundary slug (e.g., "austin", "sf", "denver") |
list | string | Alternative: List slug that provides configuration from Lists API |
Note: Either slug/boundary OR list must be provided. When using list, if the list has an associated organization, that organization's boundary will be used automatically.
Content & Data Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
type | string | "places" | Content type: "places" or "events" |
vibes | string | - | Comma-separated vibe filters (e.g., "chill,artsy") |
categories | string | - | Comma-separated category filters |
tags | string | - | Comma-separated tag filters |
editorial_categories | string | - | Editorial category filters (always applied server-side) |
featured | boolean | false | When true, only show featured places/events |
dist / radius | number | - | Radius in meters for proximity search |
search / searchTerm | string | - | Initial search term |
hideNoImageItems | boolean | false | Hide items without images |
tiers | string | - | Filter by membership tier slugs. Comma-separated (e.g., "basic,premium"). Use "non-member" for items with no tier. |
ordering / sort | string | "-score_combined" | Sort order for results (see below) |
Sort Order (ordering / sort)
Controls how places are sorted in the grid.
| 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) |
Filter Behavior Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
strictFilter | boolean | false | When true, taxonomy filters are applied server-side (AND logic). When false, filters are client-side (OR logic). |
onlyShowPassedTaxonomies | boolean | false | When true, filter chips only show values passed via URL (plus subcategories for hierarchical taxonomies). |
filterBehavior | string | "trapped" | Only applies when strictFilter=true. Controls how users can navigate taxonomy filters: |
Filter Behavior Options:
"trapped"- User is locked within the passed taxonomy values and their children"selected"- Passed filter values are pre-selected, but user can deselect and explore other options"open"- All taxonomies shown, passed values are not pre-selected
Grid Display Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
gridColumns | number | 3 | Number of columns in the grid |
shownAtStart | number | 99 | Number of items shown initially (before "Load More") |
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. |
Filter UI Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
showSearchFilter | boolean | true | Show the search input |
showVibeFilter | boolean | true | Show the vibes filter |
showCategoryFilter | boolean | auto | Show the category filter (auto-enabled for places) |
showTagFilter | boolean | true | Show the tags filter |
showItemCountOnFilters | boolean | true | Show item counts on filter chips |
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) |
filterViewMode | string | "horizontal" | Filter layout: "horizontal" or "tabbed" |
filterSelectionMode | string | "auto" | Selection mode: "single", "multiple", or "auto" |
multiSelectTaxonomies | array | [] | Taxonomy slugs that allow multi-select (e.g., ["vibes","tags"]) |
taxonomySortOrder | string | "count" | Sort order for taxonomy chips (see below) |
Taxonomy Sort Order (taxonomySortOrder)
Controls how filter chips are sorted. Default is count (most items first).
Format: "taxonomy:order,taxonomy:order"
Values:
| Value | Description |
|---|---|
count | Default. Sort by item count (most items first), then alphabetically |
alpha | Alphabetical sorting (theme order → color → A-Z) |
Example: taxonomySortOrder=vibes:alpha,categories:alpha,tags:alpha for all alphabetical.
Date Filter Parameters (Events Only)
| Parameter | Type | Default | Description |
|---|---|---|---|
showDateRangeSelector | boolean | true | Show date range selector (only for type=events) |
dateFilterOptions | array | ["upcoming","today","weekend","next_week","month"] | Available date filter options |
groupRecurringEvents | boolean | false | Group recurring events to show only next occurrence |
recurringBadgeLinkTo | string | "grid-filter" | Where recurring badge click navigates: "grid-filter" (filter in place) or "event-series-page" (navigate to series page) |
Date Boundary
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/grid?slug=austin&type=events&dateBoundaryEnd=%2B14d
# Next 3 months of events
/embed/grid?slug=austin&type=events&dateBoundaryEnd=%2B3m
# Events between specific dates
/embed/grid?slug=austin&type=events&dateBoundaryStart=2026-06-01&dateBoundaryEnd=2026-09-01
Note: The + character must be URL-encoded as %2B in query strings.
Past Event Window
Controls how long after an event's end time it remains visible in the grid. Default behavior 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/grid?slug=austin&type=events&pastWindow=360
# Show all events from the past week onward
/embed/grid?slug=austin&type=events&pastWindow=10080
# Show every event ending on/after June 1, 2026
/embed/grid?slug=austin&type=events&pastCutoff=2026-06-01T00:00:00
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=truefrom API queries - Show closed places — drops
is_closed=false(places only) - Hide items without images
- Min completeness score
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. Hide items that don't have images. Logged-in users can also override via the panel. |
Developer guide for adding a new admin display toggle:
web/src/hooks/useAdvancedDisplaySettings.ts.
Card Display Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
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-titleinstead.
| subtitleSource | string | "none" | Source for card subtitle: "none", "category", "address", etc. |
| 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 on cards |
| smartCrop | boolean | true | ImageKit AI smart crop (fo-auto). Set false for deterministic center crop |
| linkToExternalUrl | boolean | false | Open each card's source URL (event source, place website) in a new tab instead of the internal single-post page. Falls back to the internal permalink when no source URL is set. |
Updates Display
| Parameter | Type | Default | Description |
|---|---|---|---|
showUpdates | boolean | false | Enable updates display on cards |
updatesDisplayMode | string | "badge" | Display mode: "badge", "text", or "both" |
updatesFilterTypes | string | - | Comma-separated types: Update,Offer,Clue,Sponsor,Special |
Theme Parameter
| Parameter | Type | Default | Description |
|---|---|---|---|
theme / themeName | string | "default" | Theme slug for styling |
Example URLs
Basic Places Grid
/embed/grid?slug=austin&type=places
Events with Date Filters
/embed/grid?slug=dc&type=events&showDateRangeSelector=true
Grid with Custom Columns
/embed/grid?slug=la&gridColumns=4&shownAtStart=20
List-Based Grid
/embed/grid?list=my-curated-list&gridColumns=3
Filtered by Vibes (Client-Side)
/embed/grid?slug=sf&vibes=chill,artsy&showVibeFilter=true
Strict Filtering (Server-Side)
/embed/grid?slug=sf&strictFilter=true&categories=food&vibes=chill
Trapped Filter Behavior
/embed/grid?slug=austin&strictFilter=true&filterBehavior=trapped&categories=food
Custom Theme and Display Options
/embed/grid?slug=denver&theme=dark&showVibesOnCards=true&showAddressOnCards=true
Full Featured Example
/embed/grid?slug=nyc&type=events&gridColumns=3&shownAtStart=50&showVibesOnCards=true&showDateRangeSelector=true&filterViewMode=horizontal&theme=default
PostMessage Events
The embed communicates with the parent window via postMessage:
| Event Type | Description | Data |
|---|---|---|
"card-clicked" | User clicked a card | { embedId: "grid", data: <item> } |
Example Parent Window Handler
window.addEventListener("message", (event) => {
if (event.data.embedId === "grid") {
switch (event.data.type) {
case "card-clicked":
console.log("Card clicked:", event.data.data);
break;
}
}
});
Embedding
Basic iframe Embed
<iframe
src="https://vibemap.com/embed/grid?slug=austin&type=places"
width="100%"
height="600"
frameborder="0"
style="border: none;"
></iframe>
Responsive Embed
<div style="position: relative; width: 100%; padding-bottom: 75%;">
<iframe
src="https://vibemap.com/embed/grid?slug=austin"
style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: none;"
></iframe>
</div>