react-native-map-supercluster

A lightweight, dependency-minimized library for clustering markers on react-native-maps. Built as a modern alternative and continuation of the now unmaintained react-native-map-clustering.


---

Features

- Smooth marker clustering and rendering
- Minimal setup, no native linking required
- Fully compatible with react-native-maps
- Support for color ranges and customization
- Native performance via supercluster with no external geo dependencies

---

Installation

``bash
npm install react-native-map-supercluster
`

or with yarn:

`bash
yarn add react-native-map-supercluster
`

You also need react-native-maps installed and configured in your project.

---

Usage

`tsx
import React, { useState } from "react";
import { StyleSheet, View } from "react-native";
import { Marker } from "react-native-maps";
import ClusteredMapView from "react-native-map-supercluster";

const markers = [
,
,
,
];

export default function App() {
return (

initialRegion={{
latitude: -19.92,
longitude: -43.94,
latitudeDelta: 0.1,
longitudeDelta: 0.1,
}}
style={StyleSheet.absoluteFillObject}
>
{markers}


);
}
`

---

Props

| Prop | Type | Default | Description |
| ------------------------------ | ------------------------------ | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| clusteringEnabled | boolean | true | Enable or disable clustering. |
| spiralEnabled | boolean | true | Enable spiderfy behavior when overlapping markers. |
| animationEnabled | boolean | true | Enable layout animation when clusters update. |
| preserveClusterPressBehavior | boolean | false | If true, clusters will not zoom in on press unless explicitly handled. |
| layoutAnimationConf | LayoutAnimationConfig | — | Custom layout animation config. |
| tracksViewChanges | boolean | false | Set on Marker components for performance. |
| useAndroidColorScale | boolean | false | ⚠️ Important for Android: If your custom cluster components (e.g. SVG, View) are being clipped or cut off, set this to true. This disables custom cluster rendering and instead uses the default static image cluster. |
| radius | number | 50 | Cluster radius. |
| maxZoom | number | 20 | Maximum zoom level to cluster. |
| minZoom | number | 1 | Minimum zoom level to cluster. |
| minPoints | number | 2 | Minimum number of points to form a cluster. |
| extent | number | 512 | Tile extent (usually remains at 512). |
| nodeSize | number | 64 | Node size for supercluster. |
| edgePadding | object | { top: 50, left: 50, right: 50, bottom: 50 } | Padding used when fitting to cluster bounds. |
| clusterColor | string | #00B386 | Default background color of clusters. |
| clusterTextColor | string | #FFFFFF | Default text color inside cluster. |
| clusterFontFamily | string | — | Font family to apply to cluster text. |
| spiderLineColor | string | #FF0000 | Color of spiderfy lines when a cluster is expanded. |
| selectedClusterId | string | — | Highlight a specific cluster. |
| selectedClusterColor | string | — | Color to use for the selected cluster. |
| superClusterRef | React.MutableRefObject | { current: null } | Get direct access to the SuperCluster instance. |
| mapRef | React.Ref

---

Expo Support

🚨 Warning: Due to current architectural limitations in Expo Go, dynamic cluster rendering may result in crashes or unresponsiveness. We recommend using React Native CLI for production apps. A future update may introduce Expo compatibility.

Credits

This package is based on react-native-map-clustering by @tomekvenits. Since that library is no longer maintained, we adapted its original codebase — fixing compatibility issues (especially with the new React Native architecture), resolving Android-specific bugs, and introducing a few enhancements to improve flexibility and ease of use.

---

License

MIT © 2025 [Luís-Reis]