Maplace.js

API reference

Markdown

Every export of every entry, with where it is explained, then the error codes and the capabilities. One package, one version for all entries; the package is ES modules only.

@maplacejs/maplace

The store, the list view, the GeoJSON helper, the adapter contract and the types. Side-effect-free.

Export Kind Explained in
createMaplace function Creating a store
MaplaceOptions type Store options
HeatmapOptions type Heatmaps
Maplace type Methods
Snapshot, LoadState types Snapshot
FilterRequest, LocationFilter types setFilter
LocationGroup type Subgroups
PopupOptions type Popup options
View, Viewport, Bounds, FitOptions, SelectOptions types The first view, methods
MaplaceEvents, MaplaceEventName, Listener, ListenOptions, Unsubscribe types Events
Route, RouteResult, RouteLeg, RouteStep, TravelMode types Routes
RouteComputer, RouteRequest, RouteRequestStop, RouteAnswer types Routes on MapLibre
createListView function List view options
distanceTo function Distances
createMyLocationControl, MyLocationControl, MyLocationOptions function, types The “My location” control
ListViewOptions, ListView, ListEntry types List view options
listedLocations function Listed locations
locationsFromGeoJSON function From GeoJSON
pointAlong function A point along a line
GeoJSONFeatureCollection, GeoJSONFeature types From GeoJSON
Location, MarkerLocation, CircleLocation, PolylineLocation, PolygonLocation, MultiPolygonLocation types Locations
LatLng, Geometry, MarkerGeometry, CircleGeometry, PolylineGeometry, PolygonGeometry, MultiPolygonGeometry, PolygonRings types Locations; a geometry is what a drag or edit changes
Content type Content
Icon, LocationState types Icons
LineStyle, ShapeStyle, StrokeDash types Styles
MaplaceError, MaplaceErrorDetails class, type Errors
ErrorCode, MisuseCode, RuntimeCode types Misuse codes, runtime failures
Capability type Capabilities
ControlPosition type A corner of the map: <MapControl>, <LocationList>’s position
Adapter, AdapterHost, MountContext, LocationDiff, PresentationState, Drawable, ResolvedPopupOptions, ResolvedView types The adapter contract, for a new provider: RFC §3 Shape

@maplacejs/maplace/google

The Google Maps adapter: the only entry that knows google.maps.

Export Kind Explained in
createGoogleAdapter function Google adapter
GoogleAdapterOptions type Options
createGoogleMap function createGoogleMap
GoogleMapOptions, GoogleMapList, GoogleMapMyLocation types createGoogleMap

@maplacejs/maplace/maplibre

The MapLibre GL JS adapter, on OpenFreeMap’s tiles unless a style says otherwise: the only entry that knows maplibre-gl, which the page installs, with its stylesheet.

Export Kind Explained in
createMapLibreAdapter function MapLibre adapter
MapLibreAdapterOptions, MapLibreGlobe types Options
createMapLibreMap function createMapLibreMap
MapLibreMapOptions, MapLibreMapList, MapLibreMapMyLocation types createMapLibreMap

@maplacejs/maplace/element

<maplace-map> and <maplace-location>, defined on import, with no provider registered.

Export Kind Explained in
defineProvider, ProviderFactory function, type Providers
defineListView, ListViewFactory, ListViewSetup, ElementListOptions function, types List views
ListPosition type Map attributes: list-position
MaplaceMapElement type Properties and methods
MaplaceLocationElement type Location attributes
MaplaceElementEventMap type Events

@maplacejs/maplace/element/google

The element with the Google provider registered; the Google CDN scripts are this entry bundled.

Export Kind Explained in
MaplaceMapElement type Properties and methods, provider attributes

@maplacejs/maplace/element/maplibre

The element with the MapLibre provider registered; the MapLibre CDN script is this entry bundled, with maplibre-gl.

Export Kind Explained in
MaplaceMapElement type Properties and methods, provider attributes

The CDN scripts’ Maplace

Each CDN script also sets one global, Maplace: the exports of @maplacejs/maplace, @maplacejs/maplace/element and its provider’s entry above, so a page’s own script calls Maplace.createGoogleMap(...) where an npm page imports createGoogleMap. The MapLibre script adds Maplace.maplibre, the maplibre-gl it bundles. It holds functions, no state: the store a page makes is its own (with a script of your own).

@maplacejs/maplace/react

The React binding, a client boundary ("use client").

Export Kind Explained in
MaplaceProvider, MaplaceProviderProps, MaplaceControlledProps component, types <MaplaceProvider>
MaplaceEventProps type Event props
MaplaceMap, MaplaceMapProps, PopupContentRender, MarkerIconRender component, types <MaplaceMap>
LocationList, LocationListProps component, type <LocationList>
MapControl, MapControlProps component, type <MapControl>
MyLocation, MyLocationProps component, type <MyLocation>
useMaplace hook useMaplace()

@maplacejs/maplace/testing

The conformance suite, for an adapter of your own; it needs vitest (an optional peer) in browser mode, and no page loads it.

Export Kind Explained in
describeConformance, ConformanceSubject, ConformanceGroup function, types Proving an adapter
MapProbe, LocationOnMap, ShownPopup types Proving an adapter
frontFirst, StackedLocation function, type Proving an adapter
SELECTED_LOOK, SELECTED_LINE_LOOK, HOVERED_LOOK, ORIGIN_DOT_CLASS constants Proving an adapter

Errors

Misuse throws a MaplaceError from the call that caused it, with a code and, where they apply, the locationId and the field. In the element, where no caller can catch a throw, misuse is the element’s error state and a maplace-error event instead (misuse); in React it throws from render or a layout effect, to the nearest error boundary. Runtime failures are never thrown: they are error events, with the same MaplaceError.

Misuse codes

Code When
invalid-input Bad data or arguments: a wrong or unknown field, a value out of range, a shape with too few points, a hidden location selected or hovered; the full list is in RFC §3 Errors
duplicate-id Two locations with one id
unknown-id An id not in the store: select, hover, selectedId, a route stop
unsupported-capability A feature the adapter lacks
missing-sanitizer html without sanitize
already-attached A store attached twice, or an adapter reused
destroyed A call after destroy that changes state or adds a listener

Before attach the store skips capability checks; attach checks the current state against the adapter, and afterwards each call checks before changing anything.

Runtime failures

Code When
provider-load-failed The provider, or a part it loads (maplibre-gl, its worker, a style, the clusterer), failed to load; on Google also your own map made without a map ID
provider-auth-failed The provider refused the key: Google’s, or a style’s server (HTTP 401 or 403)
route-failed A route couldn’t be computed

For the first two, loadState becomes error and whenReady() rejects; one that comes after ready moves loadState from ready to error. A map Maplace.js creates also says so on the map when it can’t be used: a panel in its container, none on your own map. An icon, content or sanitize function of yours that fails while the map draws is an invalid-input error event naming the location and the field: the map stays ready.

Capabilities

A capability is a feature an adapter may or may not support; using one the adapter lacks is unsupported-capability. Google has all six; MapLibre has route only with your own routing, as it has none (routes).

Capability What it allows
route setRoute, the element’s route and React’s route prop
cluster The cluster option
circle Circle locations
edit editable locations
multipolygon Multipolygon locations (1.2); an adapter written for 1.0 lacks it, so the store refuses them there
heatmap The heatmap option (1.2), drawn by maplace on both providers; an adapter written for 1.0 lacks it

Rules

  • camelCase throughout; verbs for methods, nouns for types, one word per concept, and no two ways to do the same thing.
  • At most two positional arguments, then an options object; never a boolean flag: select(id, { pan: false }), not select(id, false).
  • Absence is undefined, never null.
  • Views know only the store, adapters know only their host, and only the element (or your code) wires them together.

The full rules are in RFC §3.