Add warning when there is a widget with color between Material and ListTile#181402
Merged
auto-submit[bot] merged 10 commits intoflutter:masterfrom Mar 3, 2026
Conversation
github-actions
bot
added
framework
9 tasks
![gemini-code-assist[bot]](proxy.php?url=https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Code Review
This pull request introduces a valuable debug-time assertion in ListTile to warn developers when a non-transparent widget is placed between ListTile and its Material ancestor. This is a common pitfall that can hide ink splashes and background colors, and this assertion will significantly improve the developer experience by catching such issues early. The changes also include necessary adjustments to existing tests and new tests to validate the new assertion logic. The code changes are well-implemented and follow Flutter's best practices.
dkwingsmt
approved these changes
Jan 27, 2026
| @override | ||
| Widget build(BuildContext context) { | ||
| assert(debugCheckHasMaterial(context)); | ||
| if (onTap != null || |
Contributor
There was a problem hiding this comment.
I get the onTap and onLongPress part, since the inkwell only works with these enabled. The condition with tile colors isn't that obvious, since it's more like a rewrite of _tileBackgroundColor. Can you compute _tileBackgroundColor first, then use the resultant color for this assertion?
Contributor
Author
There was a problem hiding this comment.
Oh it makes sense. I was only considering the widget properties that are related to the tile background color might also get impacted but forgot about the non-transparent background color from themes. Updated the check!
| ErrorHint( | ||
| 'To fix this, wrap the ListTile in its own Material widget, ' | ||
| 'or remove the background color from the intermediate ${intermediateWidget.runtimeType}.', | ||
| ), |
Contributor
There was a problem hiding this comment.
Append detail of the intermediateWidget to the error so that it's easier for developers to debug?
Contributor
Author
There was a problem hiding this comment.
I thought about this but not sure how we can get the "real" widget in the error message. For example, if we have Container(color: xxx), the widget I can find is ColoredBox inside of Container, but I'm not sure how we can find the Container😅. Any suggestions?
Contributor
There was a problem hiding this comment.
Without making the PR too complicated, shall we simply describe the two widgets with DiagnosticsProperty here, which should be somewhat useful at least?
Contributor
Author
There was a problem hiding this comment.
That makes sense. Updated! Thanks!
Comment on lines
+4776
to
+4777
| height: | ||
| 200, // This is to remove the lint on Container. Otherwise, linter suggests to use ColoredBox instead. |
Contributor
There was a problem hiding this comment.
Suggested change
| height: | |
| 200, // This is to remove the lint on Container. Otherwise, linter suggests to use ColoredBox instead. | |
| // Specify a height remove the lint on Container. Otherwise, linter suggests to use ColoredBox instead. | |
| height: 200, |
| // are visible. A DecoratedBox with a non-transparent color will hide the | ||
| // background color or ink splashes of the ListTile. | ||
| if (backgroundColor.a > 0) { | ||
| tile = Material(type: MaterialType.transparency, child: tile); |
Contributor
There was a problem hiding this comment.
This actually fixes a bug of ExpansionTile, which didn't show inkwell splashes with opaque backgroundColor. Maybe you can try to write a test for it, although I'm not sure if there's a meaningful way.
Contributor
Author
There was a problem hiding this comment.
I spent some time on the ink splash effect but noticed we can verify this by checking its focused color and hovered color! Added tests:)
dkwingsmt
reviewed
Feb 1, 2026
| final ListTileThemeData defaults = theme.useMaterial3 | ||
| ? _LisTileDefaultsM3(context) | ||
| : _LisTileDefaultsM2(context, listTileStyle); | ||
| final Color tileBackgroundColor = _tileBackgroundColor(theme, tileTheme, defaults); |
Contributor
There was a problem hiding this comment.
On another thought, maybe we should just check if either tileColor and selectedTileColor is true regardless of selected, since this allows the error to popup without actually selecting any, and the tile is expected to be selected at some time anyway.
Contributor
Author
There was a problem hiding this comment.
Updated:) Thanks!
Contributor
|
@QuncCccccc There are some Google testing failures |
Contributor
Author
|
Fixed all failures in cl/862031140. Waiting for approvals for the CL. The CL can be submitted first and then this PR. |
Contributor
|
(from triage) How's the CL going? |
Contributor
Author
|
It's on my radar. The CL still needs one more approval. |
QuncCccccc
force-pushed
the
add_warning_when_widget_with_color_wrap_list_tile
branch
from
f9ba69c to
15d6ab1
Compare
4 tasks
Contributor
Author
|
The CL has been approved and submitted. ListTile is a common widget that developers will use, so I created a migration guide for this change: flutter/website#13131 |
Contributor
Author
|
Seems I missed to handle one more failure. Created cl/877638422. |
sfshaza2
added a commit
to flutter/website
that referenced
this pull request
Mar 3, 2026
This PR is to add a breaking change page for flutter/flutter#181402 ## Presubmit checklist - [x] If you are unwilling, or unable, to sign the CLA, even for a _tiny_, one-word PR, please file an issue instead of a PR. - [x] If this PR is not meant to land until a future stable release, mark it as draft with an explanation. - [x] This PR follows the [Google Developer Documentation Style Guidelines](https://developers.google.com/style)—for example, it doesn't use _i.e._ or _e.g._, and it avoids _I_ and _we_ (first-person pronouns). - [x] This PR uses [semantic line breaks](https://github.com/dart-lang/site-shared/blob/main/doc/writing-for-dart-and-flutter-websites.md#semantic-line-breaks) of 80 characters or fewer. --------- Co-authored-by: Shams Zakhour <[email protected]> Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
QuncCccccc
added
the
autosubmit
flutter-dashboard
bot
removed
the
autosubmit
|
Thank you @QuncCccccc ! |
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Mar 4, 2026
…rial` and `ListTile` (flutter/flutter#181402)
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Mar 4, 2026
…rial` and `ListTile` (flutter/flutter#181402)
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Mar 4, 2026
…rial` and `ListTile` (flutter/flutter#181402)
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Mar 4, 2026
…rial` and `ListTile` (flutter/flutter#181402)
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Mar 4, 2026
…rial` and `ListTile` (flutter/flutter#181402)
This was referenced Mar 4, 2026
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Mar 4, 2026
…rial` and `ListTile` (flutter/flutter#181402)
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Mar 5, 2026
…rial` and `ListTile` (flutter/flutter#181402)
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Mar 5, 2026
…rial` and `ListTile` (flutter/flutter#181402)
This was referenced Mar 5, 2026
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Mar 5, 2026
…rial` and `ListTile` (flutter/flutter#181402)
engine-flutter-autoroll
added a commit
to engine-flutter-autoroll/packages
that referenced
this pull request
Mar 5, 2026
…rial` and `ListTile` (flutter/flutter#181402)
auto-submit bot
pushed a commit
to flutter/packages
that referenced
this pull request
Mar 5, 2026
Roll Flutter from 46fb7210422d to d3dd7744e81f (33 revisions) flutter/flutter@46fb721...d3dd774 2026-03-04 [email protected] Show warning when plugins do not support SwiftPM (flutter/flutter#182506) 2026-03-04 [email protected] Give guided message when project is not compatible with SwiftPM (flutter/flutter#182394) 2026-03-04 [email protected] Pass --web-define through to web runner when using --machine mode (flutter/flutter#183228) 2026-03-04 [email protected] Improve SwiftPM minimum platform mismatch diagnostics (flutter/flutter#182375) 2026-03-04 [email protected] Use dart::bin::SetupDartIo to setup dart:io (flutter/flutter#176714) 2026-03-04 [email protected] Roll Skia from 3197848b14ad to ada0b7628c79 (5 revisions) (flutter/flutter#183221) 2026-03-04 [email protected] Roll Skia from fe9e9f22c531 to 3197848b14ad (15 revisions) (flutter/flutter#183198) 2026-03-04 [email protected] refactor: remove material in reorderable_list_test, scroll_notification_test, scroll_physics_test, shortcuts_test, sliver_floating_header_test, snapshot_widget_test (flutter/flutter#182698) 2026-03-04 [email protected] refactor: remove material in pop_scope_test, route_notification_message_test, two_dimensional_utils, two_dimensional_viewport_test (flutter/flutter#182699) 2026-03-04 [email protected] Add dev/benchmarks/README.md (flutter/flutter#182976) 2026-03-03 [email protected] Roll RapidJSON to a branch based on the current upstream head (flutter/flutter#183048) 2026-03-03 [email protected] [Impeller] Update comments to reflect new info about 2-pass rendering (flutter/flutter#183050) 2026-03-03 [email protected] Add vmservices for accessibilityEvaluation (flutter/flutter#182791) 2026-03-03 [email protected] Roll Fuchsia Linux SDK from 0dCDM2oORHwDf_pyb... to JJw5EJ87vLGqFVl4h... (flutter/flutter#183177) 2026-03-03 [email protected] Support mixed color spaces in `Color.lerp` (flutter/flutter#182934) 2026-03-03 [email protected] Add warning when there is a widget with color between `Material` and `ListTile` (flutter/flutter#181402) 2026-03-03 [email protected] [ios]uitest for admob banner in scrollable list gesture issue (flutter/flutter#183128) 2026-03-03 [email protected] Roll Packages from faa4e22 to 9083bc9 (4 revisions) (flutter/flutter#183164) 2026-03-03 [email protected] Build App and native asset frameworks for Add to App FlutterPluginRegistrant (flutter/flutter#183136) 2026-03-03 [email protected] Roll Skia from f886711f180d to fe9e9f22c531 (4 revisions) (flutter/flutter#183155) 2026-03-03 [email protected] Roll Dart SDK from e86dbe9aa742 to c597ef90d2dc (2 revisions) (flutter/flutter#183147) 2026-03-03 [email protected] fix: bump matcher (flutter/flutter#183167) 2026-03-02 [email protected] Use isA to test for exceptions (flutter/flutter#183129) 2026-03-02 [email protected] [two_dimensional_scrollables] Fix tableview janks when first row/column pinned (flutter/flutter#180563) 2026-03-02 [email protected] Add await to callsites of BasicMessageChannel.send (flutter/flutter#182868) 2026-03-02 [email protected] Roll pub packages (flutter/flutter#183133) 2026-03-02 [email protected] Improve FFI code for windowing (flutter/flutter#183098) 2026-03-02 [email protected] [workflow] Update the changelog merge action to fetch the stable branch (flutter/flutter#183132) 2026-03-02 [email protected] Roll Skia from e180358b7a7a to f886711f180d (2 revisions) (flutter/flutter#183130) 2026-03-02 [email protected] Merge changelog from 3.41.3. (flutter/flutter#183131) 2026-03-02 [email protected] Make TextDecoration final and unify maskValue across platforms (flutter/flutter#183070) 2026-03-02 [email protected] Roll pub packages (flutter/flutter#182640) 2026-03-02 [email protected] Enable SwiftPM by default on master and beta (flutter/flutter#182923) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC [email protected],[email protected] on the revert to ensure that a human is aware of the problem. To file a bug in Packages: https://github.com/flutter/flutter/issues/new/choose To report a problem with the AutoRoller itself, please file a bug: https://issues.skia.org/issues/new?component=1389291&template=1850622 Documentation for the AutoRoller is here: ...
xxxOVALxxx
pushed a commit
to xxxOVALxxx/flutter
that referenced
this pull request
Mar 10, 2026
…`ListTile` (flutter#181402) Fixes flutter#174366 This PR is to throw exception when there is a widget with a non-transparent color (like a `Container(color: Colors.pink)`) between `ListTile` and `Material`. The fix is based on [comment](flutter#174858 (comment)) in the original fix PR which has been closed. ## Pre-launch Checklist - [x] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [x] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [x] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [x] I signed the [CLA]. - [x] I listed at least one issue that this PR fixes in the description above. - [x] I updated/added relevant documentation (doc comments with `///`). - [x] I added new tests to check the change I am making, or this PR is [test-exempt]. - [x] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [x] All existing and new tests are passing. 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](https://developers.google.com/gemini-code-assist/docs/review-github-code). 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. <!-- Links --> [Contributor Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#overview [Tree Hygiene]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md [test-exempt]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#tests [Flutter Style Guide]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md [Features we expect every widget to implement]: https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md#features-we-expect-every-widget-to-implement [CLA]: https://cla.developers.google.com/ [flutter/tests]: https://github.com/flutter/tests [breaking change policy]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#handling-breaking-changes [Discord]: https://github.com/flutter/flutter/blob/main/docs/contributing/Chat.md [Data Driven Fixes]: https://github.com/flutter/flutter/blob/main/docs/contributing/Data-driven-Fixes.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #174366
This PR is to throw exception when there is a widget with a non-transparent color (like a
Container(color: Colors.pink)) betweenListTileandMaterial. The fix is based on comment in the original fix PR which has been closed.Pre-launch 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-assistbot 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.