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,
} from '@maydon_tech/react-native-nitro-maps';

// Initialize once at app startup
NitroMapInitialize('YOUR_API_KEY', 'google');

export default function App() {
  return (
    <NitroMap
      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>
  );
}

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

| Guide | Description | |---|---| | Setup & Installation | Per-vendor setup for iOS and Android | | API Reference | Components, props, methods, types, events | | Clustering | Strategies, live clustering, render buffer, performance | | Feature Support | What's available on each provider | | Examples | Selection, dragging, clustering, overlays | | Migration | Breaking changes between versions |

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)
    │          │              │
    ▼          ▼              ▼
  GMSMapView MKMapView    YMKMapView

Contributing

See CONTRIBUTING.md for development setup.

License

MIT · Made by Maydon Tech