Embed Google Maps or MapLibre with markers on a website
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 <maplace-map> 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, polygons and multipolygons 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,holduntil the page’s consent (consent). - Links:
url-statekeeps 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:
<script src="https://cdn.jsdelivr.net/npm/@maplacejs/maplace@1/dist/maplace-element.iife.js"></script>
<maplace-map api-key="YOUR_KEY" list>
<maplace-location location-id="rome" lat="41.9028" lng="12.4964" title="Rome"></maplace-location>
<maplace-location location-id="milan" lat="45.4642" lng="9.19" title="Milan"></maplace-location>
</maplace-map>
api-keyis your Google Maps JavaScript API key. The element loads Maps JS itself, once per page.map-idis optional: without it the map uses Google’sDEMO_MAP_ID, for development, and warns once in the console; set your own for production (key and map ID).color-scheme(light,darkorfollow-system) andmap-options(Google’s map options as JSON, e.g.'{"mapTypeControl":false}': not centre, zoom, map ID, colour scheme orstyles: centre and zoom are thecenterandzoomattributes) set the map Google creates; change either and the map opens again where it was.
On MapLibre, with no key and no map ID:
<script src="https://cdn.jsdelivr.net/npm/@maplacejs/maplace@1/dist/maplace-element-maplibre.iife.js"></script>
<maplace-map list>
<maplace-location location-id="rome" lat="41.9028" lng="12.4964" title="Rome"></maplace-location>
<maplace-location location-id="milan" lat="45.4642" lng="9.19" title="Milan"></maplace-location>
</maplace-map>
- 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
brightstyle (OpenStreetMap data, free, no key).map-styletakes another style URL or a JSON style, andmap-optionstakes MapLibre’s map options as JSON (not its container, style, centre, zoom or bounds: centre and zoom are thecenterandzoomattributes). 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:andimg-src data: blob:(Content Security Policy).
On either:
listputs a list beside the map;list="select"makes it a native<select>,list="<name>"your own view, given todefineListView(name, (maplace, { options, listed }) => listView), which lists whatlisted()gives, as Maplace.js’s lists do (listedLocations(snapshot)from@maplacejs/maplacegives the same to a list of your own outside the element, both before a scoped list narrows it to the map’s view; a map held withholdbuilds its list onrelease(), once your view is defined);list-positionplaces it on the map or outside it,list-headingshows a heading above it (on the map too), naming it for screen readers, andlist-scope="viewport"shows a switch above it, “All” or “This area”, which lists only what is in the map’s view and follows the map. The list and popups come with default styles in:where(): any rule of yours wins, anddata-maplace-unstyledturns them off (Styling lists the classes to style instead). What goes on the map sits in a panel like the provider’s own controls (.maplace-control): in the map’s colour scheme on Google, light on MapLibre.
A location’s popup is a <template> child, and a marker’s own look an icon image URL or a <template data-icon> child (one element, marked data-selected and data-hovered while in that state, for your CSS). A location’s zoom is where selecting it shows it, from a click on its marker or in the list too, and listed="false" keeps it on the map and out of the list; editable lets the user drag or reshape it. Both are booleans as HTML writes them: present, or "true", is true.
A circle’s styles (colours, opacities, stroke width) are JSON objects in shape-style, selected-style, hovered-style and active-style: <maplace-location type="circle" … selected-style='{"stroke":"#c2410c","fill":"#f97316"}'>.
Locations can also come from an inline <script type="application/json"> child or the element’s locations property. The element never fetches: load your data and assign it.
One script per page
The CDN has three scripts. Load exactly one of them. Two scripts on one page are two copies of Maplace.js, and the second’s provider is never seen. A page with maps on both Google and MapLibre uses npm: both element entries, each map naming its provider.
| Script | For |
|---|---|
maplace-element.iife.js |
on Google, everything but clustering |
maplace-element-cluster.iife.js |
on Google, with cluster (bundles Google’s MarkerClusterer; its licences are in THIRD-PARTY-LICENSES.txt beside it) |
maplace-element-maplibre.iife.js |
the element on MapLibre, clustering included: maplibre-gl, its worker and its stylesheet bundled, so one pinned file is all the page loads (its size; the bundled packages’ licences in THIRD-PARTY-LICENSES.txt beside it) |
A map with cluster on the first script fails to load and says to use the second.
Each script also sets one global, Maplace: what the npm entries it stands for export (@maplacejs/maplace, the provider’s and @maplacejs/maplace/element), so a page of your own script calls Maplace.createGoogleMap(...) where npm’s would import it, and defines its own list view with Maplace.defineListView(name, factory). The MapLibre script’s Maplace.maplibre is the maplibre-gl it bundles.
Pin it for production
@maplacejs/maplace@1 follows the latest 1.x, so it can’t carry an integrity hash. In production, pin the exact version and let the browser check the file:
<script src="https://cdn.jsdelivr.net/npm/@maplacejs/maplace@1.2.0/dist/maplace-element.iife.js"
integrity="sha384-OgwZw1NQ78VKxQUXntJyiiRILF/Ck2chxPi2kbY+gNOcSqZIIsBVXI1BAPbqs6LV" crossorigin="anonymous"></script>
or, with clustering:
<script src="https://cdn.jsdelivr.net/npm/@maplacejs/maplace@1.2.0/dist/maplace-element-cluster.iife.js"
integrity="sha384-nYnk30aW5TZxhlK3odeU4GRQiVdUxmZ1+GsvV2Ld4/8H7cEwXWsseZPHy8n+jfXc" crossorigin="anonymous"></script>
or, on MapLibre:
<script src="https://cdn.jsdelivr.net/npm/@maplacejs/maplace@1.2.0/dist/maplace-element-maplibre.iife.js"
integrity="sha384-NTx1K+93ZQC7ezi/smTAvSpiQCrdWid6IfMLQuIS6oT/63JARr9b+gD1devKzZqV" crossorigin="anonymous"></script>
The README published with each version has these filled in for it. unpkg serves the same paths (https://unpkg.com/@maplacejs/maplace@1.2.0/dist/…). To compute a hash yourself:
curl -s https://cdn.jsdelivr.net/npm/@maplacejs/maplace@1.2.0/dist/maplace-element.iife.js | openssl dgst -sha384 -binary | openssl base64 -A
From your own script
A page that makes its map in its own script needs no build step either: the CDN script’s Maplace holds what the npm entries export. Given apiKey, Maplace.js adds Maps JS itself, as the element does from api-key:
<!doctype html>
<!-- A page of your own script: the CDN script, what the map mounts on, and the map made with Maplace, which adds Maps JS with your key. -->
<script src="https://cdn.jsdelivr.net/npm/@maplacejs/maplace@1/dist/maplace-element.iife.js"></script>
<style>
#simple-script-map { height: 24rem; }
</style>
<div id="simple-script-map"></div>
<script type="module">
Maplace.createGoogleMap("#simple-script-map", {
apiKey: "YOUR_KEY",
locations: [{ id: "london", lat: 51.5074, lng: -0.1278, title: "London" }],
});
</script>
On MapLibre, Maplace.createMapLibreMap on the MapLibre script, with no key; Maplace.maplibre is the maplibre-gl it bundles, for a map of your own (setup).
With a bundler
npm install @maplacejs/maplace
A store on a Google map in one call, createGoogleMap, on a page that loads Maps JS with Google’s bootstrap loader (or @googlemaps/js-api-loader) and gives the map’s container its size:
<!doctype html>
<!-- The page vanilla.ts runs on: Maps JS from Google's bootstrap loader, what the module mounts on, the module. -->
<script>
(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})({
key: "YOUR_KEY",
v: "weekly",
});
</script>
<style>
#simple-vanilla-map { height: 24rem; }
</style>
<div id="simple-vanilla-map"></div>
<script type="module" src="./vanilla.ts"></script>
import { createGoogleMap } from "@maplacejs/maplace/google";
createGoogleMap("#simple-vanilla-map", {
locations: [{ id: "london", lat: 51.5074, lng: -0.1278, title: "London" }],
});
list: true adds Maplace.js’s list on the map, top right; list also takes the list view’s options with a corner (position) or an element of the page to go in (container). createGoogleMap is made of three parts a page can use itself, when it draws on its own Google map, puts a control of its own on the map, or opens the map again: the store (createMaplace), the adapter (createGoogleAdapter) and attach(adapter, "#map"), which takes an element or a selector.
On MapLibre, createMapLibreMap from @maplacejs/maplace/maplibre makes the same store in one call, with mapStyle and mapOptions for the map (MapLibre adapter). The page installs maplibre-gl too (npm install @maplacejs/maplace maplibre-gl), imports its stylesheet, maplibre-gl/dist/maplibre-gl.css, in its module, and needs no loader script and no key. Its parts are createMaplace, createMapLibreAdapter and attach. The simple example’s MapLibre version is the whole page:
<!doctype html>
<!-- The page vanilla.ts runs on: what the module mounts on, and the module, which brings maplibre-gl and its stylesheet. -->
<style>
#simple-maplibre-vanilla-map { height: 24rem; }
</style>
<div id="simple-maplibre-vanilla-map"></div>
<script type="module" src="./vanilla.ts"></script>
import "maplibre-gl/dist/maplibre-gl.css";
import { createMapLibreMap } from "@maplacejs/maplace/maplibre";
createMapLibreMap("#simple-maplibre-vanilla-map", {
locations: [{ id: "london", lat: 51.5074, lng: -0.1278, title: "London" }],
});
Circles, polylines, polygons and multipolygons take a style, a selectedStyle, a hoveredStyle and an activeStyle (and the store the same four, as defaults); Maplace.js’s own selected and hovered look fills what they leave unset, and a shape marked active has the hovered look. A line’s style can dash it (strokeDash), and a line or the route can show how much is travelled (progress, travelledStyle), with pointAlong placing your own marker on it.
For the element from npm, import "@maplacejs/maplace/element/google" defines <maplace-map> and <maplace-location> with the Google provider, and import "@maplacejs/maplace/element/maplibre" with the MapLibre provider (on the page’s maplibre-gl and its stylesheet).
| Entry | What it gives |
|---|---|
@maplacejs/maplace |
createMaplace (the headless store), createListView, createMyLocationControl, listedLocations, distanceTo, locationsFromGeoJSON (a GeoJSON FeatureCollection as locations), the adapter contract and the types |
@maplacejs/maplace/google |
createGoogleMap (a store on a Google map in one call) and createGoogleAdapter: the only entry that knows google.maps |
@maplacejs/maplace/maplibre |
createMapLibreMap (a store on a MapLibre map in one call) and createMapLibreAdapter: the only entry that knows maplibre-gl |
@maplacejs/maplace/element |
<maplace-map> and <maplace-location>, with defineProvider for other providers and defineListView for your own lists |
@maplacejs/maplace/element/google |
the element with the Google provider registered |
@maplacejs/maplace/element/maplibre |
the element with the MapLibre provider registered |
@maplacejs/maplace/react |
<MaplaceProvider>, <MaplaceMap>, <LocationList> and useMaplace() |
@maplacejs/maplace/testing |
describeConformance: the conformance suite, to prove an adapter of your own, with vitest as an optional peer |
@googlemaps/markerclusterer and supercluster are dependencies, each loaded only by a store that clusters on its provider. maplibre-gl (6.15 or a later 6.x) is an optional peer, for @maplacejs/maplace/maplibre and @maplacejs/maplace/element/maplibre; vitest is an optional peer, for @maplacejs/maplace/testing, tested on 5; @types/google.maps is an optional peer, for TypeScript pages that use @maplacejs/maplace/google; react and react-dom (19) are optional peers, for @maplacejs/maplace/react; vue (3.3 or later) and svelte (4 or 5) are optional peers, for the element’s types in their templates.
With React
import type { Location } from "@maplacejs/maplace";
import { createGoogleAdapter } from "@maplacejs/maplace/google";
import { MaplaceMap, MaplaceProvider } from "@maplacejs/maplace/react";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
const london: Location[] = [{ id: "london", lat: 51.5074, lng: -0.1278, title: "London" }];
function Simple() {
return (
<MaplaceProvider locations={london}>
<MaplaceMap createAdapter={createGoogleAdapter} className="map" />
</MaplaceProvider>
);
}
createRoot(document.getElementById("simple-react-root") as HTMLElement).render(
<StrictMode>
<Simple />
</StrictMode>,
);
The file renders its own root, into the page beside it, which loads Maps JS as the vanilla page does and sizes the map’s div. <MaplaceProvider> makes one store for its children. Its locations follow your state; selectedId with onSelectionChange controls the selection, or defaultSelectedId only starts it. <MaplaceMap> attaches a fresh adapter while it is mounted, to a div its className sizes (a map fills its container). Its popupContent gives popups React content, as the popups example does, and its markerIcon gives markers React content, as the markers example does. <LocationList> is the store’s list, with a function child for each entry’s content (inside <MaplaceMap>, its position="top-right" puts it on the map, and <MapControl position> puts your own content there), and useMaplace() returns the store to read with useSyncExternalStore or to call.
On MapLibre, createAdapter={createMapLibreAdapter} from @maplacejs/maplace/maplibre is the only change, the module importing maplibre-gl’s stylesheet (MapLibre adapter).
In a React Server Component, @maplacejs/maplace/react is a client boundary (it starts with "use client"): the server component loads the data and renders the provider and the list with it, and a small client component of yours holds the map, since its adapter is made by a function:
import type { Location } from "@maplacejs/maplace";
import { LocationList, MaplaceProvider } from "@maplacejs/maplace/react";
import { CityMap } from "./city-map";
/** Where a server component's data would come from: a database, an API. */
async function loadCities(): Promise<Location[]> {
return [
{ id: "rome", lat: 41.9028, lng: 12.4964, title: "Rome" },
{ id: "milan", lat: 45.4642, lng: 9.19, title: "Milan" },
];
}
/** A server component: it loads the data and hands it to the binding, a client boundary. */
export async function Page() {
const cities = await loadCities();
return (
<html lang="en">
<body>
<MaplaceProvider locations={cities}>
<CityMap />
<LocationList label="Cities" />
</MaplaceProvider>
</body>
</html>
);
}
"use client";
import { createGoogleAdapter } from "@maplacejs/maplace/google";
import { MaplaceMap } from "@maplacejs/maplace/react";
// Functions can't cross from a server component: the map's adapter is made here, on the client.
export function CityMap() {
return <MaplaceMap createAdapter={createGoogleAdapter} className="map" />;
}
on<Event> props, popupContent, markerIcon and a list’s function child are functions too, so they go in client components as well; so does a controlled selectedId, which needs its onSelectionChange. A server component can start the selection with defaultSelectedId. Both files are the ones Maplace.js’s own test builds with Vite’s RSC plugin.
What it needs
- Evergreen browsers (ES2022). The package is ES modules only.
- Google Maps JavaScript API (a map ID of your own for production; routes need Maps JS 3.63 or later), or MapLibre GL JS 6.15 or a later 6.x with a style, OpenFreeMap’s by default, no key (the MapLibre CDN script bundles it). Routes on MapLibre go through your own routing (
computeRoute).
Documentation
- maplacejs.com: every example running live, and these docs.
- Reference: every export, with where it is explained, its error codes and each provider’s capabilities.
- The 1.0 RFC: the API, its rules, errors and numbers.
- Examples: twenty-eight scenarios, each as an HTML page, a page of your own script on
Maplace, vanilla TypeScript and React on Google, and on MapLibre too, in each one’smaplibre/folder. - MIGRATION.md: from 0.2, option by option.
- CHANGELOG.md.
- CONTRIBUTING.md, SECURITY.md and the code of conduct.
License
Maplace.js is released under the Apache License, Version 2.0 © 2026 Daniele Moraschi.
The name
Maplace.js, Maplace, maplacejs, maplace.js, maplace-js and @maplacejs/maplace are this project’s names, and the licence grants no rights to them (Apache-2.0 §6). Please publish a fork or a product under a name of its own, and don’t present it as Maplace.js or as endorsed by it; saying it is built on or derived from Maplace.js, and carrying the NOTICE, is fine.