capacitor-plugin-apple-maps

v0.5.0

Published

2 days ago

Capacitor plugin rendering native Apple Maps (MapKit) on iOS, API-compatible with @capacitor/google-maps.

0High
0Medium
0Low

pjaudiomv

capacitor plugin native

capacitor-plugin-apple-maps

Renders a native Apple Maps (MapKit) view on iOS from a Capacitor app. The AppleMap wrapper class deliberately mirrors the core subset of @capacitor/google-maps' GoogleMap API - create, camera, markers, clustering, and camera-idle / marker-click events - so an app can route iOS to Apple Maps and Android/web to Google Maps behind one thin abstraction.

iOS only. MapKit is a native iOS framework and needs no API key. On web and Android every method rejects with unavailable - the host app is expected to use another provider on those platforms.
No external dependencies. Uses the system MapKit framework; the only SPM dependency is capacitor-swift-pm.
Requires iOS 15+ (matches the Capacitor 8 baseline).

Install

npm install capacitor-plugin-apple-maps
npx cap sync ios

Usage

Bind the map to a <capacitor-apple-map> element (registered automatically when you import the wrapper):

<capacitor-apple-map id="map" style="position:absolute; inset:0"></capacitor-apple-map>

import { AppleMap } from 'capacitor-plugin-apple-maps';

const map = await AppleMap.create({
  id: 'map',
  element: document.getElementById('map')!,
  config: {
    center: { lat: 42.36, lng: -71.06 },
    zoom: 11,
    minZoom: 7,
  },
});

await map.setOnMarkerClickListener((data) => console.log('tapped', data.markerId));
await map.setOnCameraIdleListener((data) => console.log('idle at', data.zoom, data.bounds));

const ids = await map.addMarkers([
  { coordinate: { lat: 42.36, lng: -71.06 }, iconUrl: 'marker-blue.png', iconSize: { width: 30, height: 36 } },
]);
await map.enableClustering();

A marker with no iconUrl draws MapKit's native pin (MKMarkerAnnotationView), the same way @capacitor/google-maps falls back to a default marker - so a marker written against the shared API is always visible. Supply an iconUrl to use your own art, resolved from three sources: a bundled web asset filename (copied into the app bundle under public/ - e.g. marker-blue.png from your web static/), an https: URL, or a data: URI. SVG is not supported.

Sharing one abstraction with `@capacitor/google-maps`

The wrapper's method names and payload shapes (LatLng, LatLngBounds, CameraIdleCallbackData, MarkerClickCallbackData) match @capacitor/google-maps, so a host app can pick the provider per platform:

const map =
  Capacitor.getPlatform() === 'ios'
    ? await AppleMap.create({ id, element, config })
    : await GoogleMap.create({ id, element, apiKey, config });

Notes & limitations

Zoom is approximated. MapKit uses region spans, not Google's integer zoom; the plugin converts using the web-mercator tile relationship. Reported zoom round-trips but is not pixel-identical to Google.
Cluster taps zoom to fit the cluster members (Apple-native behaviour) rather than firing an event.
minZoom is enforced on programmatic moves and by bouncing back a gesture that overshoots the floor. maxZoom is currently advisory.

API

Low-level bridge to the native MapKit implementation. Most callers should use the {@link AppleMap} wrapper instead of these methods directly.

create(...)

create(options: { id: string; config: AppleMapConfig; element?: unknown; forceCreate?: boolean; }) => Promise<void>

| Param | Type | | ------------- | ---------------------------------------------------------------------------------------------------------------------------- | | options | { id: string; config: AppleMapConfig; element?: unknown; forceCreate?: boolean; } |

destroy(...)

destroy(options: { id: string; }) => Promise<void>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

setCamera(...)

setCamera(options: { id: string; config: CameraConfig; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------------------------------------ | | options | { id: string; config: CameraConfig; } |

getMapBounds(...)

getMapBounds(options: { id: string; }) => Promise<LatLngBounds>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

Returns: Promise<LatLngBounds>

getCameraPosition(...)

getCameraPosition(options: { id: string; }) => Promise<CameraPosition>

Current camera as { latitude, longitude, zoom, bounds }.

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

Returns: Promise<CameraPosition>

fitBounds(...)

fitBounds(options: { id: string; bounds: LatLngBounds; padding?: number; animate?: boolean; }) => Promise<void>

Move the camera to fit bounds, insetting the visible rect by padding points on every side (default 0). Animates unless animate is false.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------------------------------------- | | options | { id: string; bounds: LatLngBounds; padding?: number; animate?: boolean; } |

addMarkers(...)

addMarkers(options: { id: string; markers: Marker[]; }) => Promise<{ ids: string[]; }>

| Param | Type | | ------------- | ----------------------------------------------- | | options | { id: string; markers: Marker[]; } |

Returns: Promise<{ ids: string[]; }>

addMarker(...)

addMarker(options: { id: string; marker: Marker; }) => Promise<{ id: string; }>

Add a single marker, returning its id. Convenience over {@link addMarkers}.

| Param | Type | | ------------- | ------------------------------------------------------------------ | | options | { id: string; marker: Marker; } |

Returns: Promise<{ id: string; }>

updateMarkers(...)

updateMarkers(options: { id: string; markers: MarkerUpdate[]; }) => Promise<void>

Apply partial changes to existing markers, addressed by markerId.

| Param | Type | | ------------- | ----------------------------------------------------- | | options | { id: string; markers: MarkerUpdate[]; } |

removeMarkers(...)

removeMarkers(options: { id: string; markerIds: string[]; }) => Promise<void>

| Param | Type | | ------------- | ------------------------------------------------- | | options | { id: string; markerIds: string[]; } |

removeMarker(...)

removeMarker(options: { id: string; markerId: string; }) => Promise<void>

Remove a single marker by id. Convenience over {@link removeMarkers}.

| Param | Type | | ------------- | ---------------------------------------------- | | options | { id: string; markerId: string; } |

enableClustering(...)

enableClustering(options: { id: string; }) => Promise<void>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

disableClustering(...)

disableClustering(options: { id: string; }) => Promise<void>

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

addPolylines(...)

addPolylines(options: { id: string; polylines: Polyline[]; }) => Promise<{ ids: string[]; }>

| Param | Type | | ------------- | --------------------------------------------------- | | options | { id: string; polylines: Polyline[]; } |

Returns: Promise<{ ids: string[]; }>

addPolygons(...)

addPolygons(options: { id: string; polygons: Polygon[]; }) => Promise<{ ids: string[]; }>

| Param | Type | | ------------- | ------------------------------------------------- | | options | { id: string; polygons: Polygon[]; } |

Returns: Promise<{ ids: string[]; }>

addCircles(...)

addCircles(options: { id: string; circles: Circle[]; }) => Promise<{ ids: string[]; }>

| Param | Type | | ------------- | ----------------------------------------------- | | options | { id: string; circles: Circle[]; } |

Returns: Promise<{ ids: string[]; }>

removeOverlays(...)

removeOverlays(options: { id: string; ids: string[]; }) => Promise<void>

Remove overlays (polylines, polygons, or circles) by the ids their add call returned.

| Param | Type | | ------------- | ------------------------------------------- | | options | { id: string; ids: string[]; } |

setMapType(...)

setMapType(options: { id: string; mapType: MapType; }) => Promise<void>

Set the base map imagery.

| Param | Type | | ------------- | --------------------------------------------------------------------- | | options | { id: string; mapType: MapType; } |

enableCurrentLocation(...)

enableCurrentLocation(options: { id: string; enabled: boolean; }) => Promise<void>

Show or hide the blue user-location dot. The host app is responsible for the NSLocationWhenInUseUsageDescription Info.plist key and for prompting the user for location permission; without it MapKit shows nothing.

| Param | Type | | ------------- | ---------------------------------------------- | | options | { id: string; enabled: boolean; } |

setTrafficEnabled(...)

setTrafficEnabled(options: { id: string; enabled: boolean; }) => Promise<void>

Overlay or hide live traffic conditions (MKMapView.showsTraffic).

| Param | Type | | ------------- | ---------------------------------------------- | | options | { id: string; enabled: boolean; } |

setPointsOfInterestEnabled(...)

setPointsOfInterestEnabled(options: { id: string; enabled: boolean; }) => Promise<void>

Show or hide Apple's points of interest (a .includingAll / .excludingAll filter).

| Param | Type | | ------------- | ---------------------------------------------- | | options | { id: string; enabled: boolean; } |

setCompassEnabled(...)

setCompassEnabled(options: { id: string; enabled: boolean; }) => Promise<void>

Show or hide the compass (MKMapView.showsCompass).

| Param | Type | | ------------- | ---------------------------------------------- | | options | { id: string; enabled: boolean; } |

setScaleEnabled(...)

setScaleEnabled(options: { id: string; enabled: boolean; }) => Promise<void>

Show or hide the scale bar (MKMapView.showsScale).

| Param | Type | | ------------- | ---------------------------------------------- | | options | { id: string; enabled: boolean; } |

setColorScheme(...)

setColorScheme(options: { id: string; colorScheme: MapColorScheme; }) => Promise<void>

Force a light/dark appearance, or default to follow the device setting.

| Param | Type | | ------------- | --------------------------------------------------------------------------------------- | | options | { id: string; colorScheme: MapColorScheme; } |

setGestures(...)

setGestures(options: { id: string; gestures: MapGestures; }) => Promise<void>

Enable or disable user gestures (only the fields you pass are changed).

| Param | Type | | ------------- | ------------------------------------------------------------------------------ | | options | { id: string; gestures: MapGestures; } |

setPadding(...)

setPadding(options: { id: string; padding: MapPadding; }) => Promise<void>

Inset the map's edges (shifts controls inward and pads fitBounds).

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | { id: string; padding: MapPadding; } |

takeSnapshot(...)

takeSnapshot(options: { id: string; }) => Promise<{ image: string; }>

Render the current map view to a PNG, returned as a data: URL - the visible base map with the marker pins and overlays composited on top.

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

Returns: Promise<{ image: string; }>

searchAutocomplete(...)

searchAutocomplete(options: { query: string; region?: SearchRegion; }) => Promise<{ results: SearchCompletion[]; }>

Type-ahead place autocomplete via MKLocalSearchCompleter. Needs no API key. Pass region to bias suggestions toward the area in view. Each result carries an opaque id; pass it to {@link searchResolve} to get coordinates.

| Param | Type | | ------------- | ---------------------------------------------------------------------------------- | | options | { query: string; region?: SearchRegion; } |

Returns: Promise<{ results: SearchCompletion[]; }>

searchPlaces(...)

searchPlaces(options: { query: string; region?: SearchRegion; maxDistanceKm?: number; limit?: number; }) => Promise<{ results: SearchResult[]; }>

One-shot place search via MKLocalSearch. Unlike {@link searchAutocomplete} the results carry coordinates up front. Pass region to scope/bias results, maxDistanceKm to drop results farther than that from the region center (e.g. a US ZIP that also exists abroad), and limit to cap the count.

| Param | Type | | ------------- | -------------------------------------------------------------------------------------------------------------------------- | | options | { query: string; region?: SearchRegion; maxDistanceKm?: number; limit?: number; } |

Returns: Promise<{ results: SearchResult[]; }>

searchResolve(...)

searchResolve(options: { id: string; }) => Promise<{ lat?: number; lng?: number; title?: string; }>

Resolve a suggestion id (from either search method) to coordinates. Returns an empty object if the id is unknown or has no location.

| Param | Type | | ------------- | ---------------------------- | | options | { id: string; } |

Returns: Promise<{ lat?: number; lng?: number; title?: string; }>

onResize(...)

onResize(options: { id: string; mapBounds: MapBounds; }) => Promise<void>

Keep the native frame in sync as the element resizes.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | { id: string; mapBounds: MapBounds; } |

onDisplay(...)

onDisplay(options: { id: string; mapBounds: MapBounds; }) => Promise<void>

Re-mount the native view after the element becomes visible again.

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | { id: string; mapBounds: MapBounds; } |

onScroll(...)

onScroll(options: { id: string; mapBounds: MapBounds; }) => Promise<void>

Keep the native frame in sync as the page scrolls (no-op on iOS).

| Param | Type | | ------------- | --------------------------------------------------------------------------- | | options | { id: string; mapBounds: MapBounds; } |

addListener('onCameraIdle', ...)

addListener(eventName: 'onCameraIdle', listenerFunc: (data: CameraIdleCallbackData) => void) => Promise<PluginListenerHandle>

| Param | Type | | ------------------ | -------------------------------------------------------------------------------------------- | | eventName | 'onCameraIdle' | | listenerFunc | (data: CameraIdleCallbackData) => void |