@maimaps/react-native

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

Install

npm install @maimaps/react-native @maimaps/js @maplibre/maplibre-react-native

Peer dependencies: react >= 18, react-native >= 0.74, @maplibre/maplibre-react-native ^10.

@maplibre/maplibre-react-native contains native code — follow its installation and platform setup guide (Expo config plugin or bare iOS/Android setup). Expo Go is not supported; use a development build.

Quickstart

import { MaimapsMapView, MaimapsProvider } from '@maimaps/react-native';

export function App() {
  return (
    <MaimapsProvider apiKey="mk_test_…">
      <MaimapsMapView
        style={{ flex: 1 }}
        styleMode="light"
        camera={{ centerCoordinate: [3.3792, 6.5244], zoomLevel: 12 }}
      />
    </MaimapsProvider>
  );
}

The style URL is built from the client's styleUrl() with the API key in the URL (?key=…) — native map views cannot set per-request headers, and the engine's /sdk/styles response references /sdk/ tile/sprite/glyph URLs that carry the key the same way.

API

• <MaimapsProvider apiKey environment? apiBaseUrl? mapBaseUrl?> — owns the MaimapsClient (useMaimaps() returns it).
• <MaimapsMapView styleFamily? styleMode? camera? myLocationEnabled? followUserLocation? …MapViewProps> — wraps MapView; camera renders a <MaimapsCamera> child for you. myLocationEnabled shows the user-location puck (dot + heading indicator) and followUserLocation makes the camera track the user (merged into camera).
• <MaimapsCamera> / <MaimapsUserLocation> — passthroughs of MapLibreRN's Camera and UserLocation for full control.
• <RouteShape coordinates color? width? id?> — GeoJSON ShapeSource + LineLayer for a route line. Coordinates are [longitude, latitude]; flip decodePolyline output: decodePolyline(geometry).map(([lat, lng]) => [lng, lat]).
• Hooks: useSearch(), useRoute(), useReverseGeocode(), usePointDetails() — { data, error, loading, execute(params) } with stale-response guarding.
• Pure helpers: buildStyleURL(client, { styleFamily, styleMode }), routeFeature(coords), routeLineLayerStyle(color?, width?), resolveCameraProps(camera, followUserLocation).

For myLocationEnabled the app must declare the platform location permission itself — ACCESS_FINE_LOCATION in the Android manifest, NSLocationWhenInUseUsageDescription in the iOS Info.plist — and request it before showing the map (e.g. with PermissionsAndroid or a permissions library). Without permission the map renders without the puck.

See examples/react_native_basic in this repo (requires a development build).