react-native-nitro-map

⚠️ BETA - Work in Progress

This library is currently in active development and beta testing. APIs may change without notice. Do not use in production until a stable release is announced.

A high-performance multi-provider maps library for React Native, built with Nitro Modules for native speed.

✨ Features

• 🚀 Native Performance - Built with Nitro Modules for maximum speed
• 🗺️ Multi-Provider - Apple Maps, Google Maps, and Yandex Maps support
• 📍 High-Performance Clustering - C++ clustering engine for 30,000+ markers
• 🎨 Customizable Markers - Price and Image marker styles
• 🌙 Dark Mode Support - Built-in dark theme
• 📱 iOS & Android - Full platform support

Supported Providers

Provider	iOS	Android	Notes
Apple Maps	✅ iOS 17+	❌	No API key required
Google Maps	✅	✅	Requires API key
Yandex Maps	✅	✅	Requires API key

Installation

npm install react-native-nitro-map react-native-nitro-modules
# or
yarn add react-native-nitro-map react-native-nitro-modules

iOS Setup

cd ios && pod install

Android Setup

We recommend using react-native-config to securely manage API keys via .env files.

1. Install react-native-config

npm install react-native-config
# or
yarn add react-native-config

2. Create .env file (add to .gitignore)

GOOGLE_MAP=your_google_maps_api_key
YANDEX_MAP=your_yandex_maps_api_key

3. Update android/app/build.gradle

apply plugin: "com.android.application"
apply plugin: "com.facebook.react"

// Add this line to load .env variables
apply from: project(':react-native-config').projectDir.getPath() + "/dotenv.gradle"

android {
    defaultConfig {
        // Expose .env variables to AndroidManifest
        manifestPlaceholders = [
            GOOGLE_MAP: project.env.get("GOOGLE_MAP") ?: "",
            YANDEX_MAP: project.env.get("YANDEX_MAP") ?: ""
        ]
    }
}

4. Update android/app/src/main/AndroidManifest.xml

<application>
  <!-- Google Maps -->
  <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="${GOOGLE_MAP}"/>

  <!-- Yandex Maps (if using) -->
  <meta-data
    android:name="com.yandex.android.mapkit.ApiKey"
    android:value="${YANDEX_MAP}"/>
</application>

Alternative: Hardcoded Keys (Not Recommended)

If you prefer not to use react-native-config, you can hardcode keys directly in AndroidManifest.xml:

<meta-data
  android:name="com.google.android.geo.API_KEY"
  android:value="YOUR_GOOGLE_MAPS_API_KEY"/>

⚠️ Warning: Hardcoding API keys in source files is insecure. Keys can be extracted from the APK and may be exposed in version control.

Initialization

Before using the map, you must initialize it with your API key:

import { useEffect } from 'react';
import {
  NitroMapInitialize,
  IsNitroMapInitialized,
} from 'react-native-nitro-map';
import Config from 'react-native-config';

function App() {
  useEffect(() => {
    // Initialize once at app startup
    // Google Maps
    NitroMapInitialize(Config.GOOGLE_MAP!, 'google');

    // OR Yandex Maps
    // NitroMapInitialize(Config.YANDEX_MAP!, 'yandex');

    // OR Apple Maps (no API key required)
    // NitroMapInitialize('', 'apple');

    // Check if initialized
    if (IsNitroMapInitialized()) {
      console.log('Map is ready!');
    }
  }, []);

  return <NitroMap provider="google" />;
}

Important: You must call NitroMapInitialize before rendering any NitroMap component.

Platform Notes

Platform	Google Maps	Yandex Maps
iOS	API key passed via NitroMapInitialize	API key via NitroMapInitialize
Android	API key from AndroidManifest.xml (build time)	API key via NitroMapInitialize

On Android, Google Maps reads the API key from the manifest at build time. The NitroMapInitialize call still initializes the SDK, but the key must be in the manifest (use react-native-config to inject it securely from .env).

Quick Start

import { useEffect } from 'react';
import {
  NitroMap,
  NitroMapInitialize,
  PriceMarker,
  ImageMarker,
} from 'react-native-nitro-map';
import Config from 'react-native-config';

export default function App() {
  // Initialize once at app startup
  useEffect(() => {
    NitroMapInitialize(Config.GOOGLE_MAP!, 'google');
  }, []);

  return (
    <NitroMap
      provider="google" // "google" | "apple" | "yandex"
      initialRegion={{
        latitude: 41.2995,
        longitude: 69.2401,
        latitudeDelta: 0.05,
        longitudeDelta: 0.05,
      }}
    >
      <PriceMarker
        coordinate={{ latitude: 41.2995, longitude: 69.2401 }}
        price="150K"
        currency="USD"
      />
      <ImageMarker
        coordinate={{ latitude: 41.305, longitude: 69.245 }}
        imageUrl="https://example.com/avatar.jpg"
        width={50}
        height={50}
      />
    </NitroMap>
  );
}

Provider Selection

Choose your map provider based on your needs:

// Apple Maps - No API key, iOS 17+ only
<NitroMap provider="apple" />

// Google Maps - Requires API key, best coverage
<NitroMap provider="google" />

// Yandex Maps - Requires API key, best for CIS regions
<NitroMap provider="yandex" />

Feature	Apple	Google	Yandex
API Key Required	❌	✅	✅
Satellite View	✅	✅	⚠️ Needs permission
Clustering Engine	C++	C++	C++
Min iOS Version	17.0	12.0	12.0
Max Markers (tested)	30,000	30,000	30,000

NitroMap Props

Prop	Type	Default	Description
provider	'google' | 'apple' | 'yandex'	'google'	Map provider
initialRegion	Region	-	Initial map region
showsUserLocation	boolean	false	Show user location dot
showsMyLocationButton	boolean	false	Show location button
mapType	'standard' | 'satellite' | 'hybrid'	'standard'	Map style
darkMode	boolean	false	Enable dark theme
zoomEnabled	boolean	true	Allow zoom gestures
scrollEnabled	boolean	true	Allow scroll gestures
rotateEnabled	boolean	true	Allow rotation gestures
pitchEnabled	boolean	true	Allow pitch/tilt gestures
clusterConfig	ClusterConfig	-	Marker clustering settings

Events

Prop	Type	Description
onMapReady	() => void	Map finished loading
onPress	(event: MapPressEvent) => void	Map tap
onLongPress	(event: MapPressEvent) => void	Map long press
onRegionChange	(event: RegionChangeEvent) => void	Region changing
onRegionChangeComplete	(event: RegionChangeEvent) => void	Region change ended
onMarkerPress	(event: MarkerPressEvent) => void	Any marker tapped
onClusterPress	(event: ClusterPressEvent) => void	Cluster tapped

NitroMap Methods

Access methods via ref:

const mapRef = useRef<NitroMapRef>(null);

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

// Select marker (changes color, no React re-render!)
mapRef.current?.selectMarker('marker-id');

// Fit to coordinates
mapRef.current?.fitToCoordinates(
  [
    { latitude: 41.299, longitude: 69.24 },
    { latitude: 41.31, longitude: 69.25 },
  ],
  { top: 50, bottom: 50, left: 50, right: 50 },
  true
);

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

// Get boundaries
const bounds = await mapRef.current?.getMapBoundaries();

Method	Description
animateToRegion(region, duration?)	Animate camera to region
fitToCoordinates(coords, padding?, animated?)	Fit map to coordinates
animateCamera(camera, duration?)	Animate to camera position
setCamera(camera)	Set camera immediately
getCamera()	Get current camera
getMapBoundaries()	Get visible region bounds
addMarker(marker)	Add marker programmatically
addMarkers(markers)	Add multiple markers
updateMarker(marker)	Update existing marker
removeMarker(id)	Remove marker by ID
clearMarkers()	Remove all markers
selectMarker(id)	Select marker (native styling)
setClusteringEnabled(enabled)	Toggle clustering
refreshClusters()	Force clustering refresh

PriceMarker Component

Display price tags on the map with zero re-render selection:

import { PriceMarker, Colors } from 'react-native-nitro-map';

<PriceMarker
  coordinate={{ latitude: 41.2995, longitude: 69.2401 }}
  price="150K"
  currency="USD"
  selected={false}
  backgroundColor={Colors.white}
  selectedBackgroundColor={Colors.red}
  textColor={Colors.black}
  selectedTextColor={Colors.white}
  fontSize={14}
  onPress={() => console.log('Pressed!')}
/>;

PriceMarker Props

Prop	Type	Default	Description
coordinate	Coordinate	Required	Marker position
price	string	Required	Price text (e.g., "150K")
id	string	auto-generated	Unique identifier
currency	string	-	Currency code
selected	boolean	false	Selected state
backgroundColor	MarkerColor	white	Background color
selectedBackgroundColor	MarkerColor	-	Background when selected
textColor	MarkerColor	black	Text color
selectedTextColor	MarkerColor	-	Text color when selected
fontSize	number	14	Font size in pixels
paddingHorizontal	number	-	Horizontal padding
paddingVertical	number	-	Vertical padding
shadowOpacity	number	-	Shadow opacity (0-1)
draggable	boolean	false	Allow dragging
opacity	number	1	Marker opacity (0-1)
anchor	Point	{x: 0.5, y: 0.5}	Anchor point
clusteringEnabled	boolean	true	Include in clustering
animation	string	'none'	Appear animation

ImageMarker Component

Display images as map markers:

import { ImageMarker, Colors } from 'react-native-nitro-map';

<ImageMarker
  coordinate={{ latitude: 41.2995, longitude: 69.2401 }}
  imageUrl="https://example.com/avatar.jpg"
  width={50}
  height={50}
  cornerRadius={25}
  borderWidth={2}
  borderColor={Colors.white}
/>;

ImageMarker Props

Prop	Type	Default	Description
coordinate	Coordinate	Required	Marker position
id	string	auto-generated	Unique identifier
imageUrl	string	-	URL of the image
imageBase64	string	-	Base64-encoded image
width	number	50	Image width in pixels
height	number	50	Image height in pixels
cornerRadius	number	8	Corner radius
borderWidth	number	0	Border thickness
borderColor	MarkerColor	gray	Border color
draggable	boolean	false	Allow dragging
opacity	number	1	Marker opacity (0-1)
anchor	Point	{x: 0.5, y: 0.5}	Anchor point
clusteringEnabled	boolean	true	Include in clustering
animation	string	'none'	Appear animation

Marker Events

Prop	Type	Description
onPress	() => void	Marker tapped
onDragStart	(coord) => void	Drag started
onDrag	(coord) => void	Dragging
onDragEnd	(coord) => void	Drag ended

Selection Example

const MARKERS = [
  { id: 'marker-1', latitude: 41.29, longitude: 69.24, price: '100K' },
  { id: 'marker-2', latitude: 41.3, longitude: 69.25, price: '150K' },
];

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

  const onMarkerPress = useCallback((event: MarkerPressEvent) => {
    // Native handles selection styling - ZERO React re-renders!
    mapRef.current?.selectMarker(event.id);

    // Optionally trigger other UI (bottom sheet, etc.)
    fetchMarkerDetails(event.id);
  }, []);

  return (
    <NitroMap ref={mapRef} onMarkerPress={onMarkerPress}>
      {MARKERS.map((m) => (
        <PriceMarker
          key={m.id}
          id={m.id}
          coordinate={{ latitude: m.latitude, longitude: m.longitude }}
          price={m.price}
          currency="USD"
          backgroundColor={Colors.white}
          selectedBackgroundColor={Colors.red}
          textColor={Colors.black}
          selectedTextColor={Colors.white}
        />
      ))}
    </NitroMap>
  );
}

C++ Clustering Engine

All three providers use the same high-performance C++ clustering engine:

<NitroMap
  clusterConfig={{
    enabled: true,
    minimumClusterSize: 2,
    maxZoom: 20, // Clusters break into markers above this zoom
    backgroundColor: { r: 255, g: 87, b: 51, a: 255 },
    textColor: { r: 255, g: 255, b: 255, a: 255 },
    borderWidth: 2,
    borderColor: { r: 255, g: 255, b: 255, a: 255 },
    animatesClusters: true,
    animationDuration: 0.3,
    animationStyle: 'default',
  }}
  onClusterPress={(event) => {
    console.log(`Cluster with ${event.count} markers`);
    console.log('Marker IDs:', event.markerIds);

    // Zoom into cluster
    mapRef.current?.animateToRegion({
      ...event.coordinate,
      latitudeDelta: 0.01,
      longitudeDelta: 0.01,
    });
  }}
>
  {markers.map((m) => (
    <PriceMarker key={m.id} {...m} clusteringEnabled={true} />
  ))}
</NitroMap>

Performance

Markers	Apple	Google	Yandex
100	⚡ Instant	⚡ Instant	⚡ Instant
1,000	⚡ Fast	⚡ Fast	⚡ Fast
10,000	✅ Smooth	✅ Smooth	✅ Smooth
30,000	✅ Works	✅ Works	✅ Works

Color Helpers

import { rgb, hex, Colors } from 'react-native-nitro-map';

// RGB helper
const red = rgb(255, 0, 0); // { r: 255, g: 0, b: 0, a: 255 }
const semiRed = rgb(255, 0, 0, 128); // 50% opacity

// Hex helper
const blue = hex('#0000FF');
const semiBlue = hex('#0000FF', 128);

// Preset colors
Colors.red; // { r: 255, g: 59, b: 48, a: 255 }
Colors.blue; // { r: 0, g: 122, b: 255, a: 255 }
Colors.green; // { r: 76, g: 175, b: 80, a: 255 }
Colors.white; // { r: 255, g: 255, b: 255, a: 255 }
Colors.black; // { r: 0, g: 0, b: 0, a: 255 }

Types

type Region = {
  latitude: number;
  longitude: number;
  latitudeDelta: number;
  longitudeDelta: number;
};

type Coordinate = {
  latitude: number;
  longitude: number;
};

type Camera = {
  center: Coordinate;
  pitch: number;
  heading: number;
  altitude: number;
  zoom: number;
};

type MarkerColor = {
  r: number; // 0-255
  g: number; // 0-255
  b: number; // 0-255
  a: number; // 0-255
};

type MapProvider = 'google' | 'apple' | 'yandex';
type MapType = 'standard' | 'satellite' | 'hybrid';
type MarkerStyle = 'default' | 'image' | 'priceMarker';
type MarkerAnimation = 'none' | 'pop' | 'fadeIn';

Troubleshooting

Apple Maps shows "+1 more" labels

This is MapKit's native clustering. Make sure you're using provider="apple" with the C++ clustering engine enabled.

Yandex satellite mode shows "Forbidden"

Yandex satellite tiles require explicit permission in the Yandex Developer Console.

Markers not appearing

1. Check that coordinates are within visible region
2. Verify marker zIndex if markers overlap
3. Ensure clusteringEnabled is set correctly

Performance issues with many markers

1. Enable clustering: clusterConfig={{ enabled: true }}
2. Use addMarkers() for batch adding instead of individual addMarker() calls
3. Consider reducing maxZoom to keep more markers clustered

License

MIT

---

Made with Nitro Modules