Maplace.js

Google Maps adapter: map IDs, routes and clustering

Markdown

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.

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)
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)
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), and JSON styles because Google ignores them on a map with a map ID (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, 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.

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 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 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).

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:

// 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
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 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 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). 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). 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). 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 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.

The origin’s dot

The dot at the store’s origin 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.