npm package: @maydon_tech/react-native-nitro-maps
Description: A high-performance React Native map library powered by Nitro Modules with support for Apple Maps, Google Maps, and Yandex Maps. Features native clustering, custom markers, and seamless cross-platform integration.
Author: Maydon Tech
Latest version: 0.2.10

<p align="center">
  <h1 align="center">@maydon_tech/react-native-nitro-maps</h1>
</p>

<p align="center">
  <b>High-performance multi-provider maps for React Native</b><br/>
  Built on <a href="https://nitro.margelo.com/">Nitro Modules</a> — C++ JSI, zero bridge overhead
</p>

<p align="center">
  <a href="https://www.npmjs.com/package/@maydon_tech/react-native-nitro-maps"><img src="https://img.shields.io/npm/v/@maydon_tech/react-native-nitro-maps?color=0a7fca&label=npm" alt="npm version" /></a>
  <a href="https://github.com/maydongroup/react-native-nitro-maps/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@maydon_tech/react-native-nitro-maps?color=41b883" alt="license" /></a>
  <img src="https://img.shields.io/badge/platforms-iOS%20%7C%20Android-lightgrey" alt="platforms" />
  <img src="https://img.shields.io/badge/architecture-New%20Architecture-blue" alt="new architecture" />
</p>

---

## 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

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

```tsx
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)

```tsx
// 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.

```tsx
<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          |

<sub>Measured on iPhone 12, including spatial index build + cluster query.</sub>

## Documentation

### Getting Started

| Guide | Description |
|---|---|
| [**Installation**](docs-new/getting-started/installation.md) | Package install, peer dependencies, platform setup |
| [**Google Maps Setup**](docs-new/getting-started/google-maps-setup.md) | API keys, iOS Podfile, Android manifest |
| [**Quick Start**](docs-new/getting-started/quick-start.md) | Minimal working example in 30 lines |

### Guides

| Guide | Description |
|---|---|
| [**Map Configuration**](docs-new/guides/map-configuration.md) | Map type, gestures, traffic, buildings, padding, dark mode |
| [**Camera & Regions**](docs-new/guides/camera-and-regions.md) | initialRegion vs region, controlled camera, fit to coordinates |
| [**Markers**](docs-new/guides/markers.md) | Marker, PriceMarker, ImageMarker — all 3 types |
| [**Marker Selection**](docs-new/guides/marker-selection.md) | Select/deselect, visual states, info windows |
| [**Clustering**](docs-new/guides/clustering.md) | Supercluster vs hideOnOverlap, config, performance |
| [**Overlays**](docs-new/guides/overlays.md) | Polylines, polygons, circles |
| [**User Location**](docs-new/guides/user-location.md) | Blue dot, custom marker, tracking modes, permissions |
| [**Styling & Themes**](docs-new/guides/styling-and-themes.md) | Provider-aware themes, Google JSON styles, dark mode |
| [**Colors**](docs-new/guides/colors.md) | ColorValue, hex(), rgb(), color presets |

### API Reference

| Reference | Description |
|---|---|
| [**NitroMap**](docs-new/api-reference/nitro-map.md) | All props, events, and ref methods |
| [**Marker**](docs-new/api-reference/marker.md) | Default pin marker props |
| [**PriceMarker**](docs-new/api-reference/price-marker.md) | Price tag marker props |
| [**ImageMarker**](docs-new/api-reference/image-marker.md) | Custom image marker props |
| [**NitroPolyline**](docs-new/api-reference/polyline.md) | Polyline overlay props |
| [**NitroPolygon**](docs-new/api-reference/polygon.md) | Polygon overlay props |
| [**NitroCircle**](docs-new/api-reference/circle.md) | Circle overlay props |
| [**Initialization**](docs-new/api-reference/initialization.md) | NitroMapInitialize, config |
| [**Types**](docs-new/api-reference/types.md) | All exported TypeScript types |

### Advanced

| Guide | Description |
|---|---|
| [**Imperative API**](docs-new/advanced/imperative-api.md) | Ref methods, declarative vs imperative |
| [**Performance**](docs-new/advanced/performance.md) | Large datasets, clustering tuning, memo optimization |
| [**Provider System**](docs-new/advanced/provider-system.md) | Multi-provider architecture, roadmap |
| [**Accessibility**](docs-new/advanced/accessibility.md) | VoiceOver, TalkBack, best practices |

### Other

| Guide | Description |
|---|---|
| [**Migration**](docs-new/migration.md) | Breaking changes, migrating from react-native-maps |
| [**Troubleshooting**](docs-new/troubleshooting.md) | 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](CONTRIBUTING.md) for development setup.

## License

[MIT](LICENSE) · Made by [Maydon Tech](https://github.com/maydongroup)