README

Maplace.js

Your locations on a map, with a list in sync.On Google Maps or MapLibre: one script tag, npm or React.

Website · Documentation · Examples · Snippet builder · Migrating from 0.2


  
  
  
  




Maplace.js is a hobby project I maintain part-time, so support is best-effort.


A list of locations becomes a map plus a synced list, in a few lines. Click a marker and the list highlights it; pick it in the list and the map pans to it, opening its popup if it has one.

It runs on Google Maps or MapLibre, as a  element, from your own script or in React.

 What it does

- Your data: HTML children, JSON or JS objects, or GeoJSON (locations): markers, circles, polylines and polygons on one map, and on Google one route through them.
- Lists: beside the map or on it, with search, groups and "this area", or a native select (list options).
- Nearest first: sorted by straight-line distance from a point, with a "My location" button, and no provider service or quota (distances).
- Many places: clustering for long lists (element).
- Loading: loading="lazy" waits until the map is near the viewport, hold until the page's consent (consent).
- Links: url-state keeps the selected place in the address (URL state).
- Keyboard and screen readers: a link to skip the map, each selection announced (accessibility).

 Quick start

One script, no build step. On Google Maps:


html


  
  



- api-key is your Google Maps JavaScript API key. The element loads Maps JS itself, once per page.
- map-id is optional: without it the map uses Google's DEMO_MAP_ID, for development, and warns once in the console; set your own for production (key and map ID).
- color-scheme (light, dark or follow-system) and map-options (Google's map options as JSON, e.g. '{"mapTypeControl":false}': not centre, zoom, map ID, colour scheme or styles: centre and zoom are the center and zoom attributes) set the map Google creates; change either and the map opens again where it was.

On MapLibre, with no key and no map ID:


html


  
  



- The MapLibre script bundles MapLibre GL JS, its worker and its stylesheet, so the page loads it alone. Open the page from a web server, a local one is fine, not directly as a file. The map draws OpenFreeMap's bright style (OpenStreetMap data, free, no key). map-style takes another style URL or a JSON style, and map-options takes MapLibre's map options as JSON (not its container, style, centre, zoom or bounds: centre and zoom are the center and zoom attributes). Change either and the map opens again where it was (MapLibre adapter). A page with a content security policy allows the script's worker and images: worker-src blob: and img-src data: blob: (Content Security Policy).

On either:

- list puts a list beside the map; list="select" makes it a native , list="" your own view, given to defineListView(name, (maplace, { options, listed }) = listView), which lists what listed() gives, as Maplace.js's lists do (listedLocations(snapshot) from @maplacejs/maplace give

Latest release

- 2026-11-09 Fixed whenReady() and loadState ready on MapLibre (and its adapter's apply) resolving before the locations were drawn when MapLibre was slow to load them (its workers starting, a busy machine): they now wait for the load, up to 10 s, and give only the drawing its 1 s cap, so a click or a hover right after finds what was added