munim-maps

Animated 3D models on Apple Maps for Expo and React Native: vehicles, people on the floor they are really on, power-ups and zone walls, powered by Nitro Modules.

iOS

Android

GitHub

npm

Overview

munim-maps puts animated 3D models on Apple Maps in React Native, anchored to real coordinates and moving in the same frame as the map. Use it with the map you already have (it draws over react-native-maps or any MapKit map) or on its own MunimMapView. It ships a catalogue of 48 detailed vehicles, from sedans, pickups and buses to F-22s, airliners and Starship, all recolourable at runtime, plus avatars that float at a person's real height in a building with a floor badge, labelled power-ups and see-through zone walls. The camera is matched to MapKit's own on device to under a point.

Installation

Terminal

npx expo install munim-maps react-native-nitro-modules

For bare React Native without Expo: npm install munim-maps react-native-nitro-modules

Usage

3D on top of your map

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+, and iOS. A native development build is required; munim-maps cannot be added with an over-the-air update. Add usdz to Metro's assetExts to bundle models. Android renders nothing for now.

Platform notes

iOS

MapKit, MunimMapView and MapModelLayer over react-native-maps. Self-test 11/11 under a point on iPhone 17 Pro and iPad Air. 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

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

A MapKit map with models built in: standard, muted, hybrid and imagery styles, flat or realistic elevation, setCamera and getCamera.

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

•Use your own map - Draws over react-native-maps or any MapKit map, or use the built-in MunimMapView
•3D models at real coordinates - USDZ, USD, SCN or OBJ files, bundled, local or downloaded and cached
•48-vehicle catalogue - Cars, trucks, buses, bikes, motorcycles, trains, boats, airliners, F-16, F-22, F-35, YF-23, a helicopter, a balloon and rockets
•Runtime paint - tint recolours a model, so one file comes in any colour
•People in buildings - Avatars float at their real height with a stem to the ground and a floor badge
•Riders, labels and power-ups - Lift an avatar over a vehicle, float labels, spin glowing gems
•Zone walls - Circles and polygons stand up as see-through walls with solid edges
•Screen-size models - Keep a model the same size on screen at any zoom, like a marker
•Matched to MapKit - Under a point against MKMapView.convert, and within 0.2 px of MapKit's overlays mid-animation
•Taps - onModelPress with the model's id while the map keeps every gesture
•Nitro Modules - Fully typed Swift, C++ and TypeScript bindings with Metal rendering

For the latest API reference, usage examples, and troubleshooting, visit the GitHub repository and npm package page.