Skip to content

About

Better (Faster) way to cluster points on react-native-maps

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

105 stars

Watchers

1 watching

Forks

Repository files navigation

react-native-better-clustering

Your react-native-maps screen freezes with thousands of markers? Change one import.

A drop-in replacement for react-native-map-clustering. Same API, same react-native-maps workflow, but the cluster index is built in C++ via Nitro on a background thread, not in JavaScript on the JS thread.

npm version npm downloads GitHub stars New Architecture License: MIT CI

Benchmark • Migration • Installation • Usage • Documentation • Example app

Four side-by-side scenes, react-native-better-clustering 1.1 against react-native-map-clustering 4.0. Opening 100,000 markers: 0.6 s against 5.1 s. Pan and zoom with the places in view in state: up to date as the fingers lift against 5.7 s later. Filtering 100,000 places: the map updates 0.2 s after the tap against 3.5 s. 500 vehicles moving every second among 50,000 markers: each update on the map in 0.2 to 0.4 s against a 2.4 s wait
The published 1.1.0 and react-native-map-clustering 4.0.0 in the same app, with the same input: opening 100,000 markers, pan and zoom on a screen that keeps the places in view in its state, a category filter, and a live fleet. iOS Simulator; each scene says its playback speed, and the times shown are real seconds.

Benchmark

The same app, the same markers, the same cluster bubble, both libraries with their default props. Medians of 5 runs of a Release build (Hermes), from the device benchmark:

Markers First markers on the map Longest JS freeze while mounting JS blocked over 10 parent re-renders
10,000 react-native-map-clustering 4.0.0 359 ms 360 ms 2,877 ms
react-native-better-clustering 193 ms 27 ms 0 ms
50,000 react-native-map-clustering 4.0.0 1,834 ms 1,835 ms 17,794 ms
react-native-better-clustering 232 ms 92 ms 464 ms
100,000 react-native-map-clustering 4.0.0 3,557 ms 3,558 ms 35,899 ms
react-native-better-clustering 434 ms 170 ms 1,719 ms
  • Mount. react-native-map-clustering builds its index on the JS thread, so no touch, timer or state update runs until the first markers appear. Here the build runs on a background thread.
  • Re-renders. With the same markers as new inline children, react-native-map-clustering rebuilds its index on every render. This library keeps the index and every mounted marker.
  • Zoom. react-native-map-clustering queries four times the screen's area; at zoom 8 it renders about 3–4× as many markers and bubbles, most of them off screen.

Measured on the iOS Simulator (iPhone 17 Pro, Apple M5 Pro) against the 1.1.0 release candidate, which runs faster than a phone: compare the libraries, not the absolute times. The full results include memory, zoom and cluster presses. They also show where this library is slower: after a cluster press, the camera settles about 0.45 s later.

Coming from react-native-clusterer or use-supercluster? At 100,000 points, useClusterer blocks the JS thread for 11 ms per index build, against 234 ms for react-native-clusterer 5.0.2 and 2.3 s for use-supercluster 1.2.0, and builds no index on a pan, where both rebuild theirs (hook benchmark; migrating from react-native-clusterer and use-supercluster).

Migration

- 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 carry over. A few defaults and behaviours differ, such as the default cluster color and how style is applied: see Migrating from react-native-map-clustering, and Coming from 3.x.

Fixes over react-native-map-clustering

Issue Status
Crash on NaN zoom (#294) Guarded with finite zoom fallback
Map size can't be 0 on Android (#285) Layout-aware fitToCoordinates
maxZoom / spiralEnabled ignored (#274, #275) Implemented
Unstable clusters on zoom (#255) Stable cluster references between renders
Per-marker cluster={false} (#297) Supported

Caution

Bugs in react-native-maps itself (ghost markers on Android, navigation crashes) may still occur. This library replaces clustering, not the map renderer.

Installation

iOS and Android, React Native 0.78+ with the New Architecture, react-native-maps 1.20.1+ and react-native-nitro-modules 0.32.0+. Expo needs a development build; Expo Go does not work. Reanimated 4.1+ is optional: with it, cluster bubbles fade and glide on zoom.

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

Rebuild the native app after installing. With Expo, install with npx expo install instead, set your Google Maps key for Android (without it, Android apps crash when a map mounts), then npx expo prebuild --clean and build. On Expo SDK 55 and later, set it with the react-native-maps config plugin's androidGoogleMapsApiKey; SDK 53 and 54 install react-native-maps 1.20.1, which has no config plugin, so set expo.android.config.googleMaps.apiKey instead. See Expo setup.

Usage

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,
      }}
      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 }}
        />
      ))}
    </MapView>
  )
}

Give each Marker a stable key, not the array index. <Marker cluster={false} /> keeps a marker out of clusters.

Documentation

Props Every MapView prop, custom cluster bubbles with renderCluster, accessibility
Installation Platform setup, Google Maps keys, animated bubbles with Reanimated
Migration Every difference from react-native-map-clustering, and coming from 3.x
Advanced APIs useClusterer, Clusterer and the headless engine, for your own map stack
Performance What runs on which thread, the benchmarks and the roadmap
Troubleshooting Blank maps, Expo Go, New Architecture errors, flickering markers
Example app Scenarios from 2,000 to 50,000 markers, and the device benchmark

Contributing

See CONTRIBUTING.md for the setup, checks and docs workflow. Releases are published from CI, see RELEASING.md. Report vulnerabilities privately, see SECURITY.md.

License

MIT, see LICENSE.


Built and maintained by GMI Software. If it saves your map screen, a ⭐ helps other React Native developers find it.

About

Better (Faster) way to cluster points on react-native-maps

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

105 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages