• Stars
    star
    1,055
  • Rank 42,011 (Top 0.9 %)
  • Language
    Kotlin
  • License
    Apache License 2.0
  • Created about 2 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Jetpack Compose composables for the Maps SDK for Android

Tests Stable Discord Apache-2.0

Maps Compose 🗺

Description

This repository contains Jetpack Compose components for the Maps SDK for Android.

Requirements

  • Kotlin-enabled project
  • Jetpack Compose-enabled project (see releases for the required version of Jetpack Compose)
  • An API key
  • API level 21+

Installation

dependencies {
    implementation 'com.google.maps.android:maps-compose:2.11.2'

    // Make sure to also include the latest version of the Maps SDK for Android
    implementation 'com.google.android.gms:play-services-maps:18.0.2'

    // Optionally, you can include the Compose utils library for Clustering, etc.
    implementation 'com.google.maps.android:maps-compose-utils:2.11.2'

    // Optionally, you can include the widgets library for ScaleBar, etc.
    implementation 'com.google.maps.android:maps-compose-widgets:2.11.2'
}

Sample App

This repository includes a sample app.

To run it:

  1. Get a Maps API key
  2. Create a file in the root directory named local.properties with a single line that looks like this, replacing YOUR_KEY with the key from step 1: MAPS_API_KEY=YOUR_KEY
  3. Build and run

Documentation

You can learn more about all the extensions provided by this library by reading the reference documents.

Usage

Adding a map to your app looks like the following:

val singapore = LatLng(1.35, 103.87)
val cameraPositionState = rememberCameraPositionState {
    position = CameraPosition.fromLatLngZoom(singapore, 10f)
}
GoogleMap(
    modifier = Modifier.fillMaxSize(),
    cameraPositionState = cameraPositionState
)
Creating and configuring a map

Creating and configuring a map

Configuring the map can be done by passing a MapProperties object into the GoogleMap composable, or for UI-related configurations, use MapUiSettings. MapProperties and MapUiSettings should be your first go-to for configuring the map. For any other configuration not present in those two classes, use googleMapOptionsFactory to provide a GoogleMapOptions instance instead. Typically, anything that can only be provided once (i.e. when the map is created)—like map ID—should be provided via googleMapOptionsFactory.

// Set properties using MapProperties which you can use to recompose the map
var mapProperties by remember {
    mutableStateOf(
        MapProperties(maxZoomPreference = 10f, minZoomPreference = 5f)
    )
}
var mapUiSettings by remember {
    mutableStateOf(
        MapUiSettings(mapToolbarEnabled = false)
    )
}
Box(Modifier.fillMaxSize()) {
    GoogleMap(properties = mapProperties, uiSettings = mapUiSettings)
    Column {
        Button(onClick = {
            mapProperties = mapProperties.copy(
                isBuildingEnabled = !mapProperties.isBuildingEnabled
            )
        }) {
            Text(text = "Toggle isBuildingEnabled")
        }
        Button(onClick = {
            mapUiSettings = mapUiSettings.copy(
                mapToolbarEnabled = !mapUiSettings.mapToolbarEnabled
            )
        }) {
            Text(text = "Toggle mapToolbarEnabled")
        }
    }
}

// ...or initialize the map by providing a googleMapOptionsFactory
// This should only be used for values that do not recompose the map such as
// map ID.
GoogleMap(
    googleMapOptionsFactory = {
        GoogleMapOptions().mapId("MyMapId")
    }
)
Controlling a map's camera

Controlling a map's camera

Camera changes and updates can be observed and controlled via CameraPositionState.

Note: CameraPositionState is the source of truth for anything camera related. So, providing a camera position in GoogleMapOptions will be overridden by CameraPosition.

val singapore = LatLng(1.35, 103.87)
val cameraPositionState: CameraPositionState = rememberCameraPositionState {
    position = CameraPosition.fromLatLngZoom(singapore, 11f)
}
Box(Modifier.fillMaxSize()) {
  GoogleMap(cameraPositionState = cameraPositionState)
  Button(onClick = {
    // Move the camera to a new zoom level
    cameraPositionState.move(CameraUpdateFactory.zoomIn())
  }) {
      Text(text = "Zoom In")
  }
}
Drawing on a map

Drawing on a map

Drawing on the map, such as adding markers, can be accomplished by adding child composable elements to the content of the GoogleMap.

GoogleMap(
  //...
) {
    Marker(
        state = MarkerState(position = LatLng(-34, 151)),
        title = "Marker in Sydney"
    )
    Marker(
        state = MarkerState(position = LatLng(35.66, 139.6)),
        title = "Marker in Tokyo"
    )
}
Customizing a marker's info window

Customizing a marker's info window

You can customize a marker's info window contents by using the MarkerInfoWindowContent element, or if you want to customize the entire info window, use the MarkerInfoWindow element instead. Both of these elements accept a content parameter to provide your customization in a composable lambda expression.

MarkerInfoWindowContent(
    //...
) { marker ->
    Text(marker.title ?: "Default Marker Title", color = Color.Red)
}

MarkerInfoWindow(
    //...
) { marker ->
    // Implement the custom info window here
    Column {
        Text(marker.title ?: "Default Marker Title", color = Color.Red)
        Text(marker.snippet ?: "Default Marker Snippet", color = Color.Red)
    }
}
Street View

Street View

You can add a Street View given a location using the StreetView composable. To use it, provide a StreetViewPanoramaOptions object as follows:

val singapore = LatLng(1.35, 103.87)
StreetView(
    streetViewPanoramaOptionsFactory = {
        StreetViewPanoramaOptions().position(singapore)
    }
)
Controlling the map directly (experimental)

Controlling the map directly (experimental)

Certain use cases may require extending the GoogleMap object to decorate / augment the map. It can be obtained with the MapEffect Composable. Doing so can be dangerous, as the GoogleMap object is managed by this library.

GoogleMap(
    // ...
) {
    MapEffect { map ->
        // map is the GoogleMap
    }
}

Utility Library

This library also provides optional utilities in the maps-compose-utils library.

Clustering

The marker clustering utility helps you manage multiple markers at different zoom levels. When a user views the map at a high zoom level, the individual markers show on the map. When the user zooms out, the markers gather together into clusters, to make viewing the map easier.

The MapClusteringActivity demonstrates usage.

Clustering(
    items = items,
    // Optional: Handle clicks on clusters, cluster items, and cluster item info windows
    onClusterClick = null,
    onClusterItemClick = null,
    onClusterItemInfoWindowClick = null,
    // Optional: Custom rendering for clusters
    clusterContent = null,
    // Optional: Custom rendering for non-clustered items
    clusterItemContent = null,
)

Widgets

This library also provides optional composable widgets in the maps-compose-widgets library that you can use alongside the GoogleMap composable.

ScaleBar

This widget shows the current scale of the map in feet and meters when zoomed into the map, changing to miles and kilometers, respectively, when zooming out. A DisappearingScaleBar is also included, which appears when the zoom level of the map changes, and then disappears after a configurable timeout period.

The ScaleBarActivity demonstrates both of these, with the DisappearingScaleBar in the upper left corner and the normal base ScaleBar in the upper right:

maps-compose-scale-bar-cropped

Both versions of this widget leverage the CameraPositionState in maps-compose and therefore are very simple to configure with their defaults:

ScaleBar(
    modifier = Modifier
            .padding(top = 5.dp, end = 15.dp)
            .align(Alignment.TopEnd),
    cameraPositionState = cameraPositionState
)

DisappearingScaleBar(
    modifier = Modifier
            .padding(top = 5.dp, end = 15.dp)
            .align(Alignment.TopStart),
    cameraPositionState = cameraPositionState
)

The colors of the text, line, and shadow are also all configurable (e.g., based on isSystemInDarkTheme() on a dark map). Similarly, the DisappearingScaleBar animations can be configured.

Contributing

Contributions are welcome and encouraged! See contributing for more info.

Support

Encounter an issue while using this library?

If you find a bug or have a feature request, please file an issue. Or, if you'd like to contribute, send us a pull request and refer to our code of conduct.

You can also discuss this library on our Discord server.

More Repositories

1

google-maps-services-python

Python client library for Google Maps API Web Services
Python
4,327
star
2

android-maps-utils

Maps SDK for Android Utility Library
Java
3,519
star
3

google-maps-services-js

Node.js client library for Google Maps API Web Services
TypeScript
2,807
star
4

android-samples

Samples demonstrating how to use Maps SDK for Android
Java
2,351
star
5

google-maps-services-java

Java client library for Google Maps API Web Services
Java
1,675
star
6

v3-utility-library

Utility libraries for Google Maps JavaScript API v3
JavaScript
1,094
star
7

js-samples

Samples for the Google Maps JavaScript v3 API
TypeScript
701
star
8

google-maps-ios-utils

Google Maps SDK for iOS Utility Library
Objective-C
699
star
9

google-maps-services-go

Go client library for Google Maps API Web Services
Go
695
star
10

transport-tracker

Applications for tracking moving assets on a live map
JavaScript
565
star
11

react-wrapper

Wrap React components with this libary to load the Google Maps JavaScript API.
TypeScript
344
star
12

android-maps-ktx

Kotlin extensions (KTX) for the Maps SDK and Utility Library for Android
Kotlin
314
star
13

js-api-loader

Load the Google Maps JavaScript API script dynamically.
TypeScript
306
star
14

maps-sdk-for-ios-samples

Samples for the Google Maps and Places SDKs for iOS
Objective-C
259
star
15

android-places-demos

Google Places SDK Demos for Android
Java
167
star
16

js-markerclusterer

Create and manage clusters for large amounts of markers
TypeScript
166
star
17

js-three

Add ThreeJS objects to Google Maps.
TypeScript
134
star
18

roads-api-samples

Sample Android app demonstrating usage of the GMP Roads API
Java
116
star
19

openapi-specification

OpenAPI specification for Google Maps Platform API
TypeScript
99
star
20

js-markerclustererplus

TypeScript
97
star
21

android-places-ktx

Kotlin extensions (KTX) for the Places SDK for Android
Kotlin
96
star
22

extended-component-library

A set of Web Components from Google Maps Platform
TypeScript
95
star
23

property-finder

A turnkey solution for a fictitious real estate business
Python
75
star
24

js-markerwithlabel

Google Maps Marker with Label
TypeScript
70
star
25

deck.gl-demos

Examples showing how to use Google Maps Platform with deck.gl
JavaScript
69
star
26

last-mile-fleet-solution-samples

Java
54
star
27

js-polyline-codec

Polyline encoding and decoding.
TypeScript
51
star
28

url-signing

Samples in various languages that demonstrate how to sign URLs for Google Maps Platform Web Services APIs
HTML
42
star
29

nyc-subway-station-locator

NYC Subway Station Locator Solution
Go
31
star
30

js-jest-mocks

Jest mocks for Google Maps Platform
TypeScript
29
star
31

ios-maps-sdk

Google Maps SDK for iOS
Swift
28
star
32

python-high-volume-address-validation-library

Python
27
star
33

android-on-demand-rides-deliveries-samples

Kotlin
22
star
34

android-maps-rx

RxJava bindings for the Maps and Places SDKs for Android
Kotlin
21
star
35

gaming-services-samples

Example games that use Google Maps Platform gaming services.
C#
20
star
36

js-map-loader

A simple JavaScript/TypeScript utility for adding a Google Map to webpages programmatically.
TypeScript
18
star
37

js-typescript-guards

TypeScript guards for the Google Maps JavaScript API.
TypeScript
17
star
38

ios-on-demand-rides-deliveries-samples

Objective-C
17
star
39

fleet-debugger

JavaScript
16
star
40

js-markermanager

Marker manager is an interface between the map and the user, designed to manage adding and removing many points when the viewport changes.
TypeScript
15
star
41

on-demand-rides-deliveries-samples

14
star
42

ios-combine

Combine extensions for Maps and Places SDKs for iOS
Swift
14
star
43

js-ogc

Add a WmsMapType to Google Maps
TypeScript
12
star
44

java-on-demand-rides-deliveries-stub-provider

Java
11
star
45

android-v3-migration

Migration tool for V3 BETA Maps SDK to Google Play services Maps SDK
Kotlin
11
star
46

.github

Default configurations for googlemaps repositories
11
star
47

java-fleetengine-auth

Java
10
star
48

react-on-demand-rides-deliveries-samples

TypeScript
10
star
49

react-last-mile-fleet-solution-samples

TypeScript
10
star
50

react-routing-playground

JavaScript
9
star
51

go-routespreferred

Go idiomatic client for Google Maps Platform Routes API.
8
star
52

js-types

Automatically generated types for the Google Maps Platform JavaScript API
Starlark
7
star
53

angular-on-demand-rides-deliveries-samples

TypeScript
6
star
54

js-url-signature

Sign a URL for Google Maps Platform requests.
TypeScript
6
star
55

semantic-release-config

Shareable configuration for semantic release.
JavaScript
5
star
56

gmp-firebase-extensions

TypeScript
5
star
57

codelab-maps-platform-101-swift

Companion code for the Add a map to your iOS app (Swift) codelab
Swift
5
star
58

fleet-events-reference-solution

Java
5
star
59

js-adv-markers-utils

TypeScript
4
star
60

codelab-places-101-android-kotlin

Companion code for the Get started with the Places SDK for Android (Kotlin) codelab
Kotlin
4
star
61

playablelocations-proxy

A proxy implementation for the Playable Locations API.
Go
4
star
62

eslint-plugin-googlemaps

ESLint rules for Google Maps Platform.
TypeScript
4
star
63

js-region-lookup

TypeScript
4
star
64

ios-places-sdk

Swift
4
star
65

js-github-policy-bot

Enforce polices for repositories in the googlemaps organization.
TypeScript
2
star
66

go-routespreferred-samples

Routes Preferred Samples in Go
Go
2
star
67

googlemaps.github.io

A page listing Google maintained GMP libraries as well as external ones.
HTML
2
star
68

java-routespreferred-samples

Samples for Routes Preferred
Java
2
star
69

eslint-config-googlemaps

Shareable ESLint style configuration for Google Maps repositories.
TypeScript
1
star
70

ios-consumer-sdk

Swift
1
star
71

ios-navigation-sdk

Swift
1
star
72

java-routespreferred

Java idiomatic client for Google Maps Platform Routes Preferred API.
Java
1
star
73

.allstar

1
star