Maplace.js

The element: a web component for Google Maps and MapLibre

Markdown

<maplace-map> is a map with an optional list, and <maplace-location> one location inside it. They are the whole API of a page with no build step: one script from the CDN defines both, with the Google provider, or, the MapLibre script, with MapLibre’s.

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

From npm, import "@maplacejs/maplace/element/google" defines the same elements with the Google provider, import "@maplacejs/maplace/element/maplibre" with the MapLibre provider, and @maplacejs/maplace/element with none (Setup). Defining them twice is harmless; a second, different copy of Maplace.js on the page logs an error and leaves the first in place.

Size

The element is 24rem tall unless the page sets its height (maplace-map { height: 30rem }); a page sizing it by its layout instead (position: absolute; inset: 0, a grid’s row) sets height: auto. The map fills it, with its list beside it, or, on a screen narrower than 40rem, under it, at most 40% of the height, scrolling. Its own styles come with the element’s script, so a page loading that script late keeps the room with :where(maplace-map:not(:defined)) { display: block; height: 24rem; }, which a height of the page’s still overrides.

A list before the script runs

Maplace.js builds its list once its script has run, and a map with hold only on release(). To show the places sooner, while a slow script loads, if it fails, or while a map waits for a visitor’s consent, write them into the page’s HTML as a list of your own. It also puts them in front of crawlers that run no JavaScript. Hide it the moment Maplace.js’s list is there:

<style>
  /* Holds the map's room, and the list's, until the script's own styles come. */
  :where(maplace-map:not(:defined)) {
    display: block;
    height: 24rem;
  }
  .before-script {
    margin: 0;
    overflow: auto;
  }
  maplace-map:not(:defined) > .before-script {
    height: 100%;
  }
  /* Beside a map waiting to load, where Maplace.js's own list will go. */
  maplace-map:defined > .before-script {
    flex: 0 1 16rem;
  }
  @media (width < 40rem) {
    maplace-map:defined > .before-script {
      flex: none;
      max-height: 40%;
    }
  }
  /* Gone the moment Maplace.js's list is there, not before. */
  maplace-map:has(.maplace-placed-list) > .before-script {
    display: none;
  }
</style>

<maplace-map list api-key="YOUR_KEY">
  <ul class="before-script">
    <li><a href="/shops/rome">Rome</a></li>
    <li><a href="/shops/milan">Milan</a></li>
  </ul>
  <maplace-location location-id="rome" lat="41.9" lng="12.5" title="Rome"></maplace-location>
  <maplace-location location-id="milan" lat="45.46" lng="9.19" title="Milan"></maplace-location>
</maplace-map>
  • Load the script so it doesn’t block parsing (defer, type="module", or after the map), or a slow one holds the list back too.
  • Picking a place still needs the script, so make the entries plain text or links to pages of their own.
  • Your list and Maplace.js’s are two separate lists. Focus and scroll in yours are lost at the swap, the places are written twice, and the entries change to Maplace.js’s look unless your CSS matches it.
  • This is for a list beside the map. One in a corner (list-position) sits on the map, where yours has no place, and with data-maplace-unstyled the map’s layout, and so your list’s place in it, is your own.
  • Schema.org JSON-LD is yours to add the same way, its data matching what the page shows; Maplace.js writes none.

Map attributes

Attribute What
list Present: a list of the locations (empty, or "true", as Svelte 5 writes a bare list); list="select": a native select; list="<name>": a list view of yours. Absent: no list
list-position outside (beside the map, the default; under it, within the element’s height, on a screen narrower than 40rem), or a corner of the map: top-left, top-right, bottom-left, bottom-right
fit-all Adds a first entry to the list, which clears the selection and fits all locations. On a select it shows only while all locations are fitted (list view options). Present, empty or "true" is on, "false" off, anything else misuse, as for search, my-location, open-in-maps-link, directions-link, cluster and hold
fit-all-label The words of the list’s first entry, which clears the selection and fits all locations; “All locations” when left out; does nothing without fit-all; a blank one is misuse
list-heading A heading above the list, beside the map or on it; the list’s accessible name
group-counts After each group heading, how many are listed under it now, following the filter and list-scope: “North (3)”. Present, empty or "true" is on, "false" off, anything else misuse
list-scope viewport: a switch above the list, “All” or “This area”, which lists only what is in the map’s view and follows it, wherever the list is placed (List view options); not with list="select"
area-only-label The words of the list-scope switch’s button that lists only the map’s view; default “This area”
show-all-label The words of the list-scope switch’s button that lists every location; default “All”
empty-area-label What a list with list-scope says when no location is in the map’s view; default “No locations in this area”
list-sort distance: once the store has an origin, a list nearest first, each entry saying how far (Distances)
distance-unit What list-sort writes a distance in: kilometer (the default) or mile
my-location Puts the “My location” control on the map: a button that asks for the visitor’s position only when pressed. A value neither true nor false keeps the map from opening until it is fixed
my-location-label The words on the “My location” button; “My location” when blank or left out; does nothing without my-location
my-location-unavailable-label What the “My location” control says under its button when no position comes; “Location unavailable” when blank or left out
my-location-position The corner of the map the “My location” control goes in; top-left when left out
search Shows a search box above the list; typing narrows the list and the map once it pauses. A switch, as fit-all is; misuse with list="select"
search-label The search box’s placeholder and accessible name; “Search” when left out; does nothing without search; a blank one is misuse
no-matches-label What the line under the search box says when nothing matches; default “No locations match”
matches-label What the line under the search box says before the count of matches; default “Locations found”, as “Locations found: 3”
group-filter (1.2) A “Groups” button above the list that opens a checkbox for each group, subgroups nested (Subgroups); a switch, as search is; misuse with list="select"
group-filter-label The boxes’ accessible name; “Groups” when left out; does nothing without group-filter; a blank one is misuse
provider The registered provider to draw with; defaults to the only one registered, and is required when several are. A change opens the map again on it
cluster Groups nearby markers into a cluster with a count (on Google’s CDN, the cluster script; the MapLibre script clusters as it is). A switch, as fit-all is; can’t change once the store exists; badges styled as cluster badges
heatmap Draws markers as a heatmap (1.2): empty or true for every marker, else the groups it names, space-separated; false for none. Not with cluster; can’t change once the store exists
heatmap-max-zoom The zoom the heatmap gives way to its dots at, 3 to 25; default 9; misuse without heatmap
skip-map-label The words of the link past the map, which keyboard users reach first; default “Skip the map”; can’t change once the store exists; a blank one is misuse
selected-label The word announced before a selected location’s name, “Selected: Rome”; default “Selected”; can’t change once the store exists; a blank one is misuse
popup-open-on What opens a location’s popup: click (the default), or hover, with the selection while nothing is hovered, so a tap still opens it (popup options); can’t change once the store exists; not with a popup’s links
open-in-maps-link Adds a link at the end of each popup, to the location on the provider’s maps site: Google Maps on Google, OpenStreetMap on MapLibre; can’t change once the store exists
open-in-maps-label The words of the link to the provider’s maps site; “Open in Maps” when left out; does nothing without open-in-maps-link; can’t change once the store exists; a blank one is misuse
directions-link Adds a link at the end of each popup, to directions to the location: Google Maps on Google, OpenStreetMap on MapLibre; can’t change once the store exists
directions-label The words of the link to directions; “Directions” when left out; does nothing without directions-link; can’t change once the store exists; a blank one is misuse
hold Stays idle, with no provider request and no list built, until release(). A switch, as fit-all is, except that a value neither true nor false holds too, as well as being misuse, so a typo can’t load a map before consent. Read when the map would open: writing false later opens nothing, release() does
loading lazy: the map stays idle until it comes within 100px of the viewport, then loads (its list is built at once), on each connect until release(); read when the map would open, as hold is. Any other value, or none, loads at once
load-label The words of the load panel’s button; “Load map” when blank or left out; live
load-from-label The words before the name on that panel; “Loads from” when blank or left out; live
failure-label The words of the panel a map shows when it can’t be used; “The map couldn’t load.” when blank or left out; live
center The map’s first centre, "lat,lng" (center="41.9,12.5"), with zoom; can’t change once the store exists
zoom The map’s first zoom, with center; can’t change once the store exists
selected-id The location selected at start, like <input value>; later changes go through maplace; a url-state address naming another location wins; center and zoom win for the first view
url-state Keeps the selection in the page’s address, as ?location=<id> or the parameter it names; see URL state

list, list-position, fit-all, fit-all-label, list-heading, group-counts, list-scope, list-sort, distance-unit, area-only-label, show-all-label, empty-area-label, search, search-label, no-matches-label, matches-label, group-filter and group-filter-label are live: a change builds the list again. my-location and the my-location-* attributes are read when the map opens: a later change does nothing until it opens again. The Google provider reads its own attributes, such as api-key and map-id, and the MapLibre provider map-style and map-options, when the map opens; a change of a map setting (color-scheme, map-style or map-options, whichever the provider, and MapLibre’s globe, globe-position and globe-label) opens it again where it was: provider attributes on Google and MapLibre.

The map opens on the location a url-state address names, if not selected-id’s; else at center and zoom when given; else on the selected-id location (at its zoom, if it has one); else with all locations fitted (the first view). The two go together: one alone is misuse naming the missing one, and a value the store’s checks refuse, such as a latitude past 90, misuse naming it; the map then opens as without them. With center and zoom, selected-id’s location is selected without moving the map, even when it arrives later, or when the address names it as the page loads (written in on a first visit, or on a reload); going back or forward to an entry brings its location into view. A popup opening may still pan the map to fit it. Any other view, or a later move, goes through map.maplace (map.maplace.setView({ lat: 41.9, lng: 12.5 }, 6)).

Properties and methods

Property What
locations The locations, as an array; once set, it wins over those written inside the element
route The route, or undefined
sanitize The store’s sanitize option, so locations given as JSON or through locations can use html. Set it before the map opens; set later, it is misuse
computeRoute Your own routing, for a map on MapLibre, which has none (routes on MapLibre); read when the map opens, so set it before; Google ignores it. On MapLibre, not a function is misuse
maplace The underlying store, for anything the attributes don’t cover
loadState error while a misuse stands, else the store’s: idle, loading, ready or error
release release() starts loading at once an element held with hold or waiting with loading="lazy"

The store is created when the element first connects (or maplace, locations or route is first read), from cluster, center and zoom, sanitize, selected-id and the locations, and lives as long as the element. Removed from the page, the map closes and the store goes back to idle, keeping its locations, selection and listeners; connected again, a new map opens. A move within one task keeps the map.

With its built-in providers the element creates its own map. A page with a map of its own takes the parts instead (on Google, on MapLibre).

Events

The store’s events, as DOM events on the element, named in lower case. They bubble, and their detail is the store event’s payload.

Event Store event
maplace-selectionchange selectionChange
maplace-hoverchange hoverChange
maplace-mapclick mapClick
maplace-locationedit locationEdit
maplace-locationchange locationChange
maplace-popupopen popupOpen
maplace-popupclose popupClose
maplace-viewportchange viewportChange
maplace-routechange routeChange
maplace-error error, and the element’s own misuse

Load states

The element’s loadState is shown as the custom state :state(idle) (also loading, ready and error), so CSS styles the map in each, such as a consent placeholder. The element never writes its own attributes or styles; its default styles, and how to turn them off, are on Styling. A map with hold asks nothing of its provider until release(): a consent banner calls it once the visitor agrees, and a held map builds its list on release too. A map with loading="lazy" stays idle until it comes near the viewport, so a map below the fold costs no map load (Google bills each) until the visitor scrolls to it; one in a hidden panel (a closed tab, <details>, display: none) loads once shown. Its list is built at once; with hold as well, it waits for release(), which loads it wherever it is.

The Load on demand example shows it. While it waits, with hold or off-screen with loading="lazy", a map shows a panel in its pane: a button calling release() and a line naming whom it loads from. The panel asks no provider anything, and leaves as the map opens, focus passing to the pane if it held it. A placeholder a page draws with :state(idle) shows beside it, unless the page replaces or hides the panel, and in the error state the panel is hidden until the misuse is corrected.

The map The line
On Google “Loads from Google”
On MapLibre with no map-style “Loads from OpenFreeMap”
On MapLibre, map-style an http or https URL “Loads from” and the URL’s host, its port kept
On MapLibre with a JSON style, a relative URL or another scheme None, only the button: there is no one host to name
On a provider of your own (defineProvider) Its registered name
With provider naming one not registered yet That name, then the provider’s own once it registers
With no provider, and none or several registered None, only the button

load-label and load-from-label word it. A blank one takes the default words, unlike the other labels, where blank is misuse: an error would hide the panel, and with it the way to load the map. A direct child marked data-maplace-idle replaces the panel: the page’s own, which stays where the page put it, shows only in :state(idle), and calls release() itself. On a lazy map starting in view, it shows for the map’s first frame, as :state(idle) is true then; the ready-made panel doesn’t. A lazy map hidden at first (a closed tab) gets no panel, and opens as it nears the viewport. To look different, or to go, see Styling.

A map that can’t be used says so in :state(error): a panel on it (.maplace-map-failure, an alert), worded by failure-label, which a page handling :state(error) itself hides with .maplace-map-failure { display: none; }. It shows on the maps Maplace.js’s adapters create, and not where the map still works (locations failing to draw), beside Google’s own refused-key message, for misuse, or on a provider of your own.

URL state

With url-state, the page’s address says which location is selected, so a link opens on it and the back button steps through selections:

<maplace-map url-state selected-id="rome">…</maplace-map>
<!-- page.html?location=milan opens on Milan -->
  • The location the address names is selected as soon as the locations show it, over selected-id. A link naming a location that isn’t there is ignored, never an error.
  • An address naming no location gets selected-id’s written in, with no new history entry, when the element connects before its store is created (a script reading maplace first writes nothing).
  • Each later selection is a new history entry, and back and forward select again; a cleared selection takes the parameter out, in place when the page took the location away (new locations, a filter), so the entry you leave doesn’t name a location that’s gone. Only that parameter changes: the rest of the query and the hash are kept.
  • A bare url-state (or "true") is the location parameter. With several maps on a page, give each its own: url-state="office".
  • The attribute is read when the element connects.

With React, or a store of your own, read and write the address around select, as the Link to a place example does.

Location attributes

Attribute What
location-id The location’s id (not id, which must be unique on the page)
lat, lng A marker’s position, or a circle’s centre
title Its title: the list label, the accessible name on the map and its popup’s heading
type marker (the default) or circle; a polyline or polygon needs a path, and a multipolygon its polygons, so they go in the map’s inline JSON (data)
group Its group: a name, or a path written as JSON when it starts with [ (group='["Europe","Italy"]'); a value starting with [ that isn’t a JSON list is misuse
tags Its tags, split on spaces, as class is: a tag written here can’t hold a space
search-text Its searchText
radius A circle’s radius, in metres
icon A marker’s image URL
zoom The zoom selecting it shows it at
weight A marker’s weight on a heatmap, as a number
listed "false" keeps it out of the list; on the map still
editable Lets the user drag or reshape it
active Marks a shape active: drawn in the hovered look while neither hovered nor selected
shape-style, selected-style, hovered-style, active-style A shape’s style, selectedStyle, hoveredStyle and activeStyle, as JSON (not style: that is HTML’s inline CSS)

Each attribute sets the location field of the same meaning. Booleans are as HTML writes them: present, empty or "true" is true, "false" false, anything else misuse naming the attribute.

Templates

A <template> child of <maplace-location> is the popup’s content, and a <template data-icon> child the marker, in place of icon (one element, or a span around the rest), cloned for each state: the location’s icon is then a function building it, which a list view of yours can call too. Templates are the page’s own markup and trusted, so they skip sanitize; html set through locations still needs it.

Data

A map’s locations come from the locations property once it is set; else from one inline <script type="application/json"> child, or from <maplace-location> children. Both a script and location children is misuse. Children and the script are watched for changes. The element never fetches: to load data from a URL, fetch it and set locations.

<!doctype html>
<script src="https://cdn.jsdelivr.net/npm/@maplacejs/maplace@1/dist/maplace-element.iife.js"></script>
<!-- An editable area; edits are written back and announced. -->
<maplace-map id="polygon-map" api-key="YOUR_KEY">
  <script type="application/json">
    [{ "id": "park", "type": "polygon", "title": "Hyde Park", "editable": true,
       "path": [{ "lat": 51.512, "lng": -0.175 }, { "lat": 51.513, "lng": -0.16 }, { "lat": 51.503, "lng": -0.155 }] }]
  </script>
</maplace-map>
<script>
  document.getElementById('polygon-map').addEventListener('maplace-locationchange', (event) => save(event.detail.location));
</script>

A map waits for the document to parse its children before it opens, whether parsed or created by a script, so its first view and selected-id see them all.

Providers

defineProvider(name, factory) registers a provider for provider="<name>": the factory gets the element and returns an adapter. @maplacejs/maplace/element/google registers google, and @maplacejs/maplace/element/maplibre registers maplibre. With both registered (both element entries imported from npm), each map names one with provider, else the map is misuse naming provider (several providers are registered ("google", "maplibre"): set provider). A map naming a provider not registered yet opens once it is.

List views

defineListView(name, factory) registers a list view for list="<name>". The factory gets the store and a setup: options, the list options from the attributes (fitAll, fitAllLabel, heading, groupCounts, scope, sort, distanceUnit, areaOnlyLabel, showAllLabel, emptyAreaLabel, search, searchLabel, noMatchesLabel, matchesLabel, groupFilter, groupFilterLabel; a switch and its label come as written, so a view of yours that shows a fit-all entry or a search box checks fitAll or search, and brings its own words when the label is missing), and listed(), the locations Maplace.js’s own lists show now, to read again on each store change; a list with scope narrows them to its view in “This area”, so a view of yours with scope scopes itself. It returns a ListView, placed by list-position as the built-in ones are. A name defined after the map opened builds its list then. Defining a built-in name (select, true), or one already given to another factory, throws; a list naming a view not defined is misuse until it is. listed() stays in data order: a view with sort sorts itself, with distanceTo.

A page on the CDN script, which imports nothing, calls it as Maplace.defineListView. The custom-list example defines one.

A list view is also how the element puts a control of yours on the map, since it gives no adapter to call mountControl on. The view’s element can be anything, and it can hold a built-in list beside your control:

Maplace.defineListView("list-and-picker", (maplace, { options }) => {
  const list = Maplace.createListView(maplace, { ...options, as: "select" });
  const element = document.createElement("div");
  element.append(yourControl, list.element);
  return {
    element,
    destroy() {
      list.destroy();
      element.remove();
    },
  };
});

Then list="list-and-picker" list-position="top-right" puts both in that corner. Controls in a second corner take the parts and mountControl.

Misuse

Where no caller can catch a throw, misuse sets the element’s error state (loadState and :state(error)) and dispatches maplace-error; nothing fails silently. The error stands until the misuse is corrected: bad locations or a bad route keep the previous ones until valid ones are given, and a selected-id the locations don’t have is selected once they do. The codes are in the API reference, the rules in RFC §3 Errors.

Vue and Svelte

Vue and Svelte use the elements as they are, with no wrapper. Import an element entry in the component, or anywhere before the app mounts. With server rendering (Nuxt, SvelteKit), render the map in the browser only, in a component that imports the entry and renders only there (Nuxt’s .client.vue, a SvelteKit page with ssr = false), so the elements are defined before it mounts.

Vue is told that maplace- tags are custom elements, not components, in its compiler options, here those of @vitejs/plugin-vue:

vue({ template: { compilerOptions: { isCustomElement: (tag) => tag.startsWith("maplace-") } } })
<script setup lang="ts">
import "@maplacejs/maplace/element/google";
import type { Location } from "@maplacejs/maplace";
import type { MaplaceElementEventMap } from "@maplacejs/maplace/element";

const locations: Location[] = [{ id: "rome", lat: 41.9028, lng: 12.4964, title: "Rome" }];
const showSelected = (event: MaplaceElementEventMap["maplace-selectionchange"]) =>
  console.log(event.detail.id);
</script>

<template>
  <maplace-map api-key="YOUR_KEY" list map-options='{"maxZoom": 12}' :locations.prop="locations"
    @maplace-selectionchange="showSelected"></maplace-map>
</template>

Svelte takes the tags as they are:

<script lang="ts">
  import "@maplacejs/maplace/element/google";
  import type { Location } from "@maplacejs/maplace";

  const locations: Location[] = [{ id: "rome", lat: 41.9028, lng: 12.4964, title: "Rome" }];
</script>

<maplace-map api-key="YOUR_KEY" list map-options={JSON.stringify({ maxZoom: 12 })} {locations}
  onmaplace-selectionchange={(event) => console.log(event.detail.id)}></maplace-map>
  • Attributes are written as in HTML; a JSON one, such as map-options or a location’s shape-style, is a string, written out or made with JSON.stringify. A switch, such as cluster or hold, takes false as "false", which is how both frameworks write it, and that is off (hold only as the map would open: release() opens a held map); other attributes are written or left out, never given false. Svelte 5 writes a bare attribute as "true", which list takes as the built-in list. A location’s listed and editable take false as "false", their off value.
  • locations is a property, as are route, sanitize and computeRoute: Vue sets each as one with .prop (:locations.prop), even before the element is defined. Svelte sets one as a property (locations={…}) once the element is defined, so the entry is imported before the component mounts.
  • Events are listened to by their names: @maplace-selectionchange in Vue, onmaplace-selectionchange in Svelte 5 and on:maplace-selectionchange in Svelte 4, the event typed with its detail; a listener for another event, such as a page’s own, types its parameter itself.
  • Popups and icons in Vue come through locations, not a <maplace-location>’s <template> child: Vue renders a template’s children into the element, not its content, so the child arrives empty.
  • Anything more goes through the element itself, taken with ref in Vue or bind:this in Svelte: its properties and methods, such as its maplace store.

The types of @maplacejs/maplace/element reach both frameworks’ template checks (vue-tsc, svelte-check): the elements’ attributes, those four properties and the events; other attributes, such as class, pass. A project with neither loads none of their types.