munim-maps
One React Native map API over MapKit, Google Maps, Mapbox, MapLibre and Cesium on iOS and Android, with every engine's features and animated 3D built in, powered by Nitro Modules.
Overview
munim-maps is one map component for React Native over five engines: Apple MapKit, Google Maps, Mapbox, MapLibre (OpenStreetMap, no key) and Cesium, on iOS and Android. Choose the engine per map; markers, shapes, camera, events and 3D models work the same everywhere, and each engine's own features are there too: Google's indoor maps, Street View and photorealistic 3D, Mapbox's Standard style, globe, terrain and offline packs, MapLibre's full style spec with a globe, terrain and sky, Cesium's 3D Tiles and CZML. Animated 3D is built in, from vehicles and people on the floor of a building to rocket launches and satellites on the globe; engines that draw 3D models themselves render them natively. The 57-model vehicle catalogue is the separate munim-maps-vehicles package, loaded from a CDN and cached on the device.
Installation
npx expo install munim-maps munim-maps-vehicles react-native-nitro-modulesFor bare React Native without Expo: npm install munim-maps react-native-nitro-modules
Usage
import MapView from 'react-native-maps'
import { MapModelLayer, type MapModel } from 'munim-maps'
import { VEHICLES } from 'munim-maps-vehicles'
const models: MapModel[] = [
{
id: 'friend',
coordinate: { latitude: 41.8853, longitude: -87.6318 },
altitude: 15, // metres above the ground
image: { uri: avatarUrl },
imageBorder: { color: '#0A84FF', width: 3 },
badge: '5F',
stem: '#0A84FF',
},
{
id: 'car',
coordinate: { latitude: 41.8841, longitude: -87.6244 },
source: VEHICLES['car-ev'],
tint: '#E5484D',
heading: 90,
screenSize: 15,
},
]
<View style={{ flex: 1 }}>
<MapView style={StyleSheet.absoluteFill} testID="map" pitchEnabled />
<MapModelLayer mapTestID="map" models={models} onModelPress={(id) => {}} />
</View>Requirements
React Native with the New Architecture, react-native-nitro-modules 0.36.5+, iOS 15+ and Android. A native development build is required. Google Maps, Mapbox and Cesium ion need your own keys; MapKit and MapLibre need none.
Platform notes
iOS
MapKit, MunimMapView and MapModelLayer over react-native-maps, or Swift Package Manager without React Native. Self-test 24/24 on iPhone 17 Pro, under a point against MapKit. Models draw over MapKit's 3D buildings, which do not share a depth buffer.
Android
Not yet; both components render nothing. Mapbox's own ModelLayer draws glTF models natively. Android on MapLibre is on the roadmap.
API
Methods
<MapModelLayer models zones mapTestID />
Draws models and zone walls over an existing MapKit map, such as react-native-maps on iOS, found by testID or as the nearest map.
Returns: Component
<MunimMapView initialCamera models markers polylines paths globe />
A full MapKit map with models built in: markers, shapes, tile overlays, standard, muted, hybrid and imagery styles, a globe when zoomed out, every map event, setCamera, animateCamera, fitToCoordinates, snapshots, geocoding and Look Around.
Returns: Component
measureAlignment()
Compares every model's ground point with MapKit's projection and checks the rendered pixels.
Returns: Promise<MapAlignmentReport>
Types
MapModel
One model on the map. Only id and coordinate are required.
| Property | Type | Description |
|---|---|---|
| coordinate | { latitude, longitude } | Where the model's base sits. |
| altitude | number | Metres above the ground. |
| source | number | string | USDZ, USD, SCN or OBJ: require(), file:// or http(s)://. |
| tint | string | Recolours the model's paint. |
| image / badge / stem | image, string, boolean | string | A camera-facing avatar, a pill such as 5F, and a line to the ground. |
| label / lift | string / number | A floating text pill, and a lift in points over another model. |
| screenSize | number | Keep the model this many points tall at any zoom. |
| heading / spinDegreesPerSecond | number | Facing and continuous spin. |
MapZone
A see-through wall on a zone outline.
| Property | Type | Description |
|---|---|---|
| circle / polygon | { center, radius } / coordinates | The outline. |
| height | number | Wall height in metres. |
| color | string | #RRGGBBAA; the alpha sets how see-through the wall is. |
Features
- •Five map engines - MapKit, Google Maps, Mapbox, MapLibre and Cesium behind one MunimMapView, chosen per map with provider
- •Every engine's features - Google indoor maps, Street View and photorealistic 3D on iOS and Android; Mapbox Standard, globe, terrain and offline; MapLibre's full style spec, globe, terrain and sky; Cesium 3D Tiles and CZML
- •iOS and Android - The same props, events and models on both platforms (MapKit on iOS)
- •Native 3D where the engine has it - Mapbox, Cesium and Google's 3D map draw models themselves; the others use munim's 3D layer
- •57-model catalogue - munim-maps-vehicles: cars, trucks, buses, bikes, trains, boats, aircraft, jets, rockets, Starbase and spacecraft, from a CDN or bundled
- •React Native views as markers - MarkerView on every engine, with dragging and continuous drag events
- •MapKit services - Place search and autocomplete, directions, geocoding, Look Around and snapshots
- •Terrain height - Altitudes above sea level sit on real mountains
- •Satellites, launches and effects - Orbits on the globe, exhaust, smoke and contrails
- •People in buildings - Avatars float at their real height with a floor badge
- •Use your own map - The 3D layer also draws over react-native-maps, expo-maps and, on Android, @rnmapbox/maps
- •Nitro Modules - Fully typed Swift, Kotlin, C++ and TypeScript bindings
For the latest API reference, usage examples, and troubleshooting, visit the GitHub repository and npm package page.