Skip to content

API.md

Latest commit

 

History

History
269 lines (214 loc) · 8.71 KB

API.md

File metadata and controls

269 lines (214 loc) · 8.71 KB

API Reference — react-native-maps-fleets

Components

<FleetMapView>

Main map component wrapping react-native-maps with fleet-optimized clustering.

import { FleetMapView } from 'react-native-maps-fleets';

Props

Extends all MapViewProps from react-native-maps, plus:

Prop Type Default Description
features FleetFeature[] required Array of fleet features to display
selectedId string | null null ID of the currently selected feature
onSelect (id: string | null) => void — Called when a feature is selected/deselected
onClusterPress (clusterId, count, markerIds) => void — Called when a cluster is tapped
onCameraChange (camera: FleetMapCamera) => void — Called on camera position changes
followId string | null — ID of feature to follow with camera
followMode boolean false Enable camera follow mode
followSmoothingMs number — Smoothing duration for follow camera
followZoom number — Zoom level for follow mode
paddingRegion { top?, bottom?, left?, right? } — Map padding
onFollowModeChange (enabled, reason?) => void — Called when follow mode changes
clusterIdDefault string | null — Default cluster ID for features without one
performanceModeEnabled boolean false Enable performance mode optimizations
performanceConfig PerformanceConfig — Performance mode configuration
performanceCluster boolean false Enable native performance clustering
performanceClusterConfig PerformanceClusterConfig — Cluster configuration
hybridOverlayConfig HybridOverlayConfig — Hybrid overlay tooltip configuration
mapTheme 'DARK' | 'LIGHT' | 'FOLLOW_SYSTEM' 'DARK' Map color scheme
showLabels boolean — Show name labels under markers
featuresKey string | number — Change to force full feature refresh
markersHidden boolean false Hide all markers

Imperative Handle (ref)

const mapRef = useRef<FleetMapViewHandle>(null);
<FleetMapView ref={mapRef} ... />
Method Signature Description
setFeatures (features: FleetFeature[]) => void Set features directly (bypasses diff)
patchPositions (patches: FleetPatch[]) => void Apply incremental position patches
setSelected (id: string | null) => void Set selected marker
getCamera () => Promise<FleetMapCamera> Get current camera state
animateCamera (camera, options?) => void Animate camera to position
animateToRegion (region, duration?) => void Animate to a region
setCamera (camera) => void Set camera instantly
moveCamera (camera) => void Move camera
pointForCoordinate (coord) => Promise<{x, y}> Convert geo to screen point
resumeFollow () => void Resume follow mode
updatePositionsBatch (updates: PositionUpdate[]) => void Batch position updates (perf mode)
updateMarkerVisualsBatch (updates: VisualUpdate[]) => void Batch visual updates (perf mode)
setPerformanceMode (enabled, config?) => void Toggle performance mode
setPerformanceCluster (enabled, config?) => void Toggle native clustering
showTooltip (coordinate, content) => void Show hybrid overlay tooltip
hideTooltip () => void Hide tooltip
setPolyline (id, points, options?) => void Add/update polyline
removePolyline (id) => void Remove polyline
removeAllPolylines () => void Remove all polylines
setShowLabels (show) => void Toggle name labels
setMapTheme (theme) => void Set map color scheme

<Cluster>

Declarative cluster container. Groups NormalMarker definitions.

import { Cluster } from 'react-native-maps-fleets';
Prop Type Description
id string required — Cluster identifier
children ReactNode NormalMarker definitions

<NormalMarker>

Declares a marker type template within a cluster or globally.

import { NormalMarker } from 'react-native-maps-fleets';
Prop Type Default Description
type string required Marker type (e.g., 'arrow', 'vehicle', 'avatar')
icon string | ImageSource — Icon asset or URI
size number — Marker size in dp
rotatable boolean false (arrow: true) Whether marker rotates with heading
zIndex number — Z-index layer
anchor { x: number; y: number } — Anchor point (arrow defaults to {0.5, 0.5})
labelMinZoom number — Min zoom to show label
labelMaxLength number — Max label character length

<AdvancedMarker>

Custom React view marker for selected/special markers.

import { AdvancedMarker } from 'react-native-maps-fleets';
Prop Type Description
id string Marker ID
coordinate FleetCoordinate required — Position
clusterId string Cluster to belong to
anchor { x, y } Anchor point
zIndex number Z-index
tracksViewChanges boolean Re-render native snapshot on change
children ReactNode Custom marker view

Hooks

useFleetMapConfig

Returns configuration defaults for the fleet map.

import { useFleetMapConfig } from 'react-native-maps-fleets';
const config = useFleetMapConfig();

useSmartPolyline

Manages polyline points with smart decimation.

import { useSmartPolyline } from 'react-native-maps-fleets';
const { points, addPoint, clear } = useSmartPolyline(options);

useFleetAreaEditor

Area editor controller for polygon/circle geofence editing.

import { useFleetAreaEditor } from 'react-native-maps-fleets';
const controller = useFleetAreaEditor(options);

Types

FleetFeature

type FleetFeature = {
  id: string;
  coordinate: { latitude: number; longitude: number };
  type: string;               // 'arrow' | 'vehicle' | 'avatar' | custom
  clusterId?: string | null;
  heading?: number;
  zIndex?: number;
  status?: string;
  size?: MarkerSizeConfig;
  avatarUrl?: string | number;
  avatarVersion?: number;
  icon?: string | number;
  label?: string;
  color?: string;
  arrowColor?: string;
  data?: Record<string, unknown>;
};

FleetPatch

type FleetPatch = {
  id: string;
  latitude?: number;
  longitude?: number;
  heading?: number;
  zIndex?: number;
  status?: string;
  arrowColor?: string | null;
};

PerformanceConfig

type PerformanceConfig = {
  throttleMs?: number;
  interpolationEnabled?: boolean;
  interpolateSelectedOnly?: boolean;
  viewportVirtualizationEnabled?: boolean;
  viewportBufferMeters?: number;
  freezeUnselectedEnabled?: boolean;
  freezeIntervalMs?: number;
  clusterZoomThreshold?: number;
  capSinglesEnabled?: boolean;
  maxSinglesInViewport?: number;
  alwaysShowSelected?: boolean;
  performanceCluster?: boolean;
  performanceClusterConfig?: PerformanceClusterConfig;
};

PerformanceClusterConfig

type PerformanceClusterConfig = {
  declusterZoomThreshold?: number;  // Default: 18
  minClusterSize?: number;          // Default: 2
  cellSizeMultiplier?: number;      // Default: 1.0
  maxVisibleIndividualMarkers?: number; // Default: 50
  alwaysShowSelected?: boolean;     // Default: true
};

FleetMapCamera

type FleetMapCamera = {
  center: { latitude: number; longitude: number };
  heading?: number;
  pitch?: number;
  zoom?: number;
  altitude?: number;
};

Native Engines

Both platforms implement a full-featured FleetMarkerEngine:

Architecture (Android: Kotlin, iOS: Swift)

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

Performance Characteristics

  • Markers: Tested with 300–1000+ simultaneous moving markers
  • Frame rate: Budget-limited to maintain 60fps
  • Memory: LRU caches prevent unbounded growth
  • Clustering: O(N) grid-based, incremental position updates
  • Animation: Selected marker lerp @ 60fps (CADisplayLink on iOS, Handler on Android)