• Features
• iOS Apple Maps clustering comparison
• Android Google Maps clustering comparison
• Requirements
• Supported platforms
• Installation
• Quick start
• Map providers
• Native POI press events
• Custom marker images
• Google Maps setup
• Marker entering animations
• Capability matrix
• Public API
• Example app
• Documentation
• Common problems
• Development
• What's next

• Performance first - Nitro Modules and JSI power zero-bridge map interactions.
• New Architecture native - Built exclusively for React Native's New Architecture: Fabric + TurboModules.
• Unified map API - One typed React API for Apple MapKit and Google Maps SDK.
• Provider-aware props - TypeScript narrows provider-specific props with MapViewPropsForProvider<P>.
• Markers and overlays - Markers with title/subtitle callouts and drag support, plus polylines, polygons, and circles.
• Native POI taps - onPoiPress reports provider-owned places from Apple Maps and Google Maps without confusing them with app-owned markers.
• Camera control - Declarative region/camera props plus imperative camera helpers.
• Marker clustering - Native marker clustering for large point sets.
• Native entering animations - Configurable marker and cluster entrance animations.
• Expo friendly - Config plugin for Google Maps API keys and location permissions.
• Tree-shakeable package - ESM-only build with an explicit exports map.

The clips below compare the same iOS Apple Maps marker clustering scenario in react-native-better-maps and react-native-maps with react-native-clusterer.

react-native-better-maps	react-native-maps + react-native-clusterer
Native MapKit-backed clustering through the Nitro map provider.	React Native Maps with JS-side clusterer integration.
Open GIF	Open GIF

The clips below compare the same Android Google Maps marker clustering scenario in react-native-better-maps and react-native-maps with react-native-clusterer.

react-native-better-maps	react-native-maps + react-native-clusterer
Native Google Maps-backed clustering through the Nitro map provider.	React Native Maps with JS-side clusterer integration.
Open GIF	Open GIF

Not supported today:

• Custom React Native marker child views such as <Marker><View /></Marker>; use bitmap marker images instead.
• openstreetmap and mapbox providers; the public provider type reserves these names for future native implementations.

Unsupported explicit providers throw before a native map view is created.

bun add react-native-better-maps react-native-nitro-modules

npm install react-native-better-maps react-native-nitro-modules

yarn add react-native-better-maps react-native-nitro-modules

pnpm add react-native-better-maps react-native-nitro-modules

For Expo apps using SDK 56+, add the config plugin to app.json or app.config.js:

export default {
  expo: {
    plugins: [
      [
        'react-native-better-maps',
        {
          googleMapsApiKey: process.env.GOOGLE_MAPS_API_KEY,
          locationPermission:
            'Allow $(PRODUCT_NAME) to use your location for map features.',
        },
      ],
    ],
  },
};

After expo prebuild, native projects have the required keys and permissions without manual edits.

Google Maps API key: Use either this plugin's googleMapsApiKey option or Expo's built-in android.config.googleMaps.apiKey. Pick one source, not both.

EAS Secrets: Store GOOGLE_MAPS_API_KEY as an EAS secret and reference it via process.env.GOOGLE_MAPS_API_KEY in app.config.js.

See docs/expo-setup.md for a full Expo SDK 56 setup walkthrough.

import { MapView, Marker, Polyline } from 'react-native-better-maps';

function MyMap() {
  return (
    <MapView
      style={{ flex: 1 }}
      mapType="standard"
      onRegionChangeComplete={(region) => console.log(region)}
    >
      <Marker
        coordinate={{ latitude: 52.2297, longitude: 21.0122 }}
        title="Warsaw"
        image={require('./assets/pin.png')}
        anchor={{ x: 0.5, y: 1 }}
        rotation={45}
        flat
        opacity={0.9}
      />
      <Polyline
        coordinates={[
          { latitude: 52.2297, longitude: 21.0122 },
          { latitude: 52.237, longitude: 21.017 },
        ]}
        strokeColor="#FF0000"
        strokeWidth={3}
      />
    </MapView>
  );
}

import { useRef } from 'react';
import { MapView, type MapViewRef } from 'react-native-better-maps';

function ControlledMap() {
  const mapRef = useRef<MapViewRef>(null);

  const flyToWarsaw = () => {
    mapRef.current?.animateCamera({
      center: { latitude: 52.2297, longitude: 21.0122 },
      zoom: 12,
    });
  };

  return <MapView ref={mapRef} style={{ flex: 1 }} />;
}

MapView accepts an optional provider prop:

import { Platform } from 'react-native';
import { MapView, type MapProvider } from 'react-native-better-maps';

const provider: MapProvider = Platform.OS === 'android' ? 'google' : 'apple';

export function ProviderMap() {
  return <MapView provider={provider} style={{ flex: 1 }} />;
}

When provider is omitted, defaults stay backward-compatible:

Changing provider remounts the native map view. Controlled props such as region, camera, overlays, and callbacks should therefore be supplied again through React props.

Provider-specific TypeScript props are exposed through MapViewPropsForProvider<P>. For example, showsScale is accepted for apple but rejected for google because Google Maps SDK has no native scale control.

Provider-owned points of interest are base-map features supplied by Apple Maps or Google Maps, such as restaurants, parks, schools, hotels, and stores. They are separate from app-owned <Marker /> elements and bulk markers; marker presses still use Marker.onPress and MapView.onMarkerPress.

onPoiPress is enabled automatically when provided. A POI tap emits only onPoiPress; it does not also emit background-map onPress.

<MapView
  provider="google"
  style={{ flex: 1 }}
  onPoiPress={(event) => {
    console.log(event.provider, event.name, event.placeId);
  }}
/>

<MapView
  provider="apple"
  style={{ flex: 1 }}
  onPoiPress={(event) => {
    console.log(event.provider, event.name, event.category, event.rawCategory);
  }}
/>

Provider-specific props narrow the callback payload:

Markers support custom bitmap icons with positioning and styling options:

<Marker
  coordinate={coord}
  image={require('./pin.png')}
  anchor={{ x: 0.5, y: 1.0 }}
  rotation={45}
  flat
  opacity={0.9}
/>

<MapView
  markers={[
    {
      id: '1',
      coordinate: coord,
      image: { uri: 'https://example.com/pin.png' },
      anchor: { x: 0.5, y: 1 },
    },
  ]}
/>

Supported image sources:

Additional props:

Platform notes:

• Recommended icon size: up to 128×128 dp; larger bitmaps are downscaled when width/height are provided.
• Retina assets: pass require() and let Metro resolve @2x/@3x; optional explicit width/height/scale on MarkerImage.
• Remote URLs use a basic in-memory cache only (no disk persistence).
• Custom React Native marker views (<Marker><View /></Marker>) are not supported.

Host apps must provide platform API keys for the Google Maps SDK.

Add the config plugin to your app config:

{
  "expo": {
    "plugins": [
      [
        "react-native-better-maps",
        {
          "googleMapsApiKey": "YOUR_KEY_HERE"
        }
      ]
    ]
  }
}

Use iosGoogleMapsApiKey and androidGoogleMapsApiKey when each platform needs a different restricted key.

The example app uses the config plugin. It reads GOOGLE_MAPS_IOS_API_KEY and GOOGLE_MAPS_ANDROID_API_KEY with GOOGLE_MAPS_API_KEY as a shared fallback.

• iOS: add a GoogleMapsIosApiKey string to Info.plist.
• Android: add com.google.android.geo.API_KEY metadata to AndroidManifest.xml.

The google provider accepts googleMapId for Google Cloud Map ID styling:

<MapView provider="google" googleMapId="YOUR_MAP_ID" style={{ flex: 1 }} />

googleMapId is creation-time configuration for native SDK views. Changing it remounts the native map view, matching provider changes.

MapView can configure native entering animations for markers and marker clusters:

<MapView
  style={{ flex: 1 }}
  clusteringEnabled
  markerEnteringAnimation={{ preset: 'fade-scale', duration: 180 }}
  clusterEnteringAnimation={{ preset: 'fade' }}
>
  <Marker
    coordinate={{ latitude: 52.2297, longitude: 21.0122 }}
    enteringAnimation={false}
  />
</MapView>

markerEnteringAnimation is the map-level default for all markers, including bulk markers descriptors. Marker.enteringAnimation and bulk marker enteringAnimation override that default for one marker; false is an explicit opt-out. clusterEnteringAnimation applies to marker clusters when clustering is enabled.

When no animation prop is set, the default is system: each provider keeps its native entering behavior. Explicit presets (fade, fade-scale) are the cross-provider contract. fade-scale may gracefully fall back to fade on SDK marker surfaces that do not support efficient scaling.

Explicit configs use milliseconds. duration defaults to 180, delay defaults to 0, and both values are clamped to 0..3000 before they reach the native provider. reduceMotion defaults to system, which disables explicit animations when the platform Reduced Motion setting asks for it. Use never only when the app intentionally ignores that setting for this overlay.

On Google Maps providers, marker and cluster entering animations can reduce UI-thread frame rate when a large viewport refresh adds many markers at once. The provider caps animated markers per refresh and may show the remaining markers immediately to preserve map gesture performance. For very large marker sets, prefer clustering, shorter durations, or markerEnteringAnimation={false} / clusterEnteringAnimation={false} when smooth gestures are more important than entrance motion.

bun install
bun run example start

The example app lives in example. It demonstrates provider switching, overlays, clustering, Google Map IDs, entering animation presets, and native POI tap logging.

For Google Maps in the example app, configure one shared key or platform-specific keys:

GOOGLE_MAPS_API_KEY=your_key
GOOGLE_MAPS_IOS_API_KEY=your_ios_key
GOOGLE_MAPS_ANDROID_API_KEY=your_android_key

See example/.env.example for the supported environment variables.

• Expo setup
• Architecture
• Roadmap
• Contributing
• ADRs

# Install dependencies
bun install

# Build the library
bun run build

# Run linting and type checks
bun run lint
bun run typecheck
bun run typecheck:provider-types

# Regenerate Nitro bindings after spec changes
bun run nitrogen

# Start the example app
bun run example start

See CONTRIBUTING.md for contribution guidelines.

The release surface focuses on Apple MapKit and Google Maps SDK providers. Follow-up work is tracked in docs/roadmap.md, including additional providers, expanded migration docs, and offline tile support.

MIT - see LICENSE.