# Embed Google Maps or MapLibre with markers on a website

Put a Google Map or a MapLibre map with markers and a synced list on a website: one script tag, or npm and React.

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](/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](/store/#list-view-options)).
- **Nearest first**: sorted by straight-line distance from a point, with a "My location" button, and no provider service or quota ([distances](/store/#distances)).
- **Many places**: clustering for long lists ([element](/element/#map-attributes)).
- **Loading**: `loading="lazy"` waits until the map is near the viewport, `hold` until the page's consent ([consent](/setup/#consent)).
- **Links**: `url-state` keeps the selected place in the address ([URL state](/element/#url-state)).
- **Keyboard and screen readers**: a link to skip the map, each selection announced ([accessibility](/accessibility/)).

## Quick start

One script, no build step. On Google Maps:

```html
<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](/setup/#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](/element/#map-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
<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](/setup/#use-a-web-server-for-maplibre), 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](/element/#map-attributes)). Change either and the map opens again where it was ([MapLibre adapter](/maplibre/#provider-attributes)). 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](/setup/#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](/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](/maplibre/#with-the-cdn-script); 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:

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

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

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

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

```html
<!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](/setup/#with-a-script-of-your-own)).

## With a bundler

```sh
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](https://developers.google.com/maps/documentation/javascript/load-maps-js-api) (or `@googlemaps/js-api-loader`) and gives the map's container its size:

```html
<!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>
```

```ts
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](/maplibre/#createmaplibremap)). 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:

```html
<!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>
```

```ts
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

```tsx
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](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/packages/maplace/examples/simple/react.html), 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](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/packages/maplace/examples/popups/react.tsx) does, and its `markerIcon` gives markers React content, as [the markers example](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/packages/maplace/examples/markers/react.tsx) 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](/maplibre/#react)).

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:

```tsx
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>
  );
}
```

```tsx
"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](https://maplacejs.com): every example running live, and these docs.
- [Reference](/api/): every export, with where it is explained, its error codes and each provider's capabilities.
- [The 1.0 RFC](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/docs/rfc-1.0.md): the API, its rules, errors and numbers.
- [Examples](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/packages/maplace/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's `maplibre/` folder.
- [MIGRATION.md](/migrating/): from 0.2, option by option.
- [CHANGELOG.md](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/CHANGELOG.md).
- [CONTRIBUTING.md](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/CONTRIBUTING.md), [SECURITY.md](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/SECURITY.md) and the [code of conduct](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/CODE_OF_CONDUCT.md).

## License

Maplace.js is released under the [Apache License, Version 2.0](https://github.com/danielemoraschi/maplace.js/blob/5dd17eac33e258107f91c7a4d4d05bc2673e17bd/LICENSE) © 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.
