Skip to content

feat: show a background grid while map tiles load - #2259

Open
ben-milanko wants to merge 3 commits into
fleaflet:masterfrom
ben-milanko:codex/loading-grid
Open

ben-milanko wants to merge 3 commits into
fleaflet:masterfrom
ben-milanko:codex/loading-grid

Conversation

@ben-milanko

Copy link
Copy Markdown
Contributor

Empty map areas currently show a flat background while tiles load. Add a subtle grid beneath all map layers, enabled by default with 64 logical pixel cells at integer zoom levels. It follows panning, zooming, and rotation, and opaque tiles cover it as they fade in. Existing fallback tiles continue to cover the grid while replacement tiles load.

Loading grid behind partially rendered map tiles

Expose MapOptions.backgroundGridColor and MapOptions.backgroundGridSpacing for customization. Setting backgroundGridColor: null restores the plain background. Fully transparent map backgrounds remain transparent. When disabled, the background uses the existing plain ColoredBox without a grid painter or camera dependency.

This intentionally changes the default map appearance. The grid is a background decoration, so it also remains visible through transparent tiles and in areas without tiles. The Tile Builder example includes a toggle, and the API documentation describes these behaviors.

Validation:

  • All 148 tests pass on the clean upstream-based branch, including 8 new tests for rendered grid pixels, partial loading, fade-in, fallback tiles, camera movement, customization, transparency, and gestures.
  • Analysis passes for the library, tests, and example page; formatting checks pass for all changed Dart files.
  • Tested with Flutter 3.41.9 / Dart 3.11.5. Minimum-supported-SDK validation remains for CI.

Developed and checked with OpenAI Codex; the validation listed above ran locally.

@JaffaKetchup JaffaKetchup left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hey, thanks for contributing! There are a few things to follow up on, but overall I think this is a nice addition.

(For completeness, it might be worth mentioning the old plugin which added a latlng grid layer, but that's a different purpose and also isn't updated to the latest versions, so it's mostly irrelevant here.)

Comment thread example/lib/pages/tile_builder.dart Outdated
Comment thread lib/src/map/options/options.dart Outdated
Comment thread lib/src/map/background.dart Outdated
Comment thread lib/src/map/background.dart Outdated
Comment thread README.md Outdated
Automatically compute grid color based on background color
Add more customisation options to grid
Remove over-the-top test suite
@JaffaKetchup

Copy link
Copy Markdown
Member

Hey @ben-milanko, I've made some fixes to the above requests, and also some other improvements. However, I don't seem to be able to push these to the PR/branch. Could you please check that you've checked the box allowing maintainers to make changes? If you're not happy to do this, let me know and I'll open a new PR and cherry pick your commit across to that.

@JaffaKetchup

Copy link
Copy Markdown
Member

Hey @ben-milanko, sorry for the ping and hope you're all good. Just pinging to see if you'd be able to allow maintainers to edit this PR? If not, no problem, and I'll cherry pick your commit into a new PR so I can add my edits on top.

@ben-milanko

Copy link
Copy Markdown
Contributor Author

Hey @JaffaKetchup sorry for the delay, just ticked the box now.

@JaffaKetchup

JaffaKetchup commented Oct 8, 2026 •

Copy link
Copy Markdown
Member

The changes I've made include auto-colouring, addition of minor strokes, and the option to use static or moving grid. It also is now an independent layer added automatically, but can be added anywhere in the stack.

image image image image

@JaffaKetchup
JaffaKetchup requested a review from a team October 8, 2026 22:09
@JaffaKetchup
JaffaKetchup dismissed their stale review October 8, 2026 22:10

Concerns addressed, as I am now a significant contributor to this PR I would like another maintainer to review

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants