Location Map Block

Put an interactive map on a page showing one location or a whole list of them.

moderate Data & Content

What it adds

A reusable map block rendering one or many pinned locations, with a static fallback and a text address alternative.

What your agent is told to do

1
The app already has Mapbox Geocoding and Google Places Address Lookup. Turn addresses into coordinates through the existing integration and store the result on the record; do not add a second geocoding path for this block.
2
Make the block take either a single location or a collection, and render the same component for both. A one-pin map is a collection of one, not a separate feature.
3
Reserve the block's height before the map initialises so the surrounding page does not jump when tiles arrive. The placeholder should occupy exactly the space the map will fill.
4
Render the address as real text next to or beneath the map, with a link that opens the location in the viewer's own maps application. The map is the decoration; the address is the information.
5
Do not load map tiles or scripts until the block is close to the viewport. A map at the foot of a long page should not cost every visitor a download and a paid tile request they never look at.

Edge cases it handles

The map provider can be blocked by a network, an extension, or an outage. Detect that initialisation did not complete and swap in a static image or a plain styled address card, rather than leaving a grey rectangle that never resolves.
Pins that sit close together merge into an unreadable clump at low zoom. Cluster them into a labelled group that expands as the viewer zooms in, and make sure the count on the cluster is accurate.
A full-width map on a phone captures the page scroll and traps the visitor. Require a deliberate gesture or a tap to activate panning and zooming, and restore normal page scrolling when the map loses focus.
Geocoding the same address on every render burns quota and adds latency. Cache the resolved coordinates against the address and only re-resolve when the address text actually changes.
A map conveys nothing to a screen reader. Provide the address, and for a collection the list of locations, as readable text in the document rather than relying on the map canvas or on alt text alone.
An address that cannot be geocoded must still render something useful. Show the address text and omit the pin instead of dropping the block or centring the map on the middle of the ocean.
Interactive maps are heavy and animate on load. Respect the app's Reduced Motion Support by skipping fly-to animations and rendering the map already at its final position.
Precise pins on private residences expose more than intended. Where a location is a person's home, offer an approximate radius rather than an exact point.

Definition of done

The block renders a single location and a list of locations through one component.
Coordinates come from the app's existing geocoding integration and are cached against the address.
A blocked or failed map provider degrades to a static image or address card, never a blank area.
The page does not shift when the map loads, and the map does not load until near the viewport.
Overlapping pins cluster with accurate counts at low zoom.
Page scrolling is not hijacked on touch devices.
Every location is available as readable text with a link to an external maps application.
The feature matches the existing design system.
No existing functionality is broken.

Related features

Weather Widget

Record Merge

QR Code Generator

How it works

1

Copy the link

Grab the Markdown instruction URL for this feature.
2

Give it to your AI

Paste it into Claude Code, Cursor, v0, Lovable — whatever you build with.
3

It inspects, then implements

Your agent reads your existing app first, then adds the feature to fit it.

Works with your stack

These instructions are written to adapt. They tell the agent to detect your framework, match your existing design system, and reuse what you already have — rather than assuming a particular stack.

Need it tighter than that? Customize the feature and tell it exactly what you're running.