Maplace.js

Embed Google Maps or MapLibre with markers on a website

Markdown

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, 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:

<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-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:

<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 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 <select>, list="<name>" 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 gives 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 with hold builds its list on release(), once your view is defined); list-position places it on the map or outside it, list-heading shows a heading above it (on the map too), naming it for screen readers, and list-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, and data-maplace-unstyled turns 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

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.