kmp-maps-compose
0.6.0indexedUnified Google Maps Compose API providing map display, markers, shapes, camera control, custom icons, composable info windows, and smooth camera animations.
33
Stars
—
Used by
dependents
27
Health
/ 100
Maps Compose Multiplatform
A Kotlin Compose Multiplatform library providing Google Maps integration for Android and iOS with a unified API. Designed as a drop-in multiplatform replacement for android-maps-compose.
Installation
Add the dependency to your build.gradle.kts:
kotlin {
sourceSets {
commonMain.dependencies {
implementation("eu.buney.maps:kmp-maps-compose:0.6.0")
// Optional: clustering utilities
implementation("eu.buney.maps:kmp-maps-compose-utils:0.6.0")
}
}
}
API Key Setup
Get a Google Maps API key from Google Cloud Console.
Each platform requires the API key to be configured differently:
- Android: Add a
<meta-data>entry in yourAndroidManifest.xml - iOS: Call
GMSServices.provideAPIKey(key)before using maps
Example using BuildKonfig
BuildKonfig is a convenient way to manage secrets in KMP projects. Here's a complete setup:
1. Add BuildKonfig plugin to your app's build.gradle.kts:
plugins {
// ...
id("com.codingfeline.buildkonfig") version "0.15.1"
}
2. Create secrets.properties in your project root (add to .gitignore):
MAPS_API_KEY=your_api_key_here
3. Configure BuildKonfig and Android manifest in your app's build.gradle.kts:
import java.util.Properties
// load secrets
val secretsFile = rootProject.file("secrets.properties")
val secrets = Properties().apply {
if (secretsFile.exists()) load(secretsFile.inputStream())
}
val mapsApiKey = secrets.getProperty("MAPS_API_KEY", "")
android {
defaultConfig {
// make key available in AndroidManifest.xml as ${MAPS_API_KEY}
manifestPlaceholders["MAPS_API_KEY"] = mapsApiKey
}
}
buildkonfig {
packageName = "com.example.myapp"
defaultConfigs {
buildConfigField(STRING, , mapsApiKey)
}
}
4. Add to AndroidManifest.xml:
<application>
<meta-data
android:name="com.google.android.geo.API_KEY"
android:value="${MAPS_API_KEY}" />
</application>
5. Initialize iOS in your MainViewController.kt:
import GoogleMaps.GMSServices
fun MainViewController() = ComposeUIViewController(
configure = {
GMSServices.provideAPIKey(BuildKonfig.MAPS_API_KEY)
}
) {
App()
}
iOS SDK Setup
The iOS app requires the Google Maps iOS SDK to be linked. There are two ways to set this up:
Option 1: Use the exported bridge package (Recommended)
Add kmp-maps-compose/exportedGoogleMapsBridge as a local Swift Package in your Xcode project:
- In Xcode, go to File → Add Package Dependencies...
- Click Add Local...
- Navigate to
kmp-maps-compose/exportedGoogleMapsBridgeand add it
This bridge package is auto-generated by the spm4kmp plugin and ensures version consistency between the SDK version expected by the library and what gets linked into your app.
Option 2: Add Google Maps iOS SDK directly
Add the SDK via SPM in your Xcode project:
- In Xcode, go to File → Add Package Dependencies...
- Enter:
https://github.com/googlemaps/ios-maps-sdk - Select the version matching what the library expects (check
exportedGoogleMapsBridge/Package.swiftfor the exact version)
Note: With this approach, you're responsible for keeping the SDK version in sync with library updates.
Quick Start
import eu.buney.maps.*
@Composable
fun MapScreen() {
val cameraPositionState = rememberCameraPositionState {
position = CameraPosition(
target = LatLng(, -),
zoom =
)
}
GoogleMap(
modifier = Modifier.fillMaxSize(),
cameraPositionState = cameraPositionState,
properties = MapProperties(mapType = MapType.NORMAL),
uiSettings = MapUiSettings(zoomControlsEnabled = ),
onMapClick = { latLng -> println() }
) {
Marker(
state = rememberUpdatedMarkerState(position = LatLng(, -)),
title = ,
snippet =
)
}
}
Features
Map Display
GoogleMap(
modifier = Modifier.fillMaxSize(),
cameraPositionState = rememberCameraPositionState(),
properties = MapProperties(
mapType = MapType.HYBRID,
isTrafficEnabled = true,
isBuildingEnabled = true
),
uiSettings = MapUiSettings(
compassEnabled = true,
rotationGesturesEnabled = true
),
contentPadding = PaddingValues(bottom = 80.dp),
onMapClick = { latLng -> /* handle click */ },
onMapLongClick = { latLng -> /* handle long click */ },
onPOIClick = { poi -> /* handle POI click */ },
onMapLoaded = { /* map ready */ }
) {
// add markers, polylines, etc.
}
Markers
// basic marker
Marker(
state = rememberUpdatedMarkerState(position = LatLng(, -)),
title = ,
snippet = ,
alpha = ,
rotation = ,
draggable = ,
onClick = { marker -> }
)
MarkerInfoWindow(
state = rememberUpdatedMarkerState(position = latLng),
onClick = { }
) { marker ->
Column(
modifier = Modifier.background(Color.White).padding(dp)
) {
Text(, fontWeight = FontWeight.Bold)
Text()
}
}
MarkerComposable(
keys = arrayOf(count),
state = rememberUpdatedMarkerState(position = latLng)
) {
Box(
modifier = Modifier
.size(dp)
.background(Color.Red, CircleShape),
contentAlignment = Alignment.Center
) {
Text(, color = Color.White)
}
}
Shapes
Camera Control
val cameraPositionState = rememberCameraPositionState()
// animate to position
LaunchedEffect(targetLocation) {
cameraPositionState.animate(
CameraPosition(target = targetLocation, zoom = 15f),
durationMs = 1000
)
}
// animate to bounds
LaunchedEffect(markers) {
val bounds = LatLngBounds.Builder().apply {
markers.forEach { include(it.position) }
}.build()
cameraPositionState.animate(CameraUpdateFactory.newLatLngBounds(bounds, 100))
}
// instant move
cameraPositionState.move(CameraUpdateFactory.newCameraPosition(CameraPosition(target = latLng, zoom = )))
(cameraPositionState.isMoving) {
}
Custom Marker Icons
// from Compose Resources (recommended)
val icon = rememberBitmapDescriptor(Res.drawable.my_marker)
// from PNG/JPEG bytes
val icon = BitmapDescriptorFactory.fromEncodedImage(imageBytes)
// from Compose content (rendered to bitmap)
val icon = rememberComposeBitmapDescriptor(key1, key2) {
Icon(Icons.Default.Place, contentDescription = null, tint = Color.Red)
}
Marker(
state = markerState,
icon = icon
)
Feature Parity with android-maps-compose
This table shows feature compatibility between android-maps-compose and this library.
Core Map Features
Camera
Markers
Shapes & Overlays
Advanced Features
Legend: Yes = Supported | Partial = See notes | No = Not supported
iOS-Specific Notes
- Uses Google Maps iOS SDK via Swift Package Manager
- Some styling features not supported by iOS SDK:
- Polyline/polygon stroke patterns
- Line caps and joint types
- Map toolbar and zoom controls
- TERRAIN map type falls back to NORMAL
- Z-index values are truncated to integers
- Custom info window Compose content rendered as bitmap
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.