API reference
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 }), notselect(id, false). - Absence is
undefined, nevernull. - 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.