Skip to content

MAPVIEW.md

Latest commit

 

History

History
273 lines (225 loc) · 8.19 KB

MAPVIEW.md

File metadata and controls

273 lines (225 loc) · 8.19 KB

MapView

Main map component.

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

Prop Type Default Description
provider MapProvider 'apple' (iOS), 'google' (Android) Map provider
mapType MapType 'standard' Map display type
mapId string - Map style ID (Google) or configuration name (Apple)
initialCoordinate Coordinate - Initial camera coordinate
initialZoom number 10 Initial zoom level
zoomEnabled boolean true Enable zoom gestures
scrollEnabled boolean true Enable scroll/pan gestures
rotateEnabled boolean true Enable rotation gestures
pitchEnabled boolean true Enable pitch/tilt gestures
edgeInsets EdgeInsets - Map content edge insets
userLocationEnabled boolean false Show current user location on the map
userLocationButtonEnabled boolean false Show native my-location button (Android only)
poiEnabled boolean true Show points of interest (Apple Maps only)
poiFilter PoiFilter - Filter POI categories (Apple Maps only)
theme MapTheme 'system' Map color theme
insetAdjustment 'automatic' | 'never' 'never' Safe area inset adjustment behavior
onPress (event: MapPressEvent) => void - Called when the map is pressed
onLongPress (event: MapPressEvent) => void - Called when the map is long pressed
onCameraMove (event: MapCameraEvent) => void - Called when camera moves
onCameraIdle (event: MapCameraEvent) => void - Called when camera stops moving
onReady () => void - Called when map is loaded and ready

Types

MapProvider

Value Description
'google' Google Maps
'apple' Apple Maps (iOS only)

MapType

Value Description
'standard' Default map style
'satellite' Satellite imagery
'terrain' Terrain/topographic map
'hybrid' Satellite imagery with labels
'muted-standard' Muted standard style (Apple Maps only, falls back to standard on Google Maps)

MapTheme

Value Description
'light' Light appearance
'dark' Dark appearance
'system' Follow system appearance

InsetAdjustment

Value Description
'never' No safe area inset adjustment
'automatic' Automatically adjust for safe area insets

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

Value Description Availability
'airport' Airports iOS 13+
'amusement-park' Amusement parks iOS 13+
'animal-service' Animal services iOS 18+
'aquarium' Aquariums iOS 13+
'atm' ATMs iOS 13+
'automotive-repair' Automotive repair iOS 18+
'bakery' Bakeries iOS 13+
'bank' Banks iOS 13+
'baseball' Baseball iOS 18+
'basketball' Basketball iOS 18+
'beach' Beaches iOS 13+
'beauty' Beauty services iOS 18+
'bowling' Bowling iOS 18+
'brewery' Breweries iOS 13+
'cafe' Cafes iOS 13+
'campground' Campgrounds iOS 13+
'car-rental' Car rental locations iOS 13+
'castle' Castles iOS 18+
'convention-center' Convention centers iOS 18+
'distillery' Distilleries iOS 18+
'ev-charger' EV charging stations iOS 13+
'fairground' Fairgrounds iOS 18+
'fire-station' Fire stations iOS 13+
'fishing' Fishing iOS 18+
'fitness-center' Fitness centers iOS 13+
'food-market' Food markets iOS 13+
'fortress' Fortresses iOS 18+
'gas-station' Gas stations iOS 13+
'go-kart' Go-kart iOS 18+
'golf' Golf iOS 18+
'hiking' Hiking iOS 18+
'hospital' Hospitals iOS 13+
'hotel' Hotels iOS 13+
'kayaking' Kayaking iOS 18+
'landmark' Landmarks iOS 18+
'laundry' Laundry services iOS 13+
'library' Libraries iOS 13+
'mailbox' Mailboxes iOS 18+
'marina' Marinas iOS 13+
'mini-golf' Mini golf iOS 18+
'movie-theater' Movie theaters iOS 13+
'museum' Museums iOS 13+
'music-venue' Music venues iOS 18+
'national-monument' National monuments iOS 18+
'national-park' National parks iOS 13+
'nightlife' Nightlife venues iOS 13+
'park' Parks iOS 13+
'parking' Parking lots iOS 13+
'pharmacy' Pharmacies iOS 13+
'planetarium' Planetariums iOS 18+
'police' Police stations iOS 13+
'post-office' Post offices iOS 13+
'public-transport' Public transport stations iOS 13+
'restaurant' Restaurants iOS 13+
'restroom' Restrooms iOS 13+
'rock-climbing' Rock climbing iOS 18+
'rv-park' RV parks iOS 18+
'school' Schools iOS 13+
'skate-park' Skate parks iOS 18+
'skating' Skating iOS 18+
'skiing' Skiing iOS 18+
'soccer' Soccer iOS 18+
'spa' Spas iOS 18+
'stadium' Stadiums iOS 13+
'store' Stores iOS 13+
'surfing' Surfing iOS 18+
'swimming' Swimming iOS 18+
'tennis' Tennis iOS 18+
'theater' Theaters iOS 13+
'university' Universities iOS 13+
'volleyball' Volleyball iOS 18+
'winery' Wineries iOS 13+
'zoo' Zoos iOS 13+

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 }
);

moveCamera

Move the camera to a coordinate with optional zoom and animation duration.

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.

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
}

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;
}