GroundOverlay composable added to composition tree but does not render on map

[DOTNETTMiller]

Bug Report: GroundOverlay Composable Not Rendering

For: https://github.com/googlemaps/android-maps-compose/issues

---

Title

GroundOverlay composable added to composition tree but does not render on map

Description

The GroundOverlay composable is successfully added to the composition tree (confirmed via logs and no exceptions) but does not display on the Google Map. All parameters are correct, the bitmap is valid, and other map composables (Markers, Polylines) render correctly.

Environment

• Library Version: maps-compose (latest as of January 2026)
• Android Version: API 33
• Device: Google Pixel 4
• Maps SDK: Android Maps SDK via Compose
• Compose Version: Latest stable

Expected Behavior

The GroundOverlay should display a semi-transparent PDF image (rendered to bitmap) at the specified LatLngBounds on the map, similar to how it works in the traditional XML/View-based Google Maps API.

Actual Behavior

The GroundOverlay composable is added to the composition tree but nothing displays on the map. No exceptions are thrown, no errors logged. Other map elements (Polyline, Marker) render correctly.

Code Sample

@Composable
fun PDFOverlayScreen() {
    val overlayBitmap: Bitmap? = ... // 1200x1600px bitmap, valid

    GoogleMap(
        modifier = Modifier.fillMaxSize(),
        cameraPositionState = cameraPositionState,
        properties = MapProperties(mapType = MapType.SATELLITE)
    ) {
        // This renders correctly ✅
        Polyline(
            points = listOf(
                LatLng(41.629, -93.787),
                LatLng(41.629, -93.778)
            ),
            color = Color.Red,
            width = 20f,
            visible = true,
            zIndex = 5f
        )

        // This renders correctly ✅
        Marker(
            state = MarkerState(position = LatLng(41.629, -93.784)),
            title = "Test Marker"
        )

        // This does NOT render ❌
        if (overlayBitmap != null) {
            GroundOverlay(
                position = GroundOverlayPosition.create(
                    LatLngBounds(
                        LatLng(41.628, -93.785),  // SW corner
                        LatLng(41.630, -93.782)   // NE corner
                    )
                ),
                image = BitmapDescriptorFactory.fromBitmap(overlayBitmap),
                transparency = 0.3f,  // 70% opaque
                bearing = 0f,
                clickable = false,
                visible = true,
                zIndex = 10f
            )
        }
    }
}

Logs

D/PDFOverlay: bitmap size=1200x1600
D/PDFOverlay: visible=true, transparency=0.3
D/PDFOverlay: Rendering PDF overlay: SW=(41.628,-93.785) NE=(41.630,-93.782)
D/PDFOverlay: GroundOverlay composable added to tree

No errors, no exceptions. The composable is in the tree but not rendering.

What I've Tried

1. ✅ Set zIndex = 10f - No effect
2. ✅ Set visible = true explicitly - No effect
3. ✅ Reduced transparency to 0.3f (70% opaque) - No effect
4. ✅ Removed rotation (bearing = 0f) - No effect
5. ✅ Increased size to 1000 feet - No effect
6. ✅ Disabled buildings (isBuildingEnabled = false) - No effect
7. ✅ Tested on both NORMAL and SATELLITE map types - No effect
8. ✅ Verified bitmap is valid (not null, correct size) - Bitmap is fine
9. ✅ Created bright red Polyline as test - Polyline renders correctly
10. ✅ Created Marker as test - Marker renders correctly

Conclusion: Polylines and Markers work, GroundOverlay does not.

Comparison with Traditional API

The same code using the traditional XML/View-based Google Maps API with GoogleMap.addGroundOverlay() works perfectly:

// This works in traditional API
val overlay = googleMap.addGroundOverlay(
    GroundOverlayOptions()
        .image(BitmapDescriptorFactory.fromBitmap(bitmap))
        .positionFromBounds(bounds)
        .transparency(0.3f)
        .zIndex(10f)
)
// Overlay displays correctly ✅

But the Compose version does not render at all.

Related Issues

• Ability to render GroundOverlays on top of map content such as buildings #526 - GroundOverlays render below map content (different issue - that one renders but z-order wrong, this one doesn't render at all)
• GroundOverlayPosition() freezes app sometimes #378 - GroundOverlayPosition freezes app (different issue - this doesn't freeze, just doesn't render)

Impact

This blocks a production feature where users need to overlay DOT traffic control plan PDFs on the map for reference during work zone setup. The feature works perfectly in iOS (SwiftUI MapKit) but is completely non-functional in Android due to this bug.

Workaround

None found. Only solution is to rewrite entire screen using XML/Fragment views instead of Compose, which breaks the app's Compose-first architecture.

Suspected Root Cause

The GroundOverlay composable may not be properly triggering the underlying Google Maps SDK's addGroundOverlay() call, or there's a disconnect between the Compose state and the actual map rendering.

Request

Please fix GroundOverlay rendering in maps-compose, or provide guidance if there's a known workaround. This is a blocker for production use.

---

System Info

• Gradle: 8.x
• Kotlin: Latest stable
• Compose: Latest stable
• Maps Compose: Latest from Maven

Reproduction

Can provide full reproduction repository if needed.

[kikoso]

Hi @DOTNETTMiller . This seems to be due to the fact that the GroundOverlayPosition is not a data class and is not recomposing.

We are working on this. We will commit a PR with a sample and a fix. Thanks for reporting it.

[kikoso]

@DOTNETTMiller , I have a potential fix with an example showcasing the implementation here.

Would you be able to provide a sample repo, to check it with your implementation?