CMS Locations Map · Documentation · Version 1.2.1
Your locations, straight from the CMS.
How the Map and Map Pin work together, connecting your CMS, filters, map styles and brand colours, popups, near me, and every setting. No API key.
01
Start here.
Add it to your project. Open the link in your purchase email (or the Marketplace page). You get two components: CMS Locations Map (the map) and Map Pin.
See it working. Drop the map on a page and preview. It shows five demo offices (Madrid, Barcelona, Valencia, London and Lisbon) so you can style it before connecting anything.
Connect your CMS. Add Latitude and Longitude to your collection, put a Map Pin inside your Collection List item and bind it. Connect your CMS, step by step, below.
Make it yours. Pick a map style or your brand colours, a marker, the popup texts and the fonts. Then turn Manual pins off and publish.
02
How it works.
Two components that talk to each other through a shared Map ID (map by default).
Draws the map, the markers, clusters, popups and the Near me button.
Sits inside each item of a native Framer Collection List. It’s invisible on the published site. It tells the map: this item is here, with this title, address and link.
Because each pin lives inside its item, the map always shows exactly what the Collection List shows. Filter, sort, paginate or Load more with Framer’s own tools and the markers follow: an item that leaves the list takes its marker with it. You design the list yourself, with the Collection List, as freely as any other layer.
No API keys, no account, no backend.
Several maps can live on one site, or one page: give each its own Map ID.
Manual pins on the map and CMS pins are shown together. Useful while you build, or for a site without a CMS.
03
Connect your CMS, step by step.
1. Add two number fields
In your CMS collection (Offices, Hotels, Stores…), add two Number fields: Latitude and Longitude.
2. Get the coordinates in 10 seconds
Open Google Maps and find the place.
Right-click exactly on the spot.
The first line of the menu is the coordinates, like 40.41680, -3.70379. Click it: they’re copied.
Paste the first number in Latitude and the second in Longitude.
Shortcut: prefer one field? Add a single Text field (Coordinates), paste the whole line as copied, and bind it to Map Pin’s Or coordinates instead.
3. Put a Map Pin in the Collection List item
Add a Collection List connected to your collection, and design the card as you like.
Drag a Map Pin into the item (inside the card).
Bind its properties to your fields: Latitude, Longitude, Title, Address, Link (the item’s page) and, optionally, Category.
Tip: set the Map Pin to Position: Absolute so it never takes space in the card’s layout.
4. Place the map anywhere
Drop the Map on the same page: above the list, beside it in a two-column layout, or in a sticky column. Keep the same Map ID on the Map and on the Map Pin (map, unless you change both). Preview: your items appear as markers.
Then turn Manual pins off on the Map, so the demo offices go away.
A map without a visible list? Keep the Collection List on the page with Height 0 and Overflow Hidden. Don’t switch its Visible off: Framer doesn’t render hidden layers, so their pins can’t register.
04
Filtering with Framer’s native CMS filters.
Use Framer’s own Collection List filters, sorting, limits, pagination and Load more. Nothing to set up on the map.
Filtered-out items unmount, so their markers disappear.
With Refit on filter on, the map refits to show the pins that are left.
Load more adds markers as new items appear.
An item that appears twice (for example, in two lists) shows one marker.
05
Map styles and brand colours.
All styles come from OpenFreeMap: Light, Bright, Liberty, Dark and Fiord (blue-grey).
Brand colours repaints the Light style with six colours: Land, Water, Roads, Parks, Buildings and Map labels. Pick your site’s colour styles so the map follows your palette. Road numbers and map icons are hidden in this style for a cleaner look.
All, Places only (hides street names, road numbers and points of interest) or None.
Auto writes city and country names in your site’s language when the map knows them (Londres, Lisboa on a Spanish page). Or fix one, keep the style’s default, or use Local names.
06
Markers and clusters.
Marker: Pin, Dot or Image. Image takes any PNG or SVG, like your logo; Image point sets whether its bottom or its centre sits on the location.
Marker, Active and Outline colours. Active is used for the selected marker, the one whose card is hovered, and the keyboard focus ring.
Category colours: optional. Pins whose Category matches (Headquarters, Showroom…) get their own colour.
Clusters: nearby pins join into a number. Click a cluster to zoom in. Cluster radius sets how close is “nearby”; from Cluster until zoom in, every pin shows on its own.
Two items at the same address show a cluster that opens a short list instead of zooming forever.
07
Popups and directions.
Click a marker (or press Enter on it) and a popup opens with the category, title, address, and two links:
Opens the pin’s Link, usually the item’s CMS page. Hidden when the pin has no link.
Opens Google Maps or Apple Maps with the location as destination, in a new tab. Auto uses Apple Maps on Apple devices and Google Maps elsewhere.
All popup texts (View, Directions, Close) are properties, so Framer Localization translates them. Colours, radius, width and three fonts (Title, Body, Link) are yours.
Cards that open the map. On Map Pin, Hover card highlights the marker while the visitor hovers or focuses the card. Focus on click makes a click on the card fly the map to the pin and open its popup; if the map is off screen, the page scrolls to it (Scroll to map). If the whole card is a link, the click goes to the map instead, and View in the popup opens the page. Links and buttons inside the card keep working as usual.
The card is found by itself, looking at most 8 levels up from the Map Pin and never at the rest of the page: the link around the Map Pin, or the Collection List item. If your card is built differently, set Card levels up to pick a parent by hand (Framer adds one wrapper, so it’s usually 2 or 3).
08
Near me and distances.
The Near me button first says why it needs the location (Why text, with Use my location and Not now). Only then does the browser ask for the visitor’s position. The map shows a You dot, flies to the nearest location and opens its popup. If the visitor already allowed it, the map goes straight there.
On Map Pin, turn on Distance to show “1.2 km” in each card. Distance text shapes it: {distance} away, a {distance}…
Sort by distance on Map Pin moves the nearest items to the top of the Collection List.
Distance unit: Auto uses miles in the US and the UK and kilometres elsewhere, or fix one.
Distances are written in the site’s language (1,2 km on a Spanish page).
Browsers only share the position on published sites over HTTPS, and only after the visitor allows it. If they don’t, the button says Location unavailable for a few seconds.
09
Customize the look.
Settings to copy for four common cases.
Map style Light · Labels Places only · Marker Pin · Marker your ink colour · Active your accent · Clusters off · Near me off · Popup radius 4 · Radius 0
Map style Brand colours with your palette · Marker Image (your monogram, Image point Centre) · Category colours for each brand line · Near me on · Directions Auto · Popup width 320
Map style Bright · Marker Dot · Clusters on · Near me on · Map Pin: Distance on, Sort by distance on, Focus on click on · Refit on filter on · Map beside the list in a sticky column
Manual pins on with one location · Initial view Fit all pins · Max fit zoom 15 · Clusters off · Near me off · Zoom buttons off · Scroll zoom off · Popup with Directions only
10
Settings reference.
In the order they appear in the property panel.
Map
Data
Map Pins with the same Map ID appear on this map.
Show the pins typed in Locations, together with CMS pins.
Title, Address, Latitude, Longitude, Link and Category for each one.
View
Fit all pins, or a Fixed centre.
Space kept around the pins when fitting.
Stops a single pin from zooming in too close.
Refits when CMS filters change the pins.
The fixed view, also used when there are no pins yet.
How close the map goes when a card or Near me focuses a pin.
Scrolls to the map when a card focuses a pin off screen.
Map style
Light, Bright, Liberty, Dark, Fiord or Brand colours.
Brand colours only.
All, Places only or None.
Auto, Style default, Local names or a fixed language.
Markers
Marker — Pin, Dot or Image. Pin height, Dot size, Image, Image size, Image point.
Marker, Active, Outline colours.
Category colours — a colour per category.
Clusters
Clusters, Cluster radius, Cluster until.
Cluster, Cluster text colours, Cluster font.
Cluster label — read by screen readers. {count} becomes the number.
Popup
Popup — on or off.
Category, View link, View label, View new tab.
Directions, Directions label, Directions in (Auto, Google Maps or Apple Maps).
Close label.
Popup, Popup text, Popup muted, Popup links colours. Popup radius, Popup width.
Title font, Body font, Link font.
Near me
Near me — on or off.
Near me label, Locating label, Error label, You label.
Why text, Allow label, Cancel label — the short note shown before the browser asks for the location.
Distance unit — Auto, Kilometres or Miles.
You dot colour.
Buttons and gestures
Zoom buttons, Buttons at (Top left, Top right, Bottom left).
Zoom in label, Zoom out label, Zoom group label (read by screen readers).
Buttons, Buttons text colours, Buttons radius, Button font.
Scroll zoom — off locks zooming with the mouse wheel. Buttons, pinch and double-click still zoom.
Ctrl + scroll — the page scrolls past the map; zooming needs Ctrl (⌘ on Mac), and two fingers on phones.
Ctrl hint, Mac hint, Phone hint — the messages shown over the map.
Look
Rounds the map’s corners.
Read by screen readers.
Shown above a plain list of locations when a device can’t draw maps.
Map Pin
Same as the map it belongs to.
Bind to CMS number fields.
One text field with both numbers, as Google Maps copies them. Overrides Latitude and Longitude.
Shown in the popup. Category can also set the marker colour.
Hovering or focusing the card highlights its marker.
Clicking the card flies the map to the pin and opens its popup.
0 finds the card by itself, at most 8 levels up; a number picks a parent by hand.
Shows the distance after Near me. Distance text, Distance colour, Distance font.
After Near me, the nearest items move to the top of the list.
All texts are properties, so Framer Localization translates them.
11
Privacy
Map tiles and styles come from OpenFreeMap (tiles.openfreemap.org): free, no API key, no account, no cookies. Their address is fixed in the code and can’t be changed from the canvas.
Why the map needs a tile host: an interactive map loads map data for the area and zoom on screen. The world at street level is tens of gigabytes, so no component can carry it; every interactive map, Framer’s own Google Maps included, loads tiles from a map host. The requests carry nothing but the tile being drawn: no site data, no CMS content, nothing about the visitor. If the host can’t be reached, the component shows a plain list of the locations.
The map library (MapLibre GL JS 5.6.0), its stylesheet and its worker ship inside the component. Nothing is loaded from a CDN: the only outside address is the tile host.
No other hosts, no analytics, nothing stored.
Near me uses the browser’s own location request. The position stays in the visitor’s browser, in memory, to work out distances. It’s never stored or sent anywhere.
The map keeps the attribution OpenFreeMap © OpenMapTiles Data from OpenStreetMap, which the data’s licence requires. Please don’t hide it.
12
Performance
The map is only created when it gets close to the screen. A map at the bottom of the page costs nothing until the visitor scrolls there.
Markers are light HTML, and clusters keep hundreds of pins readable and fast.
In the Framer canvas you see a light preview with your real pins (Map preview: publish or preview to load tiles). Tiles load in Preview and on the published site.
Hundreds of locations work well. For thousands, use Framer’s pagination or filters so each page shows a few hundred.
13
Troubleshooting
That’s by design. Open Preview or publish to see tiles.
The Map Pin’s Map ID must match the Map’s. Check that Latitude and Longitude are bound: an unbound pin shows “bind Latitude and Longitude” on the canvas.
That’s 0, 0: the item has no coordinates yet.
Latitude and Longitude are swapped. Latitude comes first in Google Maps.
Turn Manual pins off on the Map.
Turn on Refit on filter, with Initial view set to Fit all pins.
Turn on Focus on click on the Map Pin. If it still finds the wrong element, set Card levels up.
The visitor declined, or the site isn’t on HTTPS. Framer’s published sites are. Some embedded previews block location: test on the published site.
Turn on Ctrl + scroll, or turn Scroll zoom off.
The device can’t draw maps (WebGL is off or unavailable), or OpenFreeMap couldn’t be reached. Your locations still show, with Directions.
14
Updates
New versions are free and listed here. To update, insert the component again from the Marketplace page or from the link in your Polar order, which always points to the latest version, and copy your settings across.
— The only third-party request, the map tiles from OpenFreeMap, is now explained in the code next to its fixed host: what is requested, why, and what is never sent.
— Near me explains why it needs the location before the browser asks. Zoom buttons are a labelled group, and unavailable buttons are disabled. Cards are found without looking beyond the pin’s own card. Lighter updates for long lists.
— MapLibre GL JS, its stylesheet and its worker now ship inside the component, so the map loads nothing from a CDN.
— First release: Map and Map Pin, native CMS filters, sorting and pagination, five map styles plus Brand colours, label language, Pin, Dot and Image markers, clusters, popups with View and Directions, Near me with distances and sort by distance, cards that highlight and focus the map, keyboard access, and a fallback list.
15
Support and licence.
Questions or a bug? Write to info@miguelrecio.es. A person replies within two business days (Mon–Fri, CET).
One licence covers one designer and unlimited client projects. Reselling or redistributing the component isn’t allowed.
Map data © OpenStreetMap contributors, tiles by OpenFreeMap and OpenMapTiles, rendered with MapLibre GL JS. CMS Locations Map shows them; it doesn’t own or host them.