react-native-maps-fleets

A production-ready fleet map wrapper around react-native-maps with native clustering and patch-based updates.

Install

yarn add react-native-maps-fleets react-native-maps

cd ios && pod install

Google Maps API key

Android (required): add a Google Maps API key to your AndroidManifest.xml:

<meta-data
  android:name="com.google.android.geo.API_KEY"
  android:value="YOUR_API_KEY" />

Expo config plugin (optional):

// app.json or app.config.js
{
  "expo": {
    "plugins": [
      [
        "react-native-maps-fleets/plugin/withFleetMaps",
        {
          "androidApiKey": "YOUR_API_KEY",
          "iosApiKey": "YOUR_IOS_KEY",
          "streetViewApiKey": "YOUR_STREET_VIEW_KEY"
        }
      ]
    ]
  }
}

iOS: add GMSApiKey to Info.plist for Google Maps on iOS.

Usage

import React from 'react';
import {FleetMapView, Cluster, NormalMarker, AdvancedMarker} from 'react-native-maps-fleets';

const features = [
  {
    id: 'truck-1',
    coordinate: {latitude: 37.78, longitude: -122.41},
    type: 'vehicle',
    clusterId: 'main',
    heading: 120,
    zIndex: 10,
  },
];

export default function FleetScreen() {
  return (
    <FleetMapView
      style={{flex: 1}}
      initialRegion={{
        latitude: 37.78,
        longitude: -122.41,
        latitudeDelta: 0.1,
        longitudeDelta: 0.1,
      }}
      features={features}
      selectedId={null}
      onSelect={id => console.log('select', id)}
      clusterIdDefault="main">
      <Cluster id="main">
        <NormalMarker type="vehicle" icon="car" rotatable zIndex={10} />
        <NormalMarker type="arrow" icon="arrow" rotatable zIndex={20} />
        <NormalMarker type="avatar" size={64} zIndex={30} />
      </Cluster>

      <Cluster id="secondary">
        <NormalMarker type="poi" icon="pin" zIndex={5} />
      </Cluster>

      <AdvancedMarker coordinate={{latitude: 37.78, longitude: -122.41}}>
        <SelectedVehicle />
      </AdvancedMarker>
    </FleetMapView>
  );
}

Performance Mode

Performance Mode is a set of optimizations for fleet-scale maps (200–1000+ moving devices), ensuring smooth movement and reduced CPU/GPU usage.

Why we never use iconView for mass markers

When rendering hundreds of markers, using iconView (UIView-based markers) leads to severe performance degradation and visual artifacts:

• GPU Texture Pressure: Each iconView requires a snapshot that is stored as a GPU texture. 300+ live views can exceed GPU memory or cause texture thrashing.
• Snapshot Corruption: Rapid movement or zoom changes during view snapshotting can cause "stretched" or falsified visuals (e.g., random red blocks).
• Main Thread Blockage: React Native and the Map SDK must manage the lifecycle of hundreds of UIViews on the main thread.

Solution: In Performance Mode, we use pre-rendered marker.icon bitmaps. These are generated once, cached in an LRU cache, and reused across all markers with the same visual state.

Advanced Optimizations

• Size Buckets: To maximize cache hits, marker sizes are quantized into a few "buckets" (e.g., small, medium, large).
• Off-Main Processing: Image decoding, resizing, and marker composition (drawing borders, pins, etc.) happen on background threads. Only the final assignment to the marker happens on the main thread.
• In-Flight Deduplication: If multiple markers request the same avatar URL simultaneously, only one download/process task is started.
• Stable Z-Index: Marker layering is updated only when necessary (creation or selection change), eliminating per-tick overhead.
• Out-of-Viewport Cadence: Markers outside the viewport remain visible but update their positions much less frequently (e.g., every 2.5s) to save CPU.

Features

• Hot Path (Positions): Throttled and interpolated native updates.
• Cold Path (Visuals): Efficient batch updates for selection and icon changes.
• Authoritative Native Registry: Ensures 1 ID maps to exactly 1 native marker.
• Viewport Virtualization: Skips processing for markers outside the camera view + buffer.
• Zoom-driven Aggressive Clustering: Automatically hides/clusters markers at low zoom levels.
• Cap Visible Singles: Limits the number of single markers in the viewport to prioritize performance.
• Performance Cluster: Native clustering for high-density marker sets (200–1000+), automatically grouping background markers while keeping the selected marker as a distinct, single entity.

How to Enable

You can enable it via props or by calling the imperative method:

<FleetMapView
  performanceModeEnabled={true}
  performanceConfig={{
    performanceCluster: true,
    performanceClusterConfig: {
      clusterZoomThreshold: 12,
      clusterDensityThreshold: 250,
    },
    // ...
  }}
/>

Or imperatively:

mapRef.current.setPerformanceMode(true, { performanceCluster: true });

Performance Cluster Behavior

When performanceCluster is active:

1. Zoom Threshold: Markers are clustered when the zoom level is below clusterZoomThreshold.
2. Density Threshold: If the number of visible markers exceeds clusterDensityThreshold, clustering activates even if zoom is high.
3. Selected Marker Exclusion: The currently selected marker is NEVER clustered. It remains a single, high-fidelity marker (arrow/avatar) regardless of zoom or density.
4. Hysteresis & Throttling: Clustering updates are throttled (default 350ms) to avoid CPU spikes during movement).

Configuration Options

Option	Default	Description
performanceCluster	false	Enable/disable native performance clustering.
clusterZoomThreshold	12	Zoom level below which background markers are clustered.
clusterDensityThreshold	250	Number of markers above which clustering is forced.
clusterUpdateThrottleMs	350	Throttling interval for native clustering logic.
alwaysShowSelected	true	If true, selected marker is always excluded from clusters.

Troubleshooting

• Ghost Markers: Ensure you are using unique IDs. Performance mode enforces a strict 1-to-1 registry.
• Arrows not moving: Ensure the marker type is set correctly and heading is provided in the position update.

Performance tips

• Prefer features + patchPositions updates (patches are computed automatically in JS).
• Use selectedId to promote one feature out of the clustered set.
• Keep marker types stable and reuse marker icons.
• Avoid re-creating the features array when not needed.

Native Architecture

Both platforms implement a full-featured FleetMarkerEngine with identical subsystems:

Component	Purpose
FleetMarkerEngine	Main engine coordinating all subsystems
MarkerStore	Thread-safe O(1) marker state storage
MarkerPool	Object pooling for zero-alloc scrolling
VisibilityIndex	3-zone viewport culling with hysteresis
ClusterGrid	O(N) spatial-hash clustering
MarkerRegistry	1-to-1 ID-to-native-marker mapping
SelectionController	Selection state management
UpdateScheduler	Budget-limited tick execution
IconCache	LRU icon cache (Android: LruCache, iOS: NSCache)

• Android: Kotlin, Google Maps SDK, Handler-based animation
• iOS: Swift, Google Maps SDK, CADisplayLink 60fps animation, GCD background processing

See API.md for the full API reference.

Limitations

• Advanced markers are rendered in React; avoid heavy layouts.

Roadmap

• Custom cluster styling hooks.
• Optional map state persistence.

License

MIT. Includes copyright from Airbnb and Nicola Tomassini.