Maplace.js

React components for Google Maps and MapLibre

Markdown

@maplacejs/maplace/react is the store as React components: a provider that makes one store for its children, a map, a list, controls on the map and a hook. It needs react and react-dom 19. Nothing touches the DOM on import or on a server render.

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>,
);

<MaplaceProvider>

Makes one store on mount and keeps it as long as it is mounted. locations and the controlled props follow later renders; the store’s other options are read once, on mount, so inline objects and functions cost nothing.

Prop What
locations Required. Applied again when the array changes, never otherwise, so an edit on the map outlives a render
selectedId A controlled selection
defaultSelectedId The selection at start, when selectedId is not controlled
filter What setFilter takes: a list of groups, or { groups, tags, query }; applied when its value changes, so a fresh object of the same value costs nothing. It replaces the whole filter, so a change clears what a search box typed: with a box, leave it out and have a child call useMaplace().setFilter({ ...getSnapshot().filter, tags })
route The route; applied when its value changes, so it is computed, and billed, once per change. On MapLibre it draws through your own routing: createAdapter={() => createMapLibreAdapter({ computeRoute })} on <MaplaceMap> (routes on MapLibre)
sanitize, popup, style, selectedStyle, hoveredStyle, activeStyle, cluster, heatmap, view, skipMapLabel, selectedLabel The store’s options, read on mount
children What uses the store: <MaplaceMap>, <LocationList>, your components

An id in selectedId or defaultSelectedId not shown yet (locations still loading, or filtered out) waits until it is; one the filter hid is tried again at the next render, as the provider follows its props only then. A filter or route that app code sets through the store stands until the prop next changes. To keep the selection in the page’s address, see the Link to a place example.

Event props

One prop per store event, its listener.

Prop Event
onSelectionChange selectionChange
onHoverChange hoverChange
onMapClick mapClick
onLocationEdit locationEdit
onLocationChange locationChange
onPopupOpen popupOpen
onPopupClose popupClose
onViewportChange viewportChange
onRouteChange routeChange
onError error

Controlled selection

With a selectedId prop (present, undefined meaning nothing selected), the prop is the selection. A selection the user or app code makes calls onSelectionChange, and unless the parent passes it back in that render, the store goes back to the prop (and pans back); so onSelectionChange sets state synchronously. Changes the prop makes call nothing. Switching selectedId between controlled and not after mount, or giving both selectedId and defaultSelectedId, is invalid-input.

<MaplaceMap>

Renders a div you size and attaches a fresh adapter to it on mount, detaching on unmount, so StrictMode and <Activity> work.

Prop What
createAdapter Required. Called once per mount: an adapter drives one map. createGoogleAdapter, createMapLibreAdapter (MapLibre), or a function making one with options, such as () => createMapLibreAdapter({ globe: true }) for a globe
className Size the map through it: a map fills its container
popupContent (location) => ReactNode: a popup’s content as React content
markerIcon (location, state) => ReactNode: a marker’s icon as React content; not a heatmap’s markers, drawn as heat
children What goes on the map: <MapControl>s, <LocationList position>s and <MyLocation>, rendered beside the map’s div, never in it

popupContent and markerIcon render through a portal into one host per location (an icon’s host carries data-selected and data-hovered, as core icons do, and stacks an icon’s children: for a row, wrap them in one element), with the provider’s context, keeping their state. Returning nothing (null, undefined, a boolean) leaves the location’s own content or icon. Whether either is given is read on mount. Content that throws is an invalid-input error event naming the field, and renders nothing.

<LocationList>

The store’s list view. A change of an option builds it again.

Prop What
as "list" (a listbox, the default) or "select" (a native select)
groupHeadings Shows group headings; default true when any location has a group
groupCounts After each group heading, how many are listed under it now, following the filter and scope: “North (3)”. Off by default; refused with groupHeadings: false
fitAll 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).
fitAllLabel The words of the list’s first entry, which clears the selection and fits all locations; default “All locations”; does nothing without fitAll
label The list’s accessible name; default the heading, else “Locations”
heading A visible heading above the entries
scope "viewport": a switch above the list, “All” or “This area”, which lists only the locations in the map’s view and follows it, on the map or outside the <MaplaceMap> (List view options); for as: "list" only
areaOnlyLabel The words of the scope switch’s button that lists only the map’s view; default “This area”
showAllLabel The words of the scope switch’s button that lists every location; default “All”
emptyAreaLabel What a list with scope says when no location is in the map’s view; default “No locations in this area”
sort "distance": once the store has an origin, nearest first, each entry saying how far, and a render function gets distance and distanceLabel (Distances)
distanceUnit What sort writes a distance in: "kilometer" (the default) or "mile"
search Shows a search box above the entries; for as: "list" only (List view options)
searchLabel The search box’s placeholder and accessible name; default “Search”; does nothing without search
noMatchesLabel What the line under the search box says when nothing matches; default “No locations match”
matchesLabel What the line under the search box says before the count of matches; default “Locations found”, as “Locations found: 3”
groupFilter (1.2) A “Groups” button above the entries that opens a checkbox for each group, subgroups nested (Subgroups); for as: "list" only. A filter prop on the provider sets the boxes again when its value changes
groupFilterLabel The boxes’ accessible name; default “Groups”; does nothing without groupFilter
children For as: "list", a function rendering an entry’s content: plain content, since the entry itself is the option
position A corner, inside a <MaplaceMap>: the list itself goes on the map there while the map is attached, as the element’s list-position, so its panel hides with it and its entries scroll under its heading. Without a <MaplaceMap> it is misuse

<MapControl>

Inside a <MaplaceMap>, puts its children on the map in a corner, through the adapter’s mountControl, while the map is attached. They keep the provider’s context, and show as the page gives them: for the page’s own content. Maplace’s list goes on the map with <LocationList position>. Outside a <MaplaceMap> it is misuse; on a server it renders nothing.

Prop What
position The corner: "top-left", "top-right", "bottom-left" or "bottom-right"
children What goes on the map

<MyLocation>

Inside a <MaplaceMap>, puts the “My location” control on the map while the map is attached. Outside a <MaplaceMap> it is misuse; on a server it renders nothing. There is no origin prop: for any other point, a child calls setOrigin on what useMaplace() returns.

Prop What
position The corner: "top-left" (the default), "top-right", "bottom-left" or "bottom-right"
label The button’s words; “My location” by default
unavailableLabel What it says when no position comes; “Location unavailable” by default

useMaplace()

Returns the store of the nearest <MaplaceProvider>, to call its methods or to read its state with useSyncExternalStore(store.subscribe, store.getSnapshot). Misuse throws from render or a layout effect, to the nearest error boundary.

Server components

The entry starts with "use client", so in React Server Components it is a client boundary. A server component renders <MaplaceProvider> and <LocationList> with data (locations, defaultSelectedId, filter, route, the list’s options). What takes a function (createAdapter, on<Event> props, popupContent, markerIcon, a list’s children) goes in a client component of yours, as does a controlled selectedId, which needs its onSelectionChange. Getting started, with React has the two files.