# Google Maps adapter: map IDs, routes and clustering

The Google Maps adapter: options, your own map, loading Maps JS, map IDs, routes and clustering.

`createGoogleAdapter(options)` from `@maplacejs/maplace/google` draws a store on Google Maps; `@maplacejs/maplace/google` is the only entry that knows `google.maps`. The element's Google provider (`@maplacejs/maplace/element/google`, and the CDN script) makes the same adapter from the element's attributes. Provider options belong to the adapter, never to the store. On MapLibre: [MapLibre adapter](/maplibre/).

## Options

| Option | Type | What |
|---|---|---|
| `mapId` | `string` | Optional: Google's `DEMO_MAP_ID` by default, for development, with a console warning; your own for production ([key and map ID](/setup/#key-and-map-id)) |
| `colorScheme` | `"light" \| "dark" \| "follow-system"` | The colour scheme of a map Maplace.js creates |
| `map` | `google.maps.Map` | Your own map to draw on, instead of one Maplace.js creates |
| `mapOptions` | `google.maps.MapOptions` | Extra options for a map Maplace.js creates; not `center`, `zoom`, `mapId`, `colorScheme` or `styles` |
| `apiKey` | `string` | Your Maps API key: Maplace.js adds Maps JS to the page with it as the map mounts, unless the page loaded Maps JS already ([loading Maps JS](#loading-maps-js)) |
| `version` | `string` | Maps JS's version, as Google's `v`; with `apiKey` |
| `language` | `string` | The language of Google's labels and route instructions; with `apiKey` |
| `region` | `string` | The region Google biases its answers to; with `apiKey` |
| `nonce` | `string` | The nonce your content security policy asks the Maps JS tag for; with `apiKey` |

`center` and `zoom` are left out of `mapOptions` because only the store sets them ([the first view](/store/#the-first-view)), and JSON `styles` because Google ignores them on a map with a map ID ([map ID and styling](#map-id-and-styling)). An option the adapter doesn't know is `invalid-input`.

## `createGoogleMap`

`createGoogleMap(container, options)` is a store on a Google map in one call. It makes the store with the [store's options](/store/#options), the adapter with `mapId`, `colorScheme`, `mapOptions` and Maps JS's settings, attaches it in `container` (an element, or a selector the page matches), and returns the store; `destroy()` takes the map and its list down.

```ts
import { createGoogleMap } from "@maplacejs/maplace/google";

const maplace = createGoogleMap("#menu-vanilla-map", {
  locations: [
    { id: "london", lat: 51.5074, lng: -0.1278, title: "London", group: "South" },
    { id: "edinburgh", lat: 55.9533, lng: -3.1883, title: "Edinburgh", group: "North" },
    { id: "belfast", lat: 54.5973, lng: -5.9301, title: "Belfast", group: "North" },
  ],
  list: { as: "select", heading: "Choose a location:", fitAll: true, fitAllLabel: "All cities" },
});

const northOnly = document.querySelector<HTMLInputElement>("#menu-vanilla-north-only");
northOnly?.addEventListener("change", () => {
  maplace.setFilter(northOnly.checked ? ["North"] : undefined);
});
```

Its own options, beside the store's:

| Option | Type | What |
|---|---|---|
| `mapId` | `string` | Optional, as the adapter's |
| `colorScheme` | `"light" \| "dark" \| "follow-system"` | As the adapter's |
| `mapOptions` | `google.maps.MapOptions` | As the adapter's |
| `apiKey` | `string` | As the adapter's: Maplace.js adds Maps JS with it |
| `version`, `language`, `region`, `nonce` | `string` | As the adapter's, with `apiKey` |
| `list` | `true \| GoogleMapList` | Maplace.js's list: `true` for the default one, or the [list view's options](/store/#list-view-options) with its place |
| `list.position` | `ControlPosition` | The corner of the map the list goes in; default `top-right` |
| `list.container` | `HTMLElement \| string` | An element, or a selector, to put the list in instead, beside the map; not with `position` |
| `myLocation` | `true \| GoogleMapMyLocation` | A ["My location" control](/store/#the-my-location-control) on the map: `true`, or its `label`, `unavailableLabel` and `position` |
| `myLocation.position` | `ControlPosition` | The corner it goes in; default `top-left` |

Each part checks what it is handed, so misuse names the part: `createMaplace: options…`, `createGoogleAdapter: options…`, `attach: container…` (a selector matching nothing), `createListView: options…`. A store that can't be attached is destroyed before the error goes on.

Your own map (`map`), a control of your own on the map (`adapter.mountControl`) and a map opened again with a new adapter need the adapter, so they take the parts: `createMaplace`, `createGoogleAdapter` and `attach` ([creating a store](/store/#creating-a-store)).

## Your own map

Most pages don't need this. Normally you give Maplace.js a container and it creates the map: a new element filling the container (so size the container), removed on `destroy`. You never touch the `google.maps.Map` behind it, so you can do only what Maplace.js has options for.

A map of your own is a `google.maps.Map` your code created and gave to the adapter as `map`, so Maplace.js draws on it instead of creating one. You'd do this for one of two reasons:

- **Your page already has a map.** You want Maplace.js's markers, popups and list on it, not a second map beside it.
- **You need something Maplace.js has no option for.** You hold the map, so you can call Maps JS yourself: a traffic layer, a map event Maplace.js doesn't report. It replaces 0.2's `oMap`.

To change a map setting, `mapOptions` is enough, with no map of your own. Here the page makes its map, and a right-click, which Maplace.js doesn't report, sets where distances are measured from:

```ts
// A map of your own on Google: the page loads Maps JS and makes it, and Maplace.js draws on it.
import { createMaplace } from "@maplacejs/maplace";
import { createGoogleAdapter } from "@maplacejs/maplace/google";

const { Map: GoogleMap } = await google.maps.importLibrary("maps");
const map = new GoogleMap(document.querySelector("#own-map") as HTMLElement, {
  mapId: "YOUR_MAP_ID",
  center: { lat: 41.9028, lng: 12.4964 },
  zoom: 5,
});

const maplace = createMaplace({
  locations: [
    { id: "rome", lat: 41.9028, lng: 12.4964, title: "Rome" },
    { id: "milan", lat: 45.4642, lng: 9.19, title: "Milan" },
  ],
});
maplace.attach(createGoogleAdapter({ map }), map.getDiv());

// A map event Maplace.js doesn't report: a right-click measures distances from there.
map.addListener("contextmenu", ({ latLng }: google.maps.MapMouseEvent) => {
  if (latLng) maplace.setOrigin(latLng.toJSON());
});
```

- `attach`'s container must be `map.getDiv()` or hold it.
- `mapOptions` and `colorScheme` are refused: set them on your map.
- Your map's own map ID applies; if you also pass `mapId`, keep it the same. Google shows no markers on a map made without one, so that is `provider-load-failed` with `field: 'mapId'`.
- The store's first view moves your map: by default it fits the locations. To keep your map where it is, give the store `view: { kind: "center", center: map.getCenter().toJSON(), zoom: map.getZoom() }`.
- Maplace.js never moves your map in the page, and `destroy` removes only what Maplace.js added.

`whenReady` waits for Google to initialise the map, created or yours (at most 2 s, and not while it is hidden).

## Provider attributes

The element's Google provider reads these attributes of `<maplace-map>` when the map opens.

| Attribute | What |
|---|---|
| `map-id` | Optional: the map ID, as `mapId` |
| `nonce` | The nonce of the Maps JS script it adds, for a Content Security Policy; read as the element's `nonce` property, so one Vue or Svelte sets, or one a header CSP hides from the attribute, still counts |
| `color-scheme` | `light`, `dark` or `follow-system`, as `colorScheme` |
| `map-options` | A JSON object of Google's map options, as `mapOptions`, with the same exclusions; `center`, `zoom` and 0.2's `set_center` in it are told to use the [`center` and `zoom` attributes](/element/#map-attributes) |
| `api-key` | The key Maps JS loads with; needed only when the provider adds Maps JS itself |
| `version` | The Maps JS version to load |
| `language` | The language Maps JS loads with |
| `region` | The region Maps JS loads with |

A change of `color-scheme` or `map-options` opens the map again where it was, keeping the store's state, since Google sets a colour scheme only on a new map; each re-open is a new map load, which Google bills. A bad value is `invalid-input` naming the attribute (`map-options.center`).

## Loading Maps JS

Nothing reads `google` on import. The adapter calls the global `google.maps.importLibrary`, which works with [Google's bootstrap loader](https://developers.google.com/maps/documentation/javascript/load-maps-js-api) and with `@googlemaps/js-api-loader`, so Maplace.js has no loader dependency. Without `google.maps.importLibrary` (an old or missing Maps JS) loading fails with `provider-load-failed`.

The element's Google provider adds Maps JS itself, from `api-key`, and so does an adapter given `apiKey`, as its map mounts: one script per page however many maps, never while the element is held or before the adapter's map mounts. Maps JS's settings, `version`, `language`, `region` and `nonce`, go with the key; without `apiKey`, or with your own `map`, an adapter refuses them (`invalid-input`). The page's Maps JS tag, whoever added it, is shared: an element asking it for another `api-key`, `version`, `language` or `region` is misuse, and an adapter asking for another fails its load with `provider-load-failed`, the option in `field` (one it leaves out takes the page's). A page that loaded Maps JS without a tag of its own (the bootstrap loader, js-api-loader) is taken as it is, an adapter's settings unused. [Setup](/setup/) has both routes.

## Map ID and styling

Maplace.js draws advanced markers only (Google deprecated the legacy `Marker`), so every map has a map ID: yours, or Google's `DEMO_MAP_ID`, for development, when you give none, which warns once in the console ([key and map ID](/setup/#key-and-map-id)). A map is styled through its map ID's Cloud styling, plus `colorScheme`; `DEMO_MAP_ID` carries none.

## Routes

Routes use Google's Routes library, so your key needs the Routes API enabled. Without it no line draws and the `error` event says `route-failed`.

Routes use Google's Routes library, which needs Maps JS 3.63 or later; an older one fails the route with `route-failed`. A route has 2 to 27 stops (the adapter's `routeStopLimit`), `via` stops counting too. Each leg comes with its turn-by-turn `steps`, at no extra cost, each `instruction` in the language Maps JS loaded with. Each computation is billed, so a route is computed only when it changes ([routes](/store/#routes)). `avoid` becomes Google's route modifiers (`avoidTolls`, `avoidHighways`, `avoidFerries`), which Google applies to driving routes only: on another travel mode they aren't sent, and the route is computed without them. They are preferences: Google keeps off what it reasonably can, so a route may still take a toll road where no other one goes.

The route is Google's own line, in Google's look with its `style` over it. While a `progress` is set, Maplace.js draws it instead, in two lines along the route's path in that look: the part ahead, and the part travelled faded, `travelledStyle` over it; a transit route is then one colour. A dash (`strokeDash`) is drawn by Google's line symbols, as on any polyline: Google can't dash a stroke, so the line's own stroke is see-through under them.

## Clustering

The `cluster` option (the element's `cluster` attribute) groups markers with `@googlemaps/markerclusterer`, drawing Maplace.js's own cluster markers: a count, titled "Cluster of N locations", styled by `.maplace-cluster` ([cluster badges](/styling/#cluster-badges)). Circles, lines and polygons are never clustered, and the selected location is drawn on its own. Only the view and half a view around it are clustered and on the map, as on MapLibre, so a map zoomed in carries the markers it shows, not every one, and a short pan draws nothing again. A cluster still in view after a longer pan keeps its marker, and its focus. The clusterer loads with the map, so `whenReady` waits for it; a failed load is `provider-load-failed`. On the CDN, a map with `cluster` needs `maplace-element-cluster.iife.js`, which bundles it; on the plain script it fails to load, naming the cluster script.

## Heatmap

A [heatmap](/store/#heatmaps) is drawn by Maplace.js, as Google retired its own heatmap layer in May 2026: the heat on a canvas in the map's overlay pane, over the map's tiles and, on a vector map, over its polygons too; each marker's dot, faded in near `maxZoom`, is an advanced marker, so a click or Enter on it selects its location. The heat is drawn again as the view changes. Its code loads with the map, only when the store asks for a heatmap; the CDN scripts include it.

## When Google refuses

Google refusing the key (an invalid key, a referrer the key doesn't allow, the API or billing not enabled, a quota used up) is `provider-auth-failed` for every map on the page. Google checks the key as the first map opens, so this can come after `ready`: Maplace.js then stops drawing and leaves the map, with Google's message on it, until `destroy`. Your own `gm_authFailure` still runs. A missing key isn't refused (Google draws the map and logs `ApiProjectMapError`), so it reports nothing.

## Clicks and edits

A click on the map is reported 250 ms after it, unless a double-click comes first, so a double-click zoom neither fires `mapClick` nor clears the selection; a location clicked within those 250 ms drops the map's click. A marker reports its drag as it moves (`locationEdit`); Google says where a shape's handle went only when it is let go, so a shape's `locationEdit` comes once, with its `locationChange`. A window losing focus ends a marker's drag where it was, with its `locationChange`; a shape's handle drag is cut short instead, nothing reported and the shape left where the store has it, as Google gives no handle place until it is let go.

## Popups

A popup is Google's InfoWindow, headed by the location's title. One opened by a click or from the list pans the map to show it, once Google's own pan ends, clear of what the map's corners hold when there is room (never over Google's logo or terms; with no room, Google's own pan stands). A hover's popup doesn't pan.

## On-map controls

What goes on the map (`createGoogleMap`'s `list`, the element's `list-position`, `<LocationList position>`, `<MapControl>`) sits in a panel like Google's own controls, `.maplace-control`, in Google's corners: `top-left` under Google's Map/Satellite toggle, `bottom-left` above its logo, in the map's corner as on MapLibre and clear of the terms on a narrow map, and the right ones in Google's corner of that name.

On a map Maplace.js creates, its lists scroll within the map, clear of Google's own controls: on the left of the toggle and of its logo and terms, on the right of the fullscreen button, the camera control and Pegman, which Google stacks on that side. On a map too short for them, a list on the right keeps at least 7em and may cover them. A list in a left corner has the most room. The room is set aside for each side, not measured: it stays when those controls are turned off in `mapOptions`, and two lists on one side can overlap; a rule of the page, such as `.maplace-control .maplace-list { max-height: 90% }`, takes it back. Classes and how to turn the defaults off: [Styling](/styling/).

## The origin's dot

The dot at the store's [origin](/store/#distances) is an advanced marker straight on the map, not clickable, below every marker, in no cluster.

## Hidden maps

A Google map with a map ID draws with WebGL, and a browser keeps about 16 WebGL contexts per page, taking the oldest away past that. So a vector map Maplace.js creates gives its context back while it's hidden (`display: none`, `hidden`, a closed tab) and the page's maps hold more than 8, the map hidden longest first, takes it back once shown, and gives it back when destroyed. Below 8, a hidden map keeps its context, so it shows again at once, without drawing from scratch. A raster map holds none, and your own map (`map`) keeps its context. Checked in Chromium.
