- import MapView from 'react-native-map-clustering'
+ import MapView from 'react-native-better-clustering'
  import { Marker } from 'react-native-maps'

That is it. Your <Marker> children, cluster props, and react-native-maps options keep working — clustering just moves off the JS thread.

• iOS
• Android
• Web

npm install react-native-better-clustering react-native-nitro-modules react-native-maps react-native-reanimated react-native-worklets
cd ios && pod install && cd ..

Rebuild the native app after installing. Add the Worklets Babel plugin (last in the list) to babel.config.js:

plugins: ['react-native-worklets/plugin']

npx expo install react-native-better-clustering react-native-nitro-modules react-native-maps react-native-reanimated react-native-worklets

babel-preset-expo wires up the Worklets plugin automatically.

Add the react-native-maps plugin to app.json:

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

npx expo prebuild --clean
npx expo run:ios   # or: npx expo run:android

import MapView from 'react-native-better-clustering'
import { Marker } from 'react-native-maps'

export function MapScreen() {
  return (
    <MapView
      style={{ flex: 1 }}
      initialRegion={{
        latitude: 52.23,
        longitude: 21.01,
        latitudeDelta: 0.35,
        longitudeDelta: 0.35,
      }}
      radius={56}
      minPoints={2}
      clusterColor="#FFCC00"
      clusterTextColor="#000000"
      spiralEnabled
      animationEnabled
      onClusterPress={(cluster, markers) => {
        console.log(cluster.properties.point_count, markers.length)
      }}
    >
      {points.map((point) => (
        <Marker
          key={point.id}
          coordinate={{
            latitude: point.latitude,
            longitude: point.longitude,
          }}
        />
      ))}

      {/* Keep a marker outside clusters */}
      <Marker
        cluster={false}
        coordinate={{ latitude: 52.23, longitude: 21.01 }}
      />
    </MapView>
  )
}

Pass renderCluster when you need full control over the cluster bubble:

import MapView, {
  type RenderClusterProps,
} from 'react-native-better-clustering'
import { Marker } from 'react-native-maps'

const renderCluster = (cluster: RenderClusterProps) => {
  const [longitude, latitude] = cluster.geometry.coordinates
  return (
    <Marker coordinate={{ latitude, longitude }} onPress={cluster.onPress}>
      {/* your cluster bubble */}
    </Marker>
  )
}

<MapView renderCluster={renderCluster} {...props}>
  {/* markers */}
</MapView>

Everything from react-native-maps MapView, plus:

Per-marker opt-out: <Marker cluster={false} ... />.

Today this library solves clustering compute — the C++ engine indexes 10k+ points and returns viewport clusters off the JS thread. Visible markers are still rendered through react-native-maps <Marker> components, which becomes the UI-thread bottleneck when hundreds of annotations are on screen at once.

The long-term goal is to remove that ceiling entirely.

Improvements within the current drop-in API: image-based cluster bubbles with caching, stable marker pooling, and smarter defaults. Expected to roughly 3–5× improve FPS at mid zoom levels, but still bounded by per-annotation overhead from react-native-maps.

A native clustered map view that draws annotations in a single native pass instead of mounting one React <Marker> per cluster or point. The existing C++ ClusterEngine feeds packed point data directly into native bubble rendering — same public MapView + <Marker> API, no N-marker mount storm on zoom.

Tier 2 is the reason this library exists beyond a faster supercluster port: render as many markers as you need without FPS collapse. The compat API stays unchanged; rendering moves under the hood.

Track progress in GitHub Issues.

A minimal full-screen map with ~2,000 randomly scattered markers across Poland — default green cluster bubbles and standard map pins, modeled on the react-native-map-clustering demo.

cd example
bun install
npx expo prebuild --clean
bun run ios   # or: bun run android

Low-level hooks and headless access live under subpath exports for custom map stacks:

See the docs for details. The /compat subpath is an alias of the main export.

More in troubleshooting.

See CONTRIBUTING.md.

bun install
cd package && bun run typecheck && bun run lint && bun run test

MIT — see LICENSE.