[google_maps_flutter] Add background color for unloaded tiles by RyanHolanda · Pull Request #12357 · flutter/packages

RyanHolanda · 2026-08-04T03:10:46Z

Adds a nullable GoogleMap.backgroundColor option for configuring the color displayed behind map tiles while they are not fully loaded.

This prevents the native map surface from showing its default black background before tiles render. The value is forwarded during map initialization to:

Android's GoogleMapOptions.backgroundColor.
iOS's GMSMapViewOptions.backgroundColor in the default, SDK 9, and SDK 10 implementations.
Web's JavaScript MapOptions.backgroundColor.

The existing SDK defaults remain unchanged when backgroundColor is null. Since the native options are initialization-time settings, changing the value after map creation has no effect.

No screenshots are included because this is an API-only platform integration change.

Fixes flutter/flutter#142520

Federated review note

This is the required combined-review PR for the federated plugin change. It intentionally contains repository-generated path dependency overrides marked DO NOT MERGE so the platform interface, implementations, and app-facing package can be reviewed and tested together.

The package publish dry-run passes for all seven packages. The federation safety check intentionally reports Unresolved combo PR, preventing this combined review branch from landing accidentally. Once the overall change is approved, it will be split and landed in dependency order:

Platform interface.
Android, iOS, and web implementations.
App-facing package after the preceding releases are published.

Test coverage

The change adds coverage for:

App-facing configuration forwarding.
Platform-interface diffing, equality, hashing, and legacy serialization.
Android Dart-to-Pigeon conversion and native creation options.
iOS Dart-to-Pigeon conversion and native GMSMapViewOptions creation across all maintained SDK implementations.
Web conversion to the JavaScript map creation options, including alpha.

Local validation completed:

Repository formatter: passed.
Dart analysis and tests for all seven packages: passed.
Android Gradle lint and native unit tests: passed.
iOS SDK 9 and SDK 10 analysis and native tests: passed (72 tests each).
iOS shared-source synchronization validator: passed.
Web integration tests against the latest and minimum supported Flutter versions: passed.
Package validation, license validation, and publish dry-runs: passed.

On the local Xcode 26.5 installation, the default CocoaPods native target is blocked before plugin tests by warnings promoted to errors in the third-party Google-Maps-iOS-Utils source. The identical shared implementation passes in the SDK 9 and SDK 10 targets; hosted CI will validate the repository's supported CocoaPods environment.

Pre-Review Checklist

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Note: The Flutter team is currently trialing the use of Gemini Code Assist for GitHub. Comments from the gemini-code-assist bot should not be taken as authoritative feedback from the Flutter team. If you find its comments useful you can update your code accordingly, but if you are unsure or disagree with the feedback, please feel free to wait for a Flutter team member's review for guidance on which automated comments should be addressed.

Regular contributors who have demonstrated familiarity with the repository guidelines only need to comment if the PR is not auto-exempted by repo tooling. ↩ ↩²

gemini-code-assist

Code Review

This pull request introduces a backgroundColor option to GoogleMap to configure the color displayed behind unloaded map tiles. This change is implemented across the main package, the platform interface, and the Android, iOS, and Web platform implementations, along with corresponding tests. There are no review comments, and I have no feedback to provide.

stuartmorgan-g

Overall the structure looks good, thanks for the contribution!

Routing to platform teams for in-depth review of platform implementations before the PR is split apart.

stuartmorgan-g · 2026-08-10T17:21:35Z

    style: config.style,
+    backgroundColor: config.backgroundColor == null
+        ? null
+        : PlatformColor(argbValue: config.backgroundColor!.toARGB32()),


Prefer creating a local backgroundColor variable and using that, so that you can rely on compiler-enforced autopromotion instead of force-unwrapping.

Fixed in d318693. I now store config.backgroundColor in a local Color? and use the promoted local for the conversion, removing the force unwrap.

stuartmorgan-g · 2026-08-10T17:21:52Z

    style: options['style'] as String?,
+    backgroundColor: options['backgroundColor'] == null
+        ? null
+        : PlatformColor(argbValue: options['backgroundColor']! as int),


Fixed in d318693. The legacy options path now stores options["backgroundColor"] in a local int? and uses compiler promotion instead of force-unwrapping the map lookup.

stuartmorgan-g · 2026-08-10T17:25:32Z

    style: config.style,
+    backgroundColor: config.backgroundColor == null
+        ? null
+        : _platformColorFromColor(config.backgroundColor!),


Same notes here as for Android.

Fixed in d318693. I applied the same promoted-local pattern to both analogous iOS conversion paths. Android/iOS analysis and all package and example Dart tests pass.

mdebbar

The web changes are straightforward and look good to me!

vashworth

iOS side LGTM

flutter-dashboard · 2026-08-25T15:32:21Z

This pull request is not mergeable in its current state, likely because of a merge conflict. Pre-submit CI jobs were not triggered. Pushing a new commit to this branch that resolves the issue will result in pre-submit jobs being scheduled.

vashworth · 2026-08-25T15:33:29Z

@RyanHolanda Can you resolve the merge conflicts so we can get the tests to run?

RyanHolanda · 2026-08-25T15:41:13Z

@vashworth Resolved, thanks! I rebased the PR onto the current main and kept both the upstream 2.16.1 release entry and this PR’s 2.17.0 entry. The PR is mergeable now and fresh CI checks are queued.

Locally, all seven affected packages pass analyze, dart-test, validate, and publish-check.

RyanHolanda · 2026-08-25T19:30:57Z

Resolved again. The new conflicts came from #12307 converting the maintained SDK9/SDK10/shared iOS controller code to Swift; that upstream change did not duplicate this PR’s backgroundColor feature.

I rebased onto current main and ported only this PR’s iOS initialization to the new Swift GoogleMapController: GMSMapViewOptions.backgroundColor is set from the creation configuration before constructing GMSMapView. I also added the equivalent Swift test, updated the generated-code paths for the new _objc targets, and left the frozen legacy iOS implementation in Objective-C.

Validation passes for all affected packages (analyze, dart-test, validate, and publish-check), shared SDK source synchronization passes, and the SDK10 GoogleMapsTests suite ran on a physical iPhone on iOS 26.6: 9/9 passed, including mapViewOptionsUseConfiguredBackgroundColor().

@vashworth Could you please take another look?

RyanHolanda · 2026-10-08T23:09:41Z

@LouiseHsu Thanks for the heads-up! I rebased the PR onto the latest main and resolved the conflicts; GitHub now marks it as mergeable. The platform-interface changes from #13014 are already in main, so they no longer appear in this PR diff. I also reran the relevant checks. Please let me know if anything else needs adjustment! 🙂

mdebbar

Web changes still look good.

auto-submit · 2026-10-16T19:04:47Z

autosubmit label was removed for flutter/packages/12357, because - The status or check suite Dashboard Checks has failed. Please fix the issues identified (or deflake) before re-applying this label.

LongCatIsLooong · 2026-10-16T22:54:16Z

The following packages had errors:
packages/google_maps_flutter/google_maps_flutter:
Missing version change

LongCatIsLooong · 2026-10-23T18:16:01Z

Hi @RyanHolanda could you update the versions of the package following https://github.com/flutter/flutter/blob/master/docs/ecosystem/contributing/README.md#version-and-changelog-updates? I think the CI is failing because of that.

…ackground-color

RyanHolanda · 2026-10-23T20:01:02Z

@LongCatIsLooong Thanks for catching this! google_maps_flutter was still at 2.19.0, which is already on main. I bumped it to 2.20.0 and moved the backgroundColor CHANGELOG entry under that release, then merged the latest main and reconciled the web CHANGELOG.

hellohuanlin · 2026-10-29T21:39:32Z

@RyanHolanda FYI this is failing CI with: "DO NOT MERGE" found in pubspec.yaml

RyanHolanda · 2026-10-30T13:01:31Z

@hellohuanlin Thanks for flagging this. The DO NOT MERGE comments and path-based dependency overrides are intentional in this combined federated review PR, following the federated plugin contribution workflow. They prevent the combined PR from landing before its packages are split in dependency order.

The interface-only PR #13014 has merged, but google_maps_flutter_platform_interface 2.18.0 is not yet published on pub.dev (2.17.0 is still the latest). Could a maintainer publish 2.18.0 or advise on the release timing? Once it is available, I can proceed with the implementation-only landing PR, then reduce this PR to the app-facing change after those implementations are published. I will leave the safety overrides in place until the corresponding published dependencies are available.

cbracken · 2026-11-05T22:58:35Z

@tarrinneal @bparrishMines for maps owners to publish 2.18.0

github-actions Bot added p: google_maps_flutter platform-android platform-ios platform-web labels Aug 4, 2026

gemini-code-assist Bot reviewed Aug 4, 2026

View reviewed changes

stuartmorgan-g self-requested a review August 4, 2026 20:53

stuartmorgan-g reviewed Aug 10, 2026

View reviewed changes

stuartmorgan-g added the CICD Run CI/CD label Aug 10, 2026

stuartmorgan-g requested review from LongCatIsLooong, mdebbar, reidbaker and vashworth August 10, 2026 17:28

stuartmorgan-g added triage-ios Should be looked at in iOS triage triage-android Should be looked at in Android triage triage-web Should be looked at in web triage labels Aug 10, 2026

mdebbar reviewed Aug 13, 2026

View reviewed changes

mdebbar approved these changes Aug 13, 2026

View reviewed changes

flutter-dashboard Bot removed the CICD Run CI/CD label Aug 13, 2026

RyanHolanda force-pushed the codex/google-maps-background-color branch 2 times, most recently from aa96f6f to dffba86 Compare August 13, 2026 21:51

vashworth approved these changes Aug 25, 2026

View reviewed changes

vashworth added the CICD Run CI/CD label Aug 25, 2026

RyanHolanda force-pushed the codex/google-maps-background-color branch from d318693 to b0ef5a7 Compare August 25, 2026 15:41

flutter-dashboard Bot removed the CICD Run CI/CD label Aug 25, 2026

RyanHolanda force-pushed the codex/google-maps-background-color branch from b0ef5a7 to 28d6755 Compare August 25, 2026 19:30

vashworth added the CICD Run CI/CD label Aug 27, 2026

RyanHolanda added 4 commits October 8, 2026 20:02

Address background color review feedback

19f3802

[google_maps_flutter_android] Test null background color

3d19b0e

[google_maps_flutter_android] Document background color integer format

d19bf20

[google_maps_flutter_android] Simplify background color documentation

d8fbe63

RyanHolanda force-pushed the codex/google-maps-background-color branch from c2ff6a5 to d8fbe63 Compare October 8, 2026 23:09

mdebbar approved these changes Oct 12, 2026

View reviewed changes

vashworth added the CICD Run CI/CD label Oct 14, 2026

Merge branch 'main' into codex/google-maps-background-color

77eef2c

flutter-dashboard Bot removed the CICD Run CI/CD label Oct 16, 2026

mdebbar added CICD Run CI/CD autosubmit Merge PR when tree becomes green via auto submit App labels Oct 16, 2026

auto-submit Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Oct 16, 2026

Merge remote-tracking branch 'upstream/main' into codex/google-maps-b…

b167eae

…ackground-color

flutter-dashboard Bot removed the CICD Run CI/CD label Oct 23, 2026

LongCatIsLooong added the CICD Run CI/CD label Oct 23, 2026

Merge branch 'main' into codex/google-maps-background-color

fe98d73

flutter-dashboard Bot removed the CICD Run CI/CD label Nov 4, 2026

flutter-zl added the CICD Run CI/CD label Nov 4, 2026

Merge branch 'main' into codex/google-maps-background-color

1c41cb3

flutter-dashboard Bot removed the CICD Run CI/CD label Nov 4, 2026

cbracken requested review from bparrishMines and tarrinneal November 5, 2026 22:58

Conversation

RyanHolanda commented Aug 4, 2026

Federated review note

Test coverage

Pre-Review Checklist

Footnotes

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

stuartmorgan-g left a comment

Choose a reason for hiding this comment

Uh oh!

stuartmorgan-g Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

RyanHolanda Aug 13, 2026

Choose a reason for hiding this comment

Uh oh!

stuartmorgan-g Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

RyanHolanda Aug 13, 2026

Choose a reason for hiding this comment

Uh oh!

stuartmorgan-g Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

RyanHolanda Aug 13, 2026

Choose a reason for hiding this comment

Uh oh!

mdebbar left a comment

Choose a reason for hiding this comment

Uh oh!

vashworth left a comment

Choose a reason for hiding this comment

Uh oh!

flutter-dashboard Bot commented Aug 25, 2026

Uh oh!

vashworth commented Aug 25, 2026

Uh oh!

RyanHolanda commented Aug 25, 2026

Uh oh!

RyanHolanda commented Aug 25, 2026

Uh oh!

RyanHolanda commented Oct 8, 2026

Uh oh!

mdebbar left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

auto-submit Bot commented Oct 16, 2026

Uh oh!

LongCatIsLooong commented Oct 16, 2026

Uh oh!

LongCatIsLooong commented Oct 23, 2026

Uh oh!

RyanHolanda commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hellohuanlin commented Oct 29, 2026

Uh oh!

RyanHolanda commented Oct 30, 2026

Uh oh!

cbracken commented Nov 5, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

11 participants

mdebbar left a comment •

edited

Loading

RyanHolanda commented Oct 23, 2026 •

edited

Loading