React Native Clusterer

The most comprehensive and yet easiest to use react native point clustering library. Uses c++ implementation of supercluster and JSI bindings for up to 10x faster initial point loading times than its JavaScript counterpart.

Installation

``sh
npm install react-native-clusterer react-native-nitro-modules
`
> react-native-nitro-modules is required as this library relies on Nitro Modules.

Example

Check out the example folder for a fully functional example and speed comparisons. On android make sure to update AndroidManifest.xml with com.google.android.geo.API_KEY meta data in order for Google Maps to work.

Usage

This library provides three different ways to use Supercluster based on your needs:

- useClusterer: Hook for most hassle-free implementation.
- Clusterer: React Native component.
- Supercluster: Class for custom functionality.

If you are looking for a JS drag-and-drop replacement to speed up point clustering, you should be aware of some caveats:

- Missing Map/reduce functionality.

useClusterer

`js
import { useClusterer } from 'react-native-clusterer';

const MAP_DIMENSIONS = { width: MAP_WIDTH, height: MAP_HEIGHT }

//...
const [region, setRegion] = useState(initialRegion);
const [points, supercluster] = useClusterer(
markers,
MAP_DIMENSIONS,
region
);

// ...
return (
onRegionChangeComplete={setRegion}
// ... other props
>
{points.map(point => (
// These should be memoized components,
// otherwise you might see flickering
// ... marker props
>
{/*
// ... marker children - callout, custom marker, etc.
*/}

);
)}
/>

);
`

useClusterer Params

$3

Same as points>) passed to supercluster.load().

$3

Object containing width and height of the Component

$3

Region from the Component: Object containing latitude, longitude, latitudeDelta and longitudeDelta values.

$3

Same as options for Supercluster, not required.

useClusterer Returns

An array with two elements:

- points - Array of points (GeoJSON Feature point or cluster). Clusters have an additional getExpansionRegion() which will return a region that can be used to expand the cluster (use isClusterFeature>) to check if this property is defined). Same as getClusterExpansionRegion>) without the need for clusterId param.
- supercluster - Supercluster instance.

Clusterer

`js
//...
import { Clusterer } from 'react-native-clusterer';
import MapView, { Marker } from 'react-native-maps';

const MAP_DIMENSIONS = { width: MAP_WIDTH, height: MAP_HEIGHT }

// ...
const [markers, setMarkers] = useState([]);
const [region, setRegion] = useState(initialRegion);

// ...
return (
onRegionChangeComplete={setRegion}
// ... other props
>
data={markers}
region={region}
options={DEFAULT_OPTIONS}
mapDimensions={MAP_DIMENSIONS}
renderItem={(item) => {
return (
// These should be memoized components,
// otherwise you might see flickering
// ... marker props
>
{/ marker children - callout, custom marker, etc. /}
{item.properties.cluster_id ? (
// render cluster
) : (
// render marker
)}

);
}}
/>

);
`

Clusterer Props

$3

Same as points>) passed to supercluster.load().

$3

Object containing width and height of the Component

$3

Region from the Component: Object containing latitude, longitude, latitudeDelta and longitudeDelta values.

$3

Same as options for Supercluster.

$3

Function that takes an item (GeoJSON Feature point or cluster) and returns a React component.

Supercluster

`js
import Supercluster from 'react-native-clusterer';
//...

// Create a new instance of Supercluster
const supercluster = new Supercluster(options);

// Load points
supercluster.load(points);

// Get clusters
supercluster.getClustersFromRegion(region, mapDimensions);
`

Supercluster Options

| Option | Default | Description |
| ---------- | ------- | ----------------------------------------------------------------- |
| minZoom | 0 | Minimum zoom level at which clusters are generated. |
| maxZoom | 16 | Maximum zoom level at which clusters are generated. |
| minPoints | 2 | Minimum number of points to form a cluster. |
| radius | 40 | Cluster radius, in pixels. |
| extent | 512 | (Tiles) Tile extent. Radius is calculated relative to this value. |
| generateId | false | Whether to generate ids for input features in vector tiles. |

Supercluster Methods

$3

Loads an array of GeoJSON Feature objects. Each feature's geometry must be a GeoJSON Point. Once loaded, index is immutable.

#### getClusters(bbox, zoom)

For the given bbox array ([westLng, southLat, eastLng, northLat]) and integer zoom, returns an array of clusters and points as GeoJSON Feature objects.

#### getClustersFromRegion(region, mapDimensions)

For the given region from react-native-maps and an object containing width and height of the component, returns an array of clusters and points as GeoJSON Feature objects.

#### getTile(z, x, y)

For a given zoom and x/y coordinates, returns a geojson-vt-compatible JSON tile object with cluster/point features.

#### getChildren(clusterId)

Returns the children of a cluster (on the next zoom level) given its id (clusterId value from feature properties).

#### getLeaves(clusterId, limit = 10, offset = 0)

Returns all the points of a cluster (given its clusterId), with pagination support:
limit is the number of points to return, and offset is the number of points to skip (for pagination).

#### getClusterExpansionZoom(clusterId)

Returns the zoom on which the cluster expands into several children (useful for "click to zoom" feature) given the cluster's clusterId.

#### getClusterExpansionRegion(clusterId)

Returns a region containing the center of all the points in a cluster and the delta value by which it should be zoomed out to see all the points. Useful for animating a MapView after a cluster press.

#### destroy()

No longer needed (version 1.2.0 and up).

~~Since JS doesnt have destructors, we have to make sure the cluster stored in c++ memory is also deleted. This method is called automatically when using the component.~~

Utility Methods

#### isClusterFeature(point)

Typescript type guard for checking if a point is a cluster.

##### Example

`js
const _handlePointPress = (point: IFeature) => {
if (isClusterFeature(point)) {
const toRegion = point.properties.getExpansionRegion();
mapRef.current?.animateToRegion(toRegion, 500);
}
};

// ... other props
renderItem={(item) => {
return ;
}}
/>;
`

#### coordsToGeoJSONFeature(coords, properties)

Converts coordinates to a GeoJSON Feature object. Accepted formats are [longitude, latitude] or {longitude, latitude} or {lng, lat}. Properties can be anything and are optional.

Troubleshooting

- If you can't see any points on the map, make sure you provided coordinates in the correct __order__ and format. The library expects [longitude, latitude] for each point.

TO-DOs

- [x] Proper input and return types for methods
- [x] Implement getClusters(bbox, zoom)
- [x] Parse and return additional Point properties added by users
- [x] Find a better implementation for destroy()`.
- [ ] Map/reduce options

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

Copyright (c) 2021 Jiri Hoffmann

Uses supercluster for point clustering. Check out mapbox/supercluster.hpp for additional licensing.