Map

How to embed, configure, and use the Mosaic Map component.

Overview

Mosaic is a Salesforce-native geospatial mapping platform built around two components:

Mosaic: Map — the map itself. Drop it on any App Page, Record Page, or Experience Cloud page and point it at a configured map.
Mosaic: Map Preview — a dropdown selector that lists every map in your org and embeds the chosen one. Useful for an "explore everything" landing page.

A "map" in Mosaic isn't built in code — it's assembled from records. You define layers (points or regions), populate them with bytes (individual features), and link them to a map via settings records. The map reads that configuration at runtime and renders the result.

End users get search, filters, bookmarks, dark/light themes, and inline editing out of the box. The map also handles clustering, popovers, runtime CSV and GeoJSON uploads, Google Places search, and AI-assisted address parsing.

Adding the Map to a Page

In App Builder, drag Mosaic: Map onto your page layout.
Set the Map Unique Name property to match a map you've configured in records (see Configuring a Map).
Optionally set Style Configurations to a JSON string for sizing (e.g. {"height": "80vh", "minHeight": "400px"}).
Save and Activate.

To let users pick which map to load, use Mosaic: Map Preview instead — it shows a dropdown of every configured map and renders the selected one. Available on App Pages only.

Note: If the map component has no explicit height and its parent container doesn't define one either, the map will collapse. Always set a height somewhere — either in Style Configurations or on the parent container.

Configuring a Map

A map is a collection of layers grouped under a shared Map Unique Name. The entire setup is record-based — no code, no deployment.

1. Assign the Permission Set

Grant the Mosaic Admin permission set to anyone who needs to manage maps and layers. End users only need read access on the underlying data; they don't need this permission set to view a map.

2. Configure API Keys

Open the FL Mosaic custom metadata type and create a record named global (or update the existing one):

Field	Required for	Notes
Mapbox API Key	Tile rendering	Must have access to the Mapbox styles you intend to use.
Google Maps API Key	Google Places search; Save as Account	Enable the Places API in Google Cloud Console.
Flourish API credentials (`FL_API_*`)	Reserved for future integrations	Optional.

3. Create One or More Layers

Open the Mosaic Layers tab and create a Mosaic Layer record for each layer you need. See Layers for full details on geometry types, recall types, and field reference.

4. Link Layers to a Map

Open the Mosaic Settings tab. For each layer in the map, create a new Mosaic Setting:

Field	Value
Map Unique Name	Your chosen identifier (e.g. `customer-overview`). Use this same value when placing the component on a page.
Type	`Component`
Key	`layer`
Layer	Look up the Mosaic Layer to include.

Optionally add another row with Type blank, Key = label, and Value = the human-readable map name. The Map Preview dropdown reads this label.

That's it — drop Mosaic: Map on a page, set Map Unique Name to customer-overview, and the map renders.

Layers

Two axes drive a layer's behavior: what it renders (Geometry Type) and where its data comes from (Recall Type).

Geometry Type

Value	Renders as
`Point`	Markers (clustered automatically when zoomed out).
`Region`	Polygon overlays from a GeoJSON file.

Recall Type

Value	Best for	Trade-offs
`Bytes`	Curated, relatively static data; large volumes	Faster load; data lives in Mosaic Byte records. Required if you want users to add points at runtime.
`Query`	Live Salesforce records (Accounts, Contacts, Cases, etc.)	Always current; bound by SOQL row limits and query performance. Read-only from the map UI.

Layer Fields Reference

Field	Applies to	Description
Name	All	Display name in the legend.
Unique Name	All	Stable external key. Auto-generated for layers created from runtime uploads.
Geometry Type	All	`Point` or `Region`.
Recall Type	All	`Bytes` or `Query`.
Point Icon URL	Point	Public URL to the marker icon (PNG or SVG).
Point Popover Variant	Point	`Fields`, `Chronicle`, or `Google Search`. See Point Popovers.
Point Popover Configs	Point	JSON config. For Chronicle: `{"templateId": "<id>"}`.
Point Configs	Point	JSON for advanced point options.
Region GeoJSON URL	Region	Publicly accessible GeoJSON FeatureCollection.
Region ID Property	Region	Property in the GeoJSON `properties` block that joins to the Byte's Region ID field.
Region ID Label / Region Value Label	Region	Friendly labels for the data tooltip (e.g. "Zip Code", "Population").
Region Color Map	Region	JSON object mapping region values to hex colors for choropleth shading.
Query SObject Name	Query	The Salesforce object to query (e.g. `Account`, `Contact`).
Query Where	Query	A SOQL `WHERE` clause without the keyword (e.g. `Type = 'Customer'`).
Query Lat / Query Lng	Query, points	API names of the lat/lng fields on the source object.
Query Region Id / Query Region Value	Query, regions	API names of the region-id and value fields.
Query Metadata Fields	Query	Comma-separated API names, or `*` to include every field on the object.

Tip: Setting Query Metadata Fields to * is a quick way to surface everything in the popover without listing fields by hand. Address/Location field groups, Id, and CreatedDate are filtered out automatically.

Loading Data

There are two ways to populate a Bytes-mode layer: bulk-load Mosaic Byte records directly, or upload data at runtime through the map UI.

Mosaic Byte Fields

Field	Required	Description
Layer	Yes	Master-detail to the parent layer.
Lat / Lng	Points	Coordinates.
Region Id	Regions	Joins to a feature in the layer's GeoJSON.
Region Value	Regions	Drives choropleth coloring through the layer's color map.
Color	No	Hex color override for an individual feature.
Label	No	Auto-generated if blank. Shown in the popover header and search results.
UUID	No	Auto-generated when the record is saved.
Metadata	No	JSON payload that drives the popover, search index, and filter property list.

Metadata Format

The Metadata field accepts two formats:

Object format — keys become field names. The popover auto-humanizes them for display (e.g. Billing_Street__c → "Billing Street").

{
    "Name": "Acme Corp",
    "Industry": "Tech",
    "Billing_Street__c": "100 Main St"
}

Array format — use this when you want explicit display labels or need to declare data types so the popover picks the right input control.

[
    { "name": "Name", "label": "Company Name", "value": "Acme Corp" },
    { "name": "Website", "label": "Site", "value": "https://acme.com", "apexDataType": "URL" }
]

Runtime Uploads

The fastest way to bulk-load data is the upload modal. From the Regions & Points panel, click the upload icon next to Points or Regions.

Points require a CSV with Lat and Lng columns. Every other column becomes searchable/filterable metadata.

Regions require a GeoJSON FeatureCollection (.geojson or .json). Once loaded, pick the Region ID property that uniquely identifies each feature, and optionally provide a Region ID label for display (e.g. "Zip Code", "County Name").

Newly uploaded layers are marked Session — they live only in the browser. To persist them, open the layer's action menu and choose Save to Salesforce.

Point Popovers

Clicking a point opens a details popover. The header shows a contextual action bar; the body renders one of three variants determined by the layer's Point Popover Variant field.

Action Bar

Buttons appear based on context:

Button	Shown when
Go to Record	Metadata contains an `Id` field. Opens the Salesforce record in a new tab.
Edit / Done	Variant is `Fields`. Toggles inline edit mode.
Save as Account	Variant is `Google Search`. Creates an Account from the place data.
Add to Layer	Variant is `Google Search`. Saves the place as a point on a Bytes-mode layer.
Google Maps	Variant is `Google Search` and a `place_id` is present. Opens the place on Google Maps.

Variants

Variant	Use when	Notes
Fields	Default — auto-renders metadata as a form	Field types are inferred from `apexDataType` first, then value heuristics (URLs become links, numbers right-align, booleans become toggles, long strings become textareas). Click Edit to modify values; saves persist back to Salesforce.
Chronicle	You have a Chronicle form template to embed	Set `{"templateId": "<id>"}` in Point Popover Configs. Form fields are prefilled from the point's metadata.
Google Search	Surface external Google Places results	Reserved for points sourced from POI search. Displays Categories, Business Status, and "Open Now" when available.

Inline Editing

In the Fields variant, click Edit to flip every field into edit mode. Change values, then click Done — only changed fields are sent back to Salesforce. The update applies to the byte's metadata, the search index, and the filter property cache automatically.

Search

Mosaic offers two complementary search surfaces.

Top Search Bar

Searches across:

Your data — full-text match against label and metadata for every loaded layer.
Google Places — included automatically when the "Always include Google Places" toggle is on; otherwise available on demand via the "Search Google Places for…" link in the dropdown.

Clicking a result from your data flies the map to it and opens its popover. Clicking a Google result drops a yellow marker, flies to the location, and opens the Google Search popover — from there you can save it as an Account or add it to a layer.

Search Panel (Side Nav)

Three sub-features:

Places of Interest — type a keyword (e.g. "churches", "schools") and press Enter to query Google Places in the current map view. Results appear as a dismissible POI layer with yellow markers.
Regions & Points — pick a dataset, optionally scope to a single property, type a keyword, and press Enter. Each search becomes a pill at the bottom; click between pills to switch result sets.
Search Settings — toggle "Always include Google Places in search bar results."

Filters

Each point layer with metadata properties exposes a filter funnel icon. Click it to open the filter panel for that layer.

A filter clause has three parts:

Property — any metadata field on the layer.
Operator — typed by property: text gets equals / contains / starts with; numbers get greater than / less than; dates get before / after; and so on.
Value — skipped for value-less operators like is blank.

Click Add Filter to apply. Filter pills appear below — click a pill to toggle it on/off without deleting, or click the X to remove it.

If other layers share the same properties, an Apply these filters to other layers section lets you check boxes and apply the active filter set to those layers in one click.

Bookmarks

Bookmarks let users collect points and regions across layers into named sets for later review.

In the Bookmarks panel, type a name and click + to create a set. New sets start as Session (in-memory only).
With the set focused, hold the B key and click points or regions on the map to add them. Click again to remove.
Toggle Only show bookmarked items to hide everything else from the map view.
Click Save Set to persist to Salesforce, or Delete Set to discard.

Saved bookmark sets persist across sessions and remain available the next time the map is opened.

Note: The B-key shortcut requires a focused set. Open the Bookmarks panel and click a set first — otherwise B+click won't do anything.

Settings

The Settings panel exposes user-adjustable preferences.

Setting	Effect
Theme	Switches the basemap style (light, dark, satellite — depending on what's enabled in your Mapbox account).
Toggle Fullscreen	Expands the map to fill the browser viewport.

The pin button on the map overlay saves the current center and zoom as the default starting view. Each user's pinned location is saved per-user, so different users can have different home views on the same map.

Map Preferences (Admin)

User-facing preferences are saved as Mosaic Settings records. Mosaic recognizes the following preference keys:

Key	Value	Effect
`label`	`"Customer Overview"`	Display name in the Map Preview dropdown.
`mapTheme`	`"light"`, `"dark"`, etc.	Default basemap style.
`defaultMapStart`	`{"lat": 29.76, "lng": -95.37, "zoom": 11}`	Default center and zoom on load.
`bookmarks`	(managed by the app)	User-saved bookmark sets.
`includeGoogleSearch`	`"true"` / `"false"`	Whether top-bar searches always include Google Places.

Most preferences are written automatically when users change settings or pin a location. Edit them manually only when seeding initial state for new maps.

Time Series

When time-series datasets are configured for a map, a Time Series tab appears in the side nav. Users select an aggregation level (day / week / month) and an aggregation type, then click a dataset title to render a timeline along the bottom of the map. A play button steps through dates, animating the map as values change over time.

If no time-series datasets are configured, the tab shows a "no datasets available" message.

Keyboard Shortcuts

Shortcut	Action
B + click	Add or remove a point/region from the focused bookmark set

Troubleshooting

The map renders but no layers appear. Confirm at least one Mosaic Setting exists with Type = Component, Key = layer, a matching Map Unique Name, and a Layer lookup to a published Mosaic Layer.

A point's popover shows raw JSON. The Metadata field is probably an unstructured string. Save it as a proper JSON object or array, or set the layer's Point Popover Variant to Fields so the auto-renderer can display it properly.

My runtime layer disappeared after I refreshed. Session layers (from CSV/GeoJSON uploads) live only in the browser. Use the layer's action menu → Save to Salesforce to persist them.

The map won't load tiles. Check the Mapbox API Key in the FL Mosaic custom metadata, and confirm that api.mapbox.com is allowed in Remote Site Settings and CSP Trusted Sites.

Google Places search returns nothing. Check the Google Maps API Key in FL Mosaic, confirm the key has the Places API enabled in Google Cloud Console, and that the host is allowed in Remote Site Settings and CSP Trusted Sites. Mosaic surfaces Google's own error message in the toast — read it before assuming a configuration issue.

"Add to Layer" doesn't show my layer. Only Bytes-mode point layers can accept new points from the Google Search popover. Query-mode layers are read-only. Change the target layer's Recall Type to Bytes, or pick a different layer.

"Save as Account" failed. The acting user needs Create permission on the Account object. The Mosaic Admin permission set covers map configuration but not necessarily Account creation in your org.

Top-search-bar Google results have a different label than POI panel results. When you click a single result from the top dropdown, Mosaic uses that result's name as the layer label. When you run a multi-result POI search from the side panel, the layer is named after the search query — because the result set may contain many places.

The B-key shortcut isn't adding bookmarks. Open the Bookmarks panel and click a set first to focus it. B+click only works when a set is focused.

For Developers

This section covers programmatic usage of the Mosaic components when embedding them as child Lightning Web Components.

Component Markup

Map component:

<c-mosaic_map
    map-unique-name="customer-overview"
    style-config='{"height": "80vh", "minHeight": "400px"}'>
</c-mosaic_map>

map-unique-name is the only required attribute. It must match a Map_Unique_Name__c value on your Mosaic Setting records.

Map Preview (picker) component:

<c-mosaic_mapPreviewer></c-mosaic_mapPreviewer>

Takes no properties. Fetches every configured map at load time, renders a dropdown, and mounts the map for the user's selection.

Property Reference

`c-mosaic_map`

Property	Type	Default	Description
`map-unique-name`	`String`	—	Required. Identifies which configured map to load.
`style-config`	`String` (JSON)	—	CSS sizing overrides. Supported keys: `height`, `minHeight`, `maxHeight`.

Both properties are also surfaced as design fields in App Builder.

`c-mosaic_mapPreviewer`

No configurable properties. Available on App Pages only.

Style Config Reference

Key	Description	Example values
`height`	Outer container height	`"80vh"`, `"600px"`, `"100%"`
`minHeight`	Minimum height	`"400px"`
`maxHeight`	Maximum height	`"900px"`

Embedding Examples

Record page — fixed height:

<c-mosaic_map
    map-unique-name="account-territory"
    style-config='{"height": "600px"}'>
</c-mosaic_map>

Full-height sidebar embed:

<c-mosaic_map
    map-unique-name="customer-overview"
    style-config='{"height": "100%", "minHeight": "500px"}'>
</c-mosaic_map>

Experience Cloud pages: Both components support lightningCommunity__Page. Confirm the API user (typically a guest user or community license) has the Mosaic Admin permission set, or at minimum read access to Mosaic_Layer__c, Mosaic_Byte__c, and Mosaic_Setting__c.

Overview​

Adding the Map to a Page​

Configuring a Map​

1. Assign the Permission Set​

2. Configure API Keys​

3. Create One or More Layers​

4. Link Layers to a Map​

Layers​

Geometry Type​

Recall Type​

Layer Fields Reference​

Loading Data​

Mosaic Byte Fields​

Metadata Format​

Runtime Uploads​

Point Popovers​

Action Bar​

Variants​

Inline Editing​

Search​

Top Search Bar​

Search Panel (Side Nav)​

Filters​

Bookmarks​

Settings​

Map Preferences (Admin)​

Time Series​

Keyboard Shortcuts​

Troubleshooting​

For Developers​

Component Markup​

Property Reference​

c-mosaic_map​

c-mosaic_mapPreviewer​

Style Config Reference​

Embedding Examples​