Why This Library?

Most React Native map libraries were built on the old Bridge. We built ours on C++ JSI — native calls with zero serialization.

| | react-native-maps | @rnmapbox | nitro-maps | |----------------------|-------------------|-----------|-----------------------------| | Architecture | Old Bridge | JS-heavy | C++ JSI (Nitro Modules) | | Clustering | JS thread (slow) | JS thread | C++ Supercluster engine | | Marker rendering | React views | Mixed | Native bitmaps | | Vendors | Google, Apple | Mapbox | Google, Apple, Yandex | | 30K markers | ❌ Freezes | ⚠️ Slow | ✅ < 40ms |

Highlights

• 🚀 C++ JSI — Nitro Modules bridge, zero serialization overhead
• 🗺️ Multi-vendor — Google Maps · Apple MapKit · Yandex MapKit, one unified API
• 📍 C++ clustering — Supercluster + KDBush handles 30,000+ markers
• 💰 Native markers — Price pills, images rendered as bitmaps — no React views
• ⚡ Live clustering — Real-time cluster updates during pan/zoom gestures
• 🌙 Dark mode — Built-in dark theme support across all vendors
• 📱 New Architecture — Fabric-ready, TurboModules compatible

Quick Start

npm install @maydon_tech/react-native-nitro-maps react-native-nitro-modules
cd ios && pod install

import {
  NitroMap,
  NitroMapInitialize,
  PriceMarker,
  type NitroMapRef,
} from '@maydon_tech/react-native-nitro-maps';

// Initialize once at app startup
NitroMapInitialize({ provider: 'google', googleApiKey: 'YOUR_API_KEY' });

export default function App() {
  const mapRef = useRef<NitroMapRef>(null);

  return (
    <NitroMap
      ref={mapRef}
      provider="google"
      initialRegion={{
        latitude: 41.2995,
        longitude: 69.2401,
        latitudeDelta: 0.05,
        longitudeDelta: 0.05,
      }}
      clusterConfig={{
        enabled: true,
        strategy: 'supercluster',
        radius: 80,
      }}
    >
      <PriceMarker
        coordinate={{ latitude: 41.2995, longitude: 69.2401 }}
        price="150K"
        currency="UZS"
      />
    </NitroMap>
  );
}

Imperative Methods (via ref)

// Animate to a region
mapRef.current?.animateToRegion({
  latitude: 41.31,
  longitude: 69.28,
  latitudeDelta: 0.01,
  longitudeDelta: 0.01,
}, 500);

// Fit to coordinates
mapRef.current?.fitToCoordinates([
  { latitude: 41.29, longitude: 69.24 },
  { latitude: 41.31, longitude: 69.28 },
]);

// Get current camera
const camera = await mapRef.current?.getCamera();

// Center on user's current location
// (requires showsUserLocation={true} and location permissions)
mapRef.current?.centerOnUserLocation();

Providers

| Provider | iOS | Android | API Key | Notes | |-----------------|-----|---------|----------|------------------------| | Google Maps | ✅ | ✅ | Required | Best global coverage | | Apple Maps | 🔜 | — | Free | iOS only, zero SDK | | Yandex Maps | 🔜 | 🔜 | Required | Best for CIS countries |

✅ Implemented · 🔜 Planned · — Not applicable

Clustering

Two strategies, powered by a shared C++ engine:

supercluster — Groups nearby markers. Overlaps acceptable. Best for general-purpose maps.

hideOnOverlap — Same grouping, but hides lower-priority overlapping items. Every visible marker sits at its real geographic position. Best for real estate, hospitality — what Zillow and Airbnb use.

<NitroMap
  clusterConfig={{
    enabled: true,
    strategy: 'hideOnOverlap',
    radius: 80,
    realtimeClustering: true,   // live updates during gestures
    renderBuffer: 0.5,           // pre-compute 50% beyond viewport
    throttleInterval: 200,       // balance perf vs smoothness
  }}
>

| Markers | Clustering Time | |---------|-----------------| | 100 | < 1ms | | 1,000 | ~ 2ms | | 10,000 | ~ 15ms | | 30,000 | ~ 40ms |

Measured on iPhone 12, including spatial index build + cluster query.

Documentation

Getting Started

| Guide | Description | |---|---| | Installation | Package install, peer dependencies, platform setup | | Google Maps Setup | API keys, iOS Podfile, Android manifest | | Quick Start | Minimal working example in 30 lines |

Guides

| Guide | Description | |---|---| | Map Configuration | Map type, gestures, traffic, buildings, padding, dark mode | | Camera & Regions | initialRegion vs region, controlled camera, fit to coordinates | | Markers | Marker, PriceMarker, ImageMarker — all 3 types | | Marker Selection | Select/deselect, visual states, info windows | | Clustering | Supercluster vs hideOnOverlap, config, performance | | Overlays | Polylines, polygons, circles | | User Location | Blue dot, custom marker, tracking modes, permissions | | Styling & Themes | Provider-aware themes, Google JSON styles, dark mode | | Colors | ColorValue, hex(), rgb(), color presets |

API Reference

| Reference | Description | |---|---| | NitroMap | All props, events, and ref methods | | Marker | Default pin marker props | | PriceMarker | Price tag marker props | | ImageMarker | Custom image marker props | | NitroPolyline | Polyline overlay props | | NitroPolygon | Polygon overlay props | | NitroCircle | Circle overlay props | | Initialization | NitroMapInitialize, config | | Types | All exported TypeScript types |

Advanced

| Guide | Description | |---|---| | Imperative API | Ref methods, declarative vs imperative | | Performance | Large datasets, clustering tuning, memo optimization | | Provider System | Multi-provider architecture, roadmap | | Accessibility | VoiceOver, TalkBack, best practices |

Other

| Guide | Description | |---|---| | Migration | Breaking changes, migrating from react-native-maps | | Troubleshooting | Common errors, platform gotchas, FAQ |

Architecture

  React Native (JS)
        │
        ▼
  ┌─────────────┐
  │  NitroMap    │  ← React component
  │  PriceMarker │  ← Declarative children
  │  ImageMarker │
  └──────┬──────┘
         │ C++ JSI (zero-copy)
         ▼
  ┌──────────────────┐
  │  Nitro Modules   │  ← C++ bridge layer
  │  HybridObject    │
  └──────┬───────────┘
         │
    ┌────┴─────┬──────────────┐
    ▼          ▼              ▼
  Google    Apple          Yandex
  Provider  Provider       Provider
  (Swift/   (Swift)        (Swift/
   Kotlin)                  Kotlin)
    │          │              │
    ▼          ▼              ▼
  GMSMapView MKMapView    YMKMapView

Contributing

See CONTRIBUTING.md for development setup.

License

MIT · Made by Maydon Tech