Awesome

@capacitor/google-maps

Google maps on Capacitor

Install

npm install @capacitor/google-maps
npx cap sync

API Keys

To use the Google Maps SDK on any platform, API keys associated with an account with billing enabled are required. These can be obtained from the Google Cloud Console. This is required for all three platforms, Android, iOS, and Javascript. Additional information about obtaining these API keys can be found in the Google Maps documentation for each platform.

iOS

The Google Maps SDK supports the use of showing the users current location via enableCurrentLocation(bool). To use this, Apple requires privacy descriptions to be specified in Info.plist:

• NSLocationWhenInUseUsageDescription (Privacy - Location When In Use Usage Description)

Read about Configuring Info.plist in the iOS Guide for more information on setting iOS permissions in Xcode.

Minimum Deployment Target

Version 6 of this plugin has a minimum deployment target of iOS 14.0. You will need to edit ios/App/Podfile and change the following line from 13.0 to 14.0:

platform :ios, '14.0'

Additionally, you will need to open your project in XCode and in the Build Settings tab for your Project and for each Target set the iOS Deployment Target to iOS 14.0 or higher.

Typescript Configuration

Your project will also need have skipLibCheck set to true in tsconfig.json.

Migrating from older versions

The main Google Maps SDK now supports running on simulators on Apple Silicon Macs, but make sure you have the latest version of Google-Maps-iOS-Utils installed.

If you added the previous workaround for getting the unreleased version, you can delete it now by removing this line from ios/App/Podfile:

pod 'Google-Maps-iOS-Utils', :git => 'https://github.com/googlemaps/google-maps-ios-utils.git', :commit => '637954e5bcb2a879c11a6f2cead153a6bad5339f'

Then run pod update Google-Maps-iOS-Utils from the ios/App/ folder:

cd ios/App
pod update Google-Maps-iOS-Utils

Android

The Google Maps SDK for Android requires you to add your API key to the AndroidManifest.xml file in your project.

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

To use certain location features, the SDK requires the following permissions to also be added to your AndroidManifest.xml:

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

Variables

This plugin will use the following project variables (defined in your app's variables.gradle file):

• googleMapsPlayServicesVersion: version of com.google.android.gms:play-services-maps (default: 18.2.0)
• googleMapsUtilsVersion: version of com.google.maps.android:android-maps-utils (default: 3.8.2)
• googleMapsKtxVersion: version of com.google.maps.android:maps-ktx (default: 5.0.0)
• googleMapsUtilsKtxVersion: version of com.google.maps.android:maps-utils-ktx (default: 5.0.0)
• kotlinxCoroutinesVersion: version of org.jetbrains.kotlinx:kotlinx-coroutines-android and org.jetbrains.kotlinx:kotlinx-coroutines-core (default: 1.7.3)
• androidxCoreKTXVersion: version of androidx.core:core-ktx (default: 1.12.0)
• kotlin_version: version of org.jetbrains.kotlin:kotlin-stdlib (default: 1.9.10)

Usage

The Google Maps Capacitor plugin ships with a web component that must be used to render the map in your application as it enables us to embed the native view more effectively on iOS. The plugin will automatically register this web component for use in your application.

For Angular users, you will get an error warning that this web component is unknown to the Angular compiler. This is resolved by modifying the module that declares your component to allow for custom web components.

import { CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';

@NgModule({
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})

Include this component in your HTML and assign it an ID so that you can easily query for that element reference later.

<capacitor-google-map id="map"></capacitor-google-map>

On Android, the map is rendered beneath the entire webview, and uses this component to manage its positioning during scrolling events. This means that as the developer, you must ensure that the webview is transparent all the way through the layers to the very bottom. In a typically Ionic application, that means setting transparency on elements such as IonContent and the root HTML tag to ensure that it can be seen. If you can't see your map on Android, this should be the first thing you check.

On iOS, we render the map directly into the webview and so the same transparency effects are not required. We are investigating alternate methods for Android still and hope to resolve this better in a future update.

The Google Map element itself comes unstyled, so you should style it to fit within the layout of your page structure. Because we're rendering a view into this slot, by itself the element has no width or height, so be sure to set those explicitly.

capacitor-google-map {
  display: inline-block;
  width: 275px;
  height: 400px;
}

Next, we should create the map reference. This is done by importing the GoogleMap class from the Capacitor plugin and calling the create method, and passing in the required parameters.

import { GoogleMap } from '@capacitor/google-maps';

const apiKey = 'YOUR_API_KEY_HERE';

const mapRef = document.getElementById('map');

const newMap = await GoogleMap.create({
  id: 'my-map', // Unique identifier for this map instance
  element: mapRef, // reference to the capacitor-google-map element
  apiKey: apiKey, // Your Google Maps API Key
  config: {
    center: {
      // The initial position to be rendered by the map
      lat: 33.6,
      lng: -117.9,
    },
    zoom: 8, // The initial zoom level to be rendered by the map
  },
});

At this point, your map should be created within your application. Using the returned reference to the map, you can easily interact with your map in a number of way, a few of which are shown here.

const newMap = await GoogleMap.create({...});

// Add a marker to the map
const markerId = await newMap.addMarker({
  coordinate: {
    lat: 33.6,
    lng: -117.9
  }
});

// Move the map programmatically
await newMap.setCamera({
  coordinate: {
    lat: 33.6,
    lng: -117.9
  }
});

// Enable marker clustering
await newMap.enableClustering();

// Handle marker click
await newMap.setOnMarkerClickListener((event) => {...});

// Clean up map reference
await newMap.destroy();

Full Examples

Angular

import { GoogleMap } from '@capacitor/google-maps';

@Component({
  template: `
    <capacitor-google-map #map></capacitor-google-map>
    <button (click)="createMap()">Create Map</button>
  `,
  styles: [
    `
      capacitor-google-map {
        display: inline-block;
        width: 275px;
        height: 400px;
      }
    `,
  ],
})
export class MyMap {
  @ViewChild('map')
  mapRef: ElementRef<HTMLElement>;
  newMap: GoogleMap;

  async createMap() {
    this.newMap = await GoogleMap.create({
      id: 'my-cool-map',
      element: this.mapRef.nativeElement,
      apiKey: environment.apiKey,
      config: {
        center: {
          lat: 33.6,
          lng: -117.9,
        },
        zoom: 8,
      },
    });
  }
}

React

import { GoogleMap } from '@capacitor/google-maps';
import { useRef } from 'react';

const MyMap: React.FC = () => {
  const mapRef = useRef<HTMLElement>();
  let newMap: GoogleMap;

  async function createMap() {
    if (!mapRef.current) return;

    newMap = await GoogleMap.create({
      id: 'my-cool-map',
      element: mapRef.current,
      apiKey: process.env.REACT_APP_YOUR_API_KEY_HERE,
      config: {
        center: {
          lat: 33.6,
          lng: -117.9
        },
        zoom: 8
      }
    })
  }

  return (
    <div className="component-wrapper">
      <capacitor-google-map ref={mapRef} style={{
        display: 'inline-block',
        width: 275,
        height: 400
      }}></capacitor-google-map>

      <button onClick={createMap}>Create Map</button>
    </div>
  )
}

export default MyMap;

Javascript

<capacitor-google-map id="map"></capacitor-google-map>
<button onclick="createMap()">Create Map</button>

<style>
  capacitor-google-map {
    display: inline-block;
    width: 275px;
    height: 400px;
  }
</style>

<script>
  import { GoogleMap } from '@capacitor/google-maps';

  const createMap = async () => {
    const mapRef = document.getElementById('map');

    const newMap = await GoogleMap.create({
      id: 'my-map', // Unique identifier for this map instance
      element: mapRef, // reference to the capacitor-google-map element
      apiKey: 'YOUR_API_KEY_HERE', // Your Google Maps API Key
      config: {
        center: {
          // The initial position to be rendered by the map
          lat: 33.6,
          lng: -117.9,
        },
        zoom: 8, // The initial zoom level to be rendered by the map
      },
    });
  };
</script>

API

• create(...)
• enableTouch()
• disableTouch()
• enableClustering(...)
• disableClustering()
• addMarker(...)
• addMarkers(...)
• removeMarker(...)
• removeMarkers(...)
• addPolygons(...)
• removePolygons(...)
• addCircles(...)
• removeCircles(...)
• addPolylines(...)
• removePolylines(...)
• destroy()
• setCamera(...)
• getMapType()
• setMapType(...)
• enableIndoorMaps(...)
• enableTrafficLayer(...)
• enableAccessibilityElements(...)
• enableCurrentLocation(...)
• setPadding(...)
• fitBounds(...)
• setOnBoundsChangedListener(...)
• setOnCameraIdleListener(...)
• setOnCameraMoveStartedListener(...)
• setOnClusterClickListener(...)
• setOnClusterInfoWindowClickListener(...)
• setOnInfoWindowClickListener(...)
• setOnMapClickListener(...)
• setOnMarkerClickListener(...)
• setOnPolygonClickListener(...)
• setOnCircleClickListener(...)
• setOnPolylineClickListener(...)
• setOnMarkerDragStartListener(...)
• setOnMarkerDragListener(...)
• setOnMarkerDragEndListener(...)
• setOnMyLocationButtonClickListener(...)
• setOnMyLocationClickListener(...)
• Interfaces
• Type Aliases
• Enums

create(...)

create(options: CreateMapArgs, callback?: MapListenerCallback<MapReadyCallbackData> | undefined) => Promise<GoogleMap>

Returns: <code>Promise<GoogleMap></code>

enableTouch()

enableTouch() => Promise<void>

disableTouch()

disableTouch() => Promise<void>

enableClustering(...)

enableClustering(minClusterSize?: number | undefined) => Promise<void>

disableClustering()

disableClustering() => Promise<void>

addMarker(...)

addMarker(marker: Marker) => Promise<string>

Returns: <code>Promise<string></code>

addMarkers(...)

addMarkers(markers: Marker[]) => Promise<string[]>

Returns: <code>Promise<string[]></code>

removeMarker(...)

removeMarker(id: string) => Promise<void>

removeMarkers(...)

removeMarkers(ids: string[]) => Promise<void>

addPolygons(...)

addPolygons(polygons: Polygon[]) => Promise<string[]>

Returns: <code>Promise<string[]></code>

removePolygons(...)

removePolygons(ids: string[]) => Promise<void>

addCircles(...)

addCircles(circles: Circle[]) => Promise<string[]>

Returns: <code>Promise<string[]></code>

removeCircles(...)

removeCircles(ids: string[]) => Promise<void>

addPolylines(...)

addPolylines(polylines: Polyline[]) => Promise<string[]>

Returns: <code>Promise<string[]></code>

removePolylines(...)

removePolylines(ids: string[]) => Promise<void>

destroy()

destroy() => Promise<void>

setCamera(...)

setCamera(config: CameraConfig) => Promise<void>

getMapType()

getMapType() => Promise<MapType>

Get current map type

Returns: <code>Promise<<a href="#maptype">MapType</a>></code>

setMapType(...)

setMapType(mapType: MapType) => Promise<void>

enableIndoorMaps(...)

enableIndoorMaps(enabled: boolean) => Promise<void>

enableTrafficLayer(...)

enableTrafficLayer(enabled: boolean) => Promise<void>

enableAccessibilityElements(...)

enableAccessibilityElements(enabled: boolean) => Promise<void>

enableCurrentLocation(...)

enableCurrentLocation(enabled: boolean) => Promise<void>

setPadding(...)

setPadding(padding: MapPadding) => Promise<void>

fitBounds(...)

fitBounds(bounds: LatLngBounds, padding?: number | undefined) => Promise<void>

Sets the map viewport to contain the given bounds.

setOnBoundsChangedListener(...)

setOnBoundsChangedListener(callback?: MapListenerCallback<CameraIdleCallbackData> | undefined) => Promise<void>

setOnCameraIdleListener(...)

setOnCameraIdleListener(callback?: MapListenerCallback<CameraIdleCallbackData> | undefined) => Promise<void>

setOnCameraMoveStartedListener(...)

setOnCameraMoveStartedListener(callback?: MapListenerCallback<CameraMoveStartedCallbackData> | undefined) => Promise<void>

setOnClusterClickListener(...)

setOnClusterClickListener(callback?: MapListenerCallback<ClusterClickCallbackData> | undefined) => Promise<void>

setOnClusterInfoWindowClickListener(...)

setOnClusterInfoWindowClickListener(callback?: MapListenerCallback<ClusterClickCallbackData> | undefined) => Promise<void>

setOnInfoWindowClickListener(...)

setOnInfoWindowClickListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>

setOnMapClickListener(...)

setOnMapClickListener(callback?: MapListenerCallback<MapClickCallbackData> | undefined) => Promise<void>

setOnMarkerClickListener(...)

setOnMarkerClickListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>

setOnPolygonClickListener(...)

setOnPolygonClickListener(callback?: MapListenerCallback<PolygonClickCallbackData> | undefined) => Promise<void>

setOnCircleClickListener(...)

setOnCircleClickListener(callback?: MapListenerCallback<CircleClickCallbackData> | undefined) => Promise<void>

setOnPolylineClickListener(...)

setOnPolylineClickListener(callback?: MapListenerCallback<PolylineCallbackData> | undefined) => Promise<void>

setOnMarkerDragStartListener(...)

setOnMarkerDragStartListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>

setOnMarkerDragListener(...)

setOnMarkerDragListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>

setOnMarkerDragEndListener(...)

setOnMarkerDragEndListener(callback?: MapListenerCallback<MarkerClickCallbackData> | undefined) => Promise<void>

setOnMyLocationButtonClickListener(...)

setOnMyLocationButtonClickListener(callback?: MapListenerCallback<MyLocationButtonClickCallbackData> | undefined) => Promise<void>

setOnMyLocationClickListener(...)

setOnMyLocationClickListener(callback?: MapListenerCallback<MapClickCallbackData> | undefined) => Promise<void>

Interfaces

CreateMapArgs

An interface containing the options used when creating a map.

GoogleMapConfig

For web, all the javascript Google Maps options are available as GoogleMapConfig extends google.maps.MapOptions. For iOS and Android only the config options declared on <a href="#googlemapconfig">GoogleMapConfig</a> are available.

LatLng

An interface representing a pair of latitude and longitude coordinates.

MapReadyCallbackData

Marker

A marker is an icon placed at a particular point on the map's surface.

Size

Point

<a href="#point">Point</a> geometry object. https://tools.ietf.org/html/rfc7946#section-3.1.2

Polygon

<a href="#polygon">Polygon</a> geometry object. https://tools.ietf.org/html/rfc7946#section-3.1.6

Circle

For web, all the javascript <a href="#circle">Circle</a> options are available as Polygon extends google.maps.CircleOptions. For iOS and Android only the config options declared on <a href="#circle">Circle</a> are available.

Polyline

For web, all the javascript <a href="#polyline">Polyline</a> options are available as Polyline extends google.maps.PolylineOptions. For iOS and Android only the config options declared on <a href="#polyline">Polyline</a> are available.

StyleSpan

Describes the style for some region of a polyline.

CameraConfig

Configuration properties for a Google Map Camera

MapPadding

Controls for setting padding on the 'visible' region of the view.

CameraIdleCallbackData

CameraMoveStartedCallbackData

ClusterClickCallbackData

MarkerCallbackData

MarkerClickCallbackData

MapClickCallbackData

PolygonClickCallbackData

CircleClickCallbackData

PolylineCallbackData

MyLocationButtonClickCallbackData

Type Aliases

MapListenerCallback

The callback function to be called when map events are emitted.

<code>(data: T): void</code>

Position

A <a href="#position">Position</a> is an array of coordinates. https://tools.ietf.org/html/rfc7946#section-3.1.1 Array should contain between two and three elements. The previous GeoJSON specification allowed more elements (e.g., which could be used to represent M values), but the current specification only allows X, Y, and (optionally) Z to be defined.

<code>number[]</code>

Enums

MapType