MapView

Usage

import { MapView } from '@lugg/maps';

<MapView
  style={{ flex: 1 }}
  provider="google"
  initialCoordinate={{ latitude: 37.7749, longitude: -122.4194 }}
  initialZoom={12}
  onCameraMove={(e) => console.log(e.nativeEvent)}
  onCameraIdle={(e) => console.log(e.nativeEvent)}
>
  {/* Markers, Polylines, etc. */}
</MapView>

Props

Static Maps

Set staticMode to render a non-interactive map optimized for list views, where mounting many live maps is expensive:

• Android (Google) - uses lite mode, which renders a static bitmap instead of a live GL surface. Lite mode does not support cloud-based styling, so mapId is ignored on lite static maps. Lite mode caps its bitmap at ~2048px per dimension, so larger views (e.g. full-screen maps) fall back to a full map with all gestures disabled.
• iOS (Apple) - MKMapSnapshotter renders the base map off the main thread, so static maps keep loading while scrolling. With nonzero edgeInsets, a temporary MKMapView renders the image to keep Apple Maps attribution inside the inset viewport. The map view is released after capture. Markers stay live views positioned over the base map; polylines, polygons, circles, and ground overlays are drawn onto it. Tile overlays are not supported.
• iOS (Google) - markers and shapes render as live overlay views, exactly like Apple static maps. Only the base map needs the SDK (which has no async snapshotter): a live, tiles-only map warms up briefly under the overlays and is replaced with a rendered image once tiles finish loading, releasing the map's rendering resources. Warmup work scales with how many rows mount at once - bound it with your list's windowSize / initialNumToRender / maxToRenderPerBatch.
• Web (Google) - gestures, POI clicks, keyboard interaction, and press events are disabled; the map itself stays live.

<Pressable onPress={() => openPlace(place)}>
  <View style={{ height: 140 }} pointerEvents="none">
    <MapView
      staticMode
      staticKey={place.id}
      style={StyleSheet.absoluteFill}
      initialCoordinate={place.coordinate}
      initialZoom={14}
    >
      <Marker coordinate={place.coordinate} />
    </MapView>
  </View>
</Pressable>

Notes:

• staticMode is creation-time only and cannot be toggled after the map is created.
• Ref methods (moveCamera, fitCoordinates, setEdgeInsets) work like on a live map, minus animation - duration is ignored and the map re-renders at the final camera (iOS) or re-centers (Android). Map-setting prop updates (e.g. mapType) after the snapshot are still ignored on iOS.
• edgeInsets shift the visible center like on a live map, so the coordinate centers in the inset viewport without changing the zoom. On iOS, attribution also respects these insets. Changing insets after the render re-renders the base map (iOS) or re-centers the camera (Android).
• For taps, wrap the map in a Pressable with pointerEvents="none" on the map container (as above) instead of relying on onPress.
• animated polylines render as complete static polylines, so the snapshot never freezes a mid-animation frame.
• On iOS, markers are live views over the base map, revealed together with it - marker content that loads asynchronously (e.g. remote images) appears when ready, and marker prop updates still apply.
• While a static map loads, a theme-aware placeholder background is shown. Set a backgroundColor style on the MapView to use your own.
• Set staticKey (e.g. your list item's id) to cache base map images across list recycling on iOS - scrolling back to a row reuses its image instead of rendering the map again (markers and shapes stay live and re-render from props). The camera and map settings are part of the cache key automatically. Changing staticKey discards the current image and re-renders, and insets set with setEdgeInsets give way to the edgeInsets prop. The cache is bounded by count and total memory.
• On iOS (Google), the base map is only captured and cached once the SDK reports the map stable with all tiles loaded. If tiles fail (e.g. offline), the live warmup map stays in place instead and renders again the next time the row appears, so a bad render can't get stuck behind staticKey. To force it, call reload() on the ref.
• Alternatively, keeping rows mounted (larger windowSize with removeClippedSubviews) avoids re-rendering entirely at the cost of holding every row's snapshot in memory.
• In long lists, limit how many rows mount at once (e.g. windowSize, initialNumToRender, maxToRenderPerBatch on FlatList) - every mounted static map holds its snapshot image in memory.

Types

MapProvider

MapType

MapTheme

InsetAdjustment

PoiFilter

interface PoiFilter {
  mode?: 'including' | 'excluding'; // default: 'including'
  categories: PoiCategory[];
}

When mode is 'including', only the specified categories are shown. When 'excluding', all categories are shown except the specified ones.

PoiCategory

Ref Methods

import { useRef } from 'react';
import { MapView, MapViewRef } from '@lugg/maps';

const mapRef = useRef<MapViewRef>(null);

// Move camera to coordinate
mapRef.current?.moveCamera(
  { latitude: 37.7749, longitude: -122.4194 },
  { zoom: 15, duration: 500 }
);

// Fit coordinates in view
mapRef.current?.fitCoordinates(
  [
    { latitude: 37.7749, longitude: -122.4194 },
    { latitude: 37.8049, longitude: -122.4094 },
  ],
  { padding: { top: 50, left: 50, bottom: 50, right: 50 }, duration: 500 }
);

// Set edge insets with animation
mapRef.current?.setEdgeInsets(
  { top: 0, left: 0, bottom: 200, right: 0 },
  { duration: 300 }
);

// Load the map again (e.g. after a network outage)
mapRef.current?.reload();

moveCamera

Move the camera to a coordinate with optional zoom and animation duration. The current heading and pitch are preserved.

moveCamera(coordinate: Coordinate, options: MoveCameraOptions): void

interface MoveCameraOptions {
  zoom: number;
  duration?: number; // milliseconds, -1 for default
}

fitCoordinates

Fit multiple coordinates in the visible map area. Resets heading to north (0°).

fitCoordinates(coordinates: Coordinate[], options?: FitCoordinatesOptions): void

interface FitCoordinatesOptions {
  padding?: EdgeInsets;
  duration?: number; // milliseconds, -1 for default
}

setEdgeInsets

Programmatically update the map's edge insets with optional animation.

setEdgeInsets(edgeInsets: EdgeInsets, options?: SetEdgeInsetsOptions): void

interface SetEdgeInsetsOptions {
  duration?: number; // milliseconds, -1 for default animation, 0 for instant
}

Insets set this way stay in place when the map re-renders or other props change. The last write wins: a new edgeInsets prop value replaces them (instantly, also during an animation), and a later setEdgeInsets call replaces the prop.

moveCamera and fitCoordinates frame against the final insets, also while an inset animation is still running.

reload

Load the map again, e.g. to recover from missing tiles after a network outage. None of the map SDKs can reload tiles in place, so:

• A static map re-renders its base map. On iOS the cached snapshot for its staticKey is discarded and the new render replaces the current image when ready; on Android the lite map is recreated.
• A live map is recreated at its current coordinate and zoom. Heading and pitch reset, and onReady fires again. Markers and overlays remain on the map after reload.

Reload preserves the map type and edge insets. On web, onReady fires once for each new map instance. On iOS, an unfinished static reload restarts when the map leaves the window and returns.

reload(): void

Events

onPress / onLongPress

Called when the map is pressed or long pressed. Event includes the geographic coordinate and screen point.

interface PressEventPayload {
  coordinate: Coordinate;
  point: Point;
}

onCameraMove

Called continuously while the camera is moving.

interface CameraMoveEvent {
  coordinate: Coordinate;
  zoom: number;
  dragging: boolean; // true if user is dragging
}

onCameraIdle

Called when the camera stops moving.

interface CameraIdleEvent {
  coordinate: Coordinate;
  zoom: number;
}