Skip to content
Skills Library
Programming · Building & coding

react-native-better-maps

/react-native-better-maps

Expert guide to react-native-better-maps — native maps for React Native built on Nitro Modules, with Apple MapKit and Google Maps provider adapters, descriptor-based overlays, and native marker clustering. Use when installing or configuring the map, rendering markers or overlays, driving the camera, diagnosing lag or marker re-render churn, working around a provider or platform difference, migrating from react-native-maps, or changing the library's TypeScript, Swift, Kotlin, or Nitro specs.

Licence
MIT
Last repository change
14.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
12
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Expert guide to react-native-better-maps — native maps for React Native built on Nitro Modules, with Apple MapKit and Google Maps provider adapters, descriptor-based overlays, and native marker clustering. Use when installing or configuring the map, rendering markers or overlays, driving the camera, diagnosing lag or marker re-render churn, working around a provider or platform difference, migrating from react-native-maps, or changing the library's TypeScript, Swift, Kotlin, or Nitro specs.

Original author description

Expert guide to react-native-better-maps — native maps for React Native built on Nitro Modules, with Apple MapKit and Google Maps provider adapters, descriptor-based overlays, and native marker clustering. Use when installing or configuring the map, rendering markers or overlays, driving the camera, diagnosing lag or marker re-render churn, working around a provider or platform difference, migrating from react-native-maps, or changing the library's TypeScript, Swift, Kotlin, or Nitro specs.

How it works

  1. Version verification
  2. When to use
  3. When NOT to use
  4. Core architecture
  5. API guidance
  6. Problem → reference routing
  7. Canonical performance workflow
  8. Common mistakes
  9. Troubleshooting
  10. Known limitations (high signal)
Original SKILL.md headings · 125 lines, 777 words
SKILL.md preview
---
name: react-native-better-maps
description: >-
  Expert guide to react-native-better-maps — native maps for React Native built on Nitro
  Modules, with Apple MapKit and Google Maps provider adapters, descriptor-based overlays,
  and native marker clustering. Use when installing or configuring the map, rendering
  markers or overlays, driving the camera, diagnosing lag or marker re-render churn,
  working around a provider or platform difference, migrating from react-native-maps, or
  changing the library's TypeScript, Swift, Kotlin, or Nitro specs.
license: MIT
metadata:
  package: react-native-better-maps
  version: "1.1.0"
  commit: b9a178334913043b3aa2542fb528731debaad4f5
  verified: "2026-08-21"
  repository: https://github.com/gmi-software/react-native-better-maps
  audience: library users and library contributors
  tags: react-native, maps, mapkit, google-maps, nitro, jsi, markers, clustering, expo, ios, android
---

# react-native-better-maps

Native map view for React Native's New Architecture. One Nitro HybridView (`MapView`) backed by
Apple MapKit or Google Maps. Overlays are serialisable descriptors (not child views). Clustering
is implemented in Swift/Kotlin — not JavaScript, not shared C++, and not shared with
`react-native-better-clustering` (load that skill only when clustering on `react-native-maps`).

Paths like `package/src/...` are relative to a **library checkout**, not this skills repo.

## Version verification

```text
Package:            react-native-better-maps
Version:            1.1.0
Commit:             b9a178334913043b3aa2542fb528731debaad4f5
Verification date:  2026-08-21
```

```bash
npm view react-native-better-maps version
node -p "require('react-native-better-maps/package.json').version"
```

## When to use

- Installing / configuring the map (Google keys, Expo config plugin)
- Markers, polylines, polygons, circles, camera control
- Jank, flicker, markers disappearing at some zooms
- iOS vs Android or Apple vs Google behaviour differences
- Migrating from `react-native-maps`
- Changing TypeScript, Swift, Kotlin, Nitro specs, or the config plugin

## When NOT to use

| Situation | Instead |
| --- | --- |
| Using or debugging `react-native-maps` itself (not migrating) | Load the `react-native-maps` skill |
| Clustering on top of `react-native-maps` | Load the `react-native-better-clustering` skill |
| Mapbox / OSM tiles | Names exist in `MapProvider` but **throw at runtime** |
| Arbitrary React views as marker content | Unsupported on every provider |
| Web / Old Architecture / Expo Go | Native New Arch + development build only |
| Directions / geocoding / places | Outside this library |

## Core architecture

1. **One HybridView.** Everything is a prop or imperative method on `MapView`.
2. **Overlays are descriptors.** `<Marker>` renders `null`; props become `MarkerDescriptor`s.
   Bulk `markers` bypasses child collection — preferred for large sets.
3. **Adapters own SDKs.** `MapProviderAdapter` owns MapKit or Google Maps.
4. **Provider changes remount.** Key is `` `${provider}:${googleMapId ?? ''}` `` — camera and
   overlays must be re-supplied.
5. **Large sets take a background path.** Clustering on, or >500 descriptors → spatial index on
   a background queue; smaller unclustered sets apply synchronously.
6. **No shared native package.** Native changes require **both** Swift and Kotlin (or an explicit
   provider/platform carve-out).

## API guidance

```ts
import {
  MapView, Marker, Polyline, Polygon, Circle,
  regionFromCoordinate, distanceBetween,
} from 'react-native-better-maps';
```

That is the entire runtime surface (plus types). Full detail: [api.md](references/api.md).

## Problem → reference routing

| Problem | Start here |
| --- | --- |
| **Installation / blank map / Expo** | [setup.md](references/setup.md) |
| Google Maps blank/crash on iOS | setup → [ios.md](references/ios.md) |
| Markers, overlays, camera | [api.md](references/api.md) |
| Lag while panning/zooming | [performance.md](references/performance.md) |
| Marker re-render / flicker | [rendering.md](references/rendering.md) |
| Clustering / markers vanish when zoomed out | [clustering.md](references/clustering.md) |
| Provider / platform asymmetry | [ios.md](references/ios.md), [android.md](references/android.md) |
| Camera fights controlled `region` | [debugging.md](references/debugging.md) |
| **Migration from react-native-maps** | [migration.md](references/migration.md) |
| `animateCamera` hangs | debugging — **duration is seconds, not ms** |
| Architecture / contributing | [architecture.md](references/architecture.md), [contributing.md](references/contributing.md) |

## Canonical performance workflow

1. Baseline (release, real device, recorded number)
2. Define workload (count, provider, gesture)
3. Profile (Instruments / Android Studio Profiler)
4. Identify layer (JS / React / JSI conversion / native SDK)
5. Hypothesis → smallest change → re-measure → compare → regression note

Most "slow map" reports are layer 1: camera event → parent re-render → new `markers` array →
full descriptor re-cross. Region callbacks fire **once per gesture**, not per frame.

## Common mistakes

- Passing `duration: 300` to `animateCamera` (five-minute animation — unit is **seconds**)
- Expecting custom React marker views
- Using `openstreetmap` / `mapbox` provider values (they throw)
- Assuming Google-iOS honours `image` / `anchor` / `opacity` (it forces stock pins)
- Blaming clustering first when the parent rebuilds descriptors every camera event
- Measuring FPS on emulator / debug builds

## Troubleshooting

1. Blank/grey map → keys + Expo plugin + New Arch ([setup.md](references/setup.md))
2. Slow → name the layer ([performance.md](references/performance.md))
3. Flicker → stabilize `markers` / descriptor identity ([rendering.md](references/rendering.md))
4. Crash / odd prop → [debugging.md](references/debugging.md)

## Known limitations (high signal)

| Limitation | Consequence |
| --- | --- |
| `openstreetmap` / `mapbox` unimplemented | Throw during render |
| Google-iOS ignores marker visuals | Stock pins only; no warning |
| `animateCamera` duration in seconds | Default 0.25 s |
| Android `fitToCoordinates` / `region` apply collapse padding to max edge | Asymmetric fit padding does not port; `mapPadding` is per-edge |
| Unclustered LOD drops markers when zoomed out | By design, not a bug |
| No Expo Go | Development build required |
| No benchmark harness in repo | Measure yourself |

Full list and evidence rules: see references; do not invent thresholds.
Files in this package (12)
  • SKILL.md 6 KB
  • references/android.md 11 KB
  • references/api.md 14 KB
  • references/architecture.md 12 KB
  • references/clustering.md 11 KB
  • references/contributing.md 15 KB
  • references/debugging.md 12 KB
  • references/ios.md 10 KB
  • references/migration.md 12 KB
  • references/performance.md 17 KB
  • references/rendering.md 9 KB
  • references/setup.md 10 KB

Versions

The database has no other skills named react-native-better-maps.

Database snapshot: 13.11.2026 · package version 740c97ed16e1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100react-native-maps
    Expert guide to react-native-maps — MapView for iOS and Android backed by MapKit and Google Maps through React Native native components (not Nitro). Use when working with MapView, Marker, Callout, Polygon, Polyline, Circle, Overlay, Heatmap, Geojson, camera, or region from the…
  • 100react-native-better-clustering
    Expert guide to react-native-better-clustering — a drop-in clustered MapView for react-native-maps backed by a C++ supercluster engine over Nitro/JSI. Use when installing, configuring, or debugging it; when clustering is slow, wrong, or flickering; when handling thousands of map…
  • 100create-react-native-library
    Scaffolds React Native libraries with create-react-native-library for standalone libraries or local native modules and views. Use when creating or working on React Native libraries or adding native functionality in an existing app.
  • 100react-native-testing
    Test React Native components with Jest and React Native Testing Library. Use when writing Jest or React Native Testing Library tests for React Native components.
  • 100react-native
    React Native renderer for json-render that turns JSON specs into native mobile UIs. Use when working with @json-render/react-native, building React Native UIs from JSON, creating mobile component catalogs, or rendering AI-generated specs on mobile.
  • 95react-native-native-modules
    Use when building or integrating native modules in React Native. Covers creating native modules, Turbo Modules, bridging native code, and accessing platform-specific APIs.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.