maiaddyDeveloper
@maimaps/react-native · v0.1.1 · Beta

Maimaps React Native SDK

React Native bindings — a keyed MapLibre map view, route shapes, and the full JS client surface re-exported.

Package

@maimaps/react-native

Version

v0.1.1

Registry

npm

Platforms

React Native 0.74+ • iOS, Android

Requires

@maplibre/maplibre-react-native ^10, react >=18, react-native >=0.74

Status

Beta — 0.x, minors may break

Get an API keyView quickstart

Overview

Builds on @maimaps/js for the REST surface and pairs with @maplibre/maplibre-react-native for display. MaimapsMapView builds the keyed style URL for you, so tiles, sprites, and glyphs authenticate without header support. The provider and hooks mirror @maimaps/react exactly, so the two codebases stay portable.

Every endpoint this SDK wraps is documented, with request parameters and response bodies, in the Maimaps API reference. This page documents the SDK surface itself.

Install

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

Requires @maplibre/maplibre-react-native ^10, react >=18, react-native >=0.74, which you install yourself as peer dependencies.

Quickstart

Replace mk_test_your_key with a MAIMAPS key from the console. Keys are mk_live_… for LIVE and mk_test_… for TEST; nothing else in your code changes between the two.

MapScreen.tsx
import { MaimapsProvider, MaimapsMapView, useSearch } from "@maimaps/react-native";

function MapScreen() {
  const { execute, data } = useSearch();

  return (
    <MaimapsMapView
      style={{ flex: 1 }}
      styleMode="dark"
      camera={{ centerCoordinate: [7.4951, 9.0579], zoomLevel: 12 }}
      myLocationEnabled
      onPress={() => execute({ q: "garki market" })}
    />
  );
}

export default function App() {
  return (
    <MaimapsProvider apiKey="mk_test_your_key">
      <MapScreen />
    </MaimapsProvider>
  );
}

Provider & hooks

The provider, the client hook, and the four async hooks are identical in shape to @maimaps/react — same props, same MaimapsAsyncResult, same stale-response guard. The whole of @maimaps/js is re-exported here too.

<MaimapsProvider>

Signature
<MaimapsProvider apiKey="mk_test_your_key">
  <App />
</MaimapsProvider>

Same contract as the React provider: apiKey, environment, apiBaseUrl, mapBaseUrl, or a pre-built client.

Hooks

Signature
useMaimaps(): MaimapsClient
useSearch(): MaimapsAsyncResult<SearchParams, SearchResult[]>
useRoute(): MaimapsAsyncResult<RouteParams, RouteResult>
useReverseGeocode(): MaimapsAsyncResult<ReverseGeocodeParams, ReverseGeocodeResult>
usePointDetails(): MaimapsAsyncResult<PointDetailsParams, PointDetails>

See the React SDK for the full hook documentation; the behavior is the same.

Map components

Built on @maplibre/maplibre-react-native, which is a peer dependency. This needs a native build: the map will not run in Expo Go.

<MaimapsMapView>

Signature
interface MaimapsMapViewProps extends Omit<ComponentProps<typeof MapView>, 'mapStyle'> {
  styleFamily?: string;
  styleMode?: 'light' | 'dark';
  camera?: MaimapsCameraProps;
  myLocationEnabled?: boolean;
  followUserLocation?: boolean;
  wordmarkPosition?: 'bottom-left' | 'top-left' | 'top-right' | 'bottom-right';
  children?: ReactNode;
}

The map view. It builds the keyed style URL for you, which is why mapStyle is omitted from the props it inherits. Everything else from MapLibre RN's MapView passes straight through.

<RouteShape>

Signature
interface RouteShapeProps {
  coordinates: ReadonlyArray<readonly [number, number]>;   // [lng, lat] pairs
  color?: string;   // DEFAULT_ROUTE_COLOR = '#2563eb'
  width?: number;   // DEFAULT_ROUTE_WIDTH = 4
  id?: string;
}

Draw a route line. Like the React RoutePolyline, it wants [lng, lat] while decodePolyline gives [lat, lng]. Flip first.

MaimapsCamera, MaimapsUserLocation

Signature
export { Camera as MaimapsCamera, UserLocation as MaimapsUserLocation };

MapLibre RN's Camera and UserLocation, re-exported under Maimaps names so you can compose a map without a second import from the peer package.

Pure helpers

These carry no React or native dependency, which makes them the parts you can unit-test on plain Node, and the escape hatch when you want to drive MapLibre RN directly.

buildStyleURL(client, props?)

Signature
buildStyleURL(client: Pick<MaimapsClient, 'styleUrl'>, props?: { styleFamily?: string; styleMode?: 'light' | 'dark' }): string

The keyed style URL MaimapsMapView would use. Call it yourself if you are rendering a raw MapLibre RN MapView.

routeFeature(coordinates)

Signature
routeFeature(coordinates: ReadonlyArray<readonly [number, number]>): RouteLineFeature

Wrap [lng, lat] pairs into a GeoJSON LineString Feature, ready for a ShapeSource.

routeLineLayerStyle(color?, width?)

Signature
routeLineLayerStyle(color?: string, width?: number): RouteLineLayerStyle

The LineLayer style RouteShape applies: round caps and joins, with your color and width.

resolveCameraProps(camera, followUserLocation)

Signature
resolveCameraProps<T extends object>(camera: T | undefined, followUserLocation: boolean | undefined): (T & CameraFollowFields) | undefined

Merge the followUserLocation flag into camera props, matching how MaimapsMapView resolves the two.

Resources

Maimaps API reference View on npm Get an API key

This SDK is 0.1.0 and in beta. Breaking changes can land in minor versions until 1.0.0, so pin the version if you need stability.