@maimaps/react

React bindings for the Maimaps platform: a MapLibre GL map wired to the Maimaps engine, marker and route components, and hooks for search, routing, reverse geocoding, and point details. Built on @maimaps/js (re-exported in full).

Install

npm install @maimaps/react @maimaps/js maplibre-gl react react-dom

Peer dependencies: react >= 18, react-dom >= 18, maplibre-gl ^5.

Quickstart

import { MaimapsMap, MaimapsProvider } from '@maimaps/react';
import 'maplibre-gl/dist/maplibre-gl.css';

export function App() {
  return (
    <MaimapsProvider apiKey="mk_test_…">
      <div style={{ width: '100vw', height: '100vh' }}>
        <MaimapsMap center={[3.3792, 6.5244]} zoom={12} styleMode="light" />
      </div>
    </MaimapsProvider>
  );
}

MaimapsProvider owns a MaimapsClient; environment defaults to staging. MaimapsMap builds its style URL via the client's styleUrl() and appends the API key to every map-host /sdk/ resource request via transformMapResource() (MapLibre transformRequest). The map is removed on unmount.

Components

• <MaimapsMap styleFamily? styleMode? center? zoom? onClick? onLoad? mapLibreOptions? className? style? ref?> — the map. ref exposes { getMap(): maplibregl.Map | null } for imperative work (flyTo, …). Changing styleFamily/styleMode swaps the style in place.
• <Marker longitude latitude>{children?}</Marker> — default pin, or custom content portaled into the marker element.
• <RoutePolyline coordinates color? width?> — GeoJSON line source + layer managed for you. Coordinates are [longitude, latitude]; flip decodePolyline output: decodePolyline(route.geometry).map(([lat, lng]) => [lng, lat]).
• <UserLocation follow? autoStart? showAccuracyCircle? position? onLocate? onError?> — the user's location on the map (dot + accuracy circle + geolocate button). By default it starts locating when the map loads and follows the user as they move; set autoStart={false} to wait for the button press, follow={false} for locate-once. Browser geolocation requires a secure (HTTPS) context and user permission — on denial the map simply renders without the dot.

Hooks

useSearch(), useRoute(), useReverseGeocode(), usePointDetails() — each returns { data, error, loading, execute(params) }. execute resolves with the data (or undefined on failure; the typed error lands in error). Out-of-order responses are dropped, so rapid re-queries never show stale results.

const search = useSearch();
// …
const results = await search.execute({ q: 'national theatre', limit: 5 });

useMaimaps() returns the underlying MaimapsClient for anything else (loccode resolve, advanced routing, …); useMaimapsMap() returns the maplibre map inside <MaimapsMap> children.

See examples/react_basic and examples/react_search_route in this repo.