Recommend OverlayPortal.overlayChildLayoutBuilder over Target-Follower#188894
Merged
Conversation
github-actions
Bot
added
the
framework
![gemini-code-assist[bot]](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 updates documentation in object.dart to clarify the null return value of _debugClosestMutationRoot, and adds documentation templates in basic.dart explaining the incompatibility between CompositedTransformFollower/CompositedTransformTarget and OverlayPortal.overlayChildLayoutBuilder. Feedback suggests correcting a grammatical error in the new documentation template and wrapping the lines to adhere to the 80-character limit.
loic-sharma
reviewed
Jul 2, 2026
| /// {@template flutter.widgets.CompositedTransformFollower.overlayPortal} | ||
| /// [CompositedTransformFollower] and [CompositedTransformTarget] are | ||
| /// incompatible with [OverlayPortal.overlayChildLayoutBuilder] and thus must not | ||
| /// be used together. Consider using the [OverlayPortal.overlayChildLayoutBuilder] |
Member
There was a problem hiding this comment.
I suspect users might miss this recommendation to prefer OverlayPortal.overlayChildLayoutBuilder since these API docs are extensive. What do you think of moving the content from the Consider using the... sentence to the See also: section? I think that might stand out more.
Something like:
/// See also:
///
...
/// * [OverlayPortal.overlayChildLayoutBuilder], which achieves a similar
/// target-following effect, but also allows the follower to be sized and
/// positioned dynamically based on the target's size and position.
loic-sharma
previously approved these changes
Jul 2, 2026
loic-sharma
left a comment
loic-sharma
left a comment
Member
There was a problem hiding this comment.
This looks good to me, but maybe consider moving the recommendation to prefer OverlayPortal.overlayChildLayoutBuilder in the See also: section to improve discoverability.
10 tasks
LongCatIsLooong
added
the
autosubmit
flutter-dashboard
Bot
removed
the
autosubmit
Rusino
pushed a commit
to Rusino/flutter
that referenced
this pull request
Jul 7, 2026
…wer (flutter#188894) Also document that these 2 APIs are not compatible. With the doc change I would like to discourage the use of `CompositedTransformTarget` and `CompositedTransformFollower` since their competing API `OverlayPortal.overlayChildLayoutBuilder` is generally more powerful but unfortunately is also incompatible with `CompositedTransformTarget` and `CompositedTransformFollower`. Existing `CompositedTransformTarget` and `CompositedTransformFollower` usages in apps may throw when we port framework widgets to the new API. I thought about introducing a convenience `OverlayPortal` constructor that can be used as drop-in replacement of `CompositedTransformTarget` and `CompositedTransformFollower` but it seems to me that always following the `target` without resizing or re-positioning is not a common use case: in most cases you'd want to adjust the follower to stay in the viewport when the target moves too close to the edge. ## Pre-launch Checklist - [ ] I read the [Contributor Guide] and followed the process outlined there for submitting PRs. - [ ] I read the [AI contribution guidelines] and understand my responsibilities, or I am not using AI tools. - [ ] I read the [Tree Hygiene] wiki page, which explains my responsibilities. - [ ] I read and followed the [Flutter Style Guide], including [Features we expect every widget to implement]. - [ ] I signed the [CLA]. - [ ] I listed at least one issue that this PR fixes in the description above. - [ ] I updated/added relevant documentation (doc comments with `///`). - [ ] I added new tests to check the change I am making, or this PR is [test-exempt]. - [ ] I followed the [breaking change policy] and added [Data Driven Fixes] where supported. - [ ] All existing and new tests are passing. If you need help, consider asking for advice on the #hackers-new channel on [Discord]. If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance. **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 [AI contribution guidelines]: https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md#ai-contribution-guidelines [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 was referenced Jul 7, 2026
auto-submit Bot
pushed a commit
to flutter/packages
that referenced
this pull request
Jul 8, 2026
…12137) Manual roll Flutter from 6995038d96ef to 91939cc4db78 (48 revisions) Manual roll requested by [email protected] flutter/flutter@6995038...91939cc 2026-07-07 [email protected] Roll Skia from 80ae1deed9ed to 075fbe4778d9 (6 revisions) (flutter/flutter#189067) 2026-07-07 [email protected] Bump customer testing version for new registrants (flutter/flutter#189070) 2026-07-07 [email protected] Roll Packages from fc00ceb to 92525f5 (2 revisions) (flutter/flutter#189069) 2026-07-07 [email protected] fix android semantics integration test hangs due to postframe callback (flutter/flutter#189043) 2026-07-07 [email protected] Bump goldctl (flutter/flutter#189030) 2026-07-07 [email protected] Roll Skia from 71db7c06c5fe to 80ae1deed9ed (2 revisions) (flutter/flutter#189060) 2026-07-07 [email protected] Collect analytics on AI agent usage (flutter/flutter#187630) 2026-07-07 [email protected] Roll Skia from 125a76cc4cf3 to 71db7c06c5fe (4 revisions) (flutter/flutter#189054) 2026-07-07 [email protected] Roll Dart SDK from 70577d6f2bba to c648e3429d76 (1 revision) (flutter/flutter#189052) 2026-07-07 [email protected] Fix RenderSliverPadding setter assertion (flutter/flutter#187353) 2026-07-07 [email protected] Roll Skia from 2dde156aec3e to 125a76cc4cf3 (3 revisions) (flutter/flutter#189037) 2026-07-07 [email protected] Explain asynchronous causes in the setState() called after dispose() error (flutter/flutter#187294) 2026-07-07 [email protected] Roll Skia from 7dccd1e79a5b to 2dde156aec3e (2 revisions) (flutter/flutter#189035) 2026-07-07 [email protected] Add `STRING_CATALOG_GENERATE_SYMBOLS = YES;` (flutter/flutter#188163) 2026-07-07 [email protected] Print warnings on Intel Macs / targeting Intel Macs (flutter/flutter#188835) 2026-07-07 [email protected] Roll Dart SDK from 4c03f64b19f6 to 70577d6f2bba (1 revision) (flutter/flutter#189031) 2026-07-07 [email protected] Roll Fuchsia Linux SDK from n1Lm2Z4DZkfC3bwj5... to 7RjQJBW3m-3Jl-7jr... (flutter/flutter#189032) 2026-07-06 [email protected] Recommend `OverlayPortal.overlayChildLayoutBuilder` over Target-Follower (flutter/flutter#188894) 2026-07-06 [email protected] Sync CHANGELOG.md from stable (flutter/flutter#189025) 2026-07-06 [email protected] Rename preferredSize to size and preferredConstraints to constraints in the windowing API (flutter/flutter#189017) 2026-07-06 [email protected] Skip locked issues in no-response check (flutter/flutter#188950) 2026-07-06 [email protected] Fix potential race condtion in android_semantics_integration_test (flutter/flutter#188830) 2026-07-06 [email protected] ci: udpate wait-for-engine-build composite action to cocoon (flutter/flutter#189020) 2026-07-06 [email protected] Roll Skia from 2b55eed5500d to 7dccd1e79a5b (3 revisions) (flutter/flutter#189021) 2026-07-06 [email protected] [AGP 9] Update Flutter Template Versions (flutter/flutter#188762) 2026-07-06 [email protected] fix(engine/windows): keep tooltip position rect alive - fix use after free (flutter/flutter#188476) 2026-07-06 [email protected] [Tool] Fix null check operator crash in currentPackageConfig (flutter/flutter#188454) 2026-07-06 [email protected] [Tool] Gracefully handle WDAC/AppLocker blocks for impellerc (flutter/flutter#188452) 2026-07-06 [email protected] [flutter_tools] Throw DaemonException if app fails to start early (flutter/flutter#188921) 2026-07-06 [email protected] Roll Dart SDK from ce7a2567eb59 to 4c03f64b19f6 (2 revisions) (flutter/flutter#189015) 2026-07-06 [email protected] [flutter_tools, engine] Add --disable-service-origin-check option to disable VM service origin checks (flutter/flutter#188745) 2026-07-06 [email protected] [flutter_tools] Fix test flakiness in widget_preview_detection_test.dart (flutter/flutter#188922) 2026-07-06 [email protected] Roll pub packages (flutter/flutter#189009) 2026-07-06 [email protected] Roll Skia from c0e2b9667d91 to 2b55eed5500d (1 revision) (flutter/flutter#189006) 2026-07-06 [email protected] Roll Packages from 2fbe873 to fc00ceb (1 revision) (flutter/flutter#189007) 2026-07-06 [email protected] Roll Skia from b68567542f81 to c0e2b9667d91 (1 revision) (flutter/flutter#189004) 2026-07-06 [email protected] Fixing multiline GetBoxesForRange (flutter/flutter#188803) 2026-07-06 [email protected] Roll Skia from e15ea7a4b927 to b68567542f81 (4 revisions) (flutter/flutter#189000) 2026-07-06 [email protected] Roll Skia from 79806692425f to e15ea7a4b927 (2 revisions) (flutter/flutter#188992) 2026-07-06 [email protected] Roll Skia from 2826ae6dc649 to 79806692425f (1 revision) (flutter/flutter#188991) 2026-07-06 [email protected] Roll Skia from 7f99eee20fd6 to 2826ae6dc649 (1 revision) (flutter/flutter#188990) 2026-07-06 [email protected] Add debugPaintFocusBoxes (flutter/flutter#188288) 2026-07-05 [email protected] Roll Fuchsia Linux SDK from bkK6BLiZDRnE7AQQj... to n1Lm2Z4DZkfC3bwj5... (flutter/flutter#188989) 2026-07-05 [email protected] Roll Skia from 75a4bf6706bd to 7f99eee20fd6 (2 revisions) (flutter/flutter#188988) ...
kalyujniy
pushed a commit
to brickit-app/camera
that referenced
this pull request
Jul 8, 2026
…lutter#12137) Manual roll Flutter from 6995038d96ef to 91939cc4db78 (48 revisions) Manual roll requested by [email protected] flutter/flutter@6995038...91939cc 2026-07-07 [email protected] Roll Skia from 80ae1deed9ed to 075fbe4778d9 (6 revisions) (flutter/flutter#189067) 2026-07-07 [email protected] Bump customer testing version for new registrants (flutter/flutter#189070) 2026-07-07 [email protected] Roll Packages from fc00ceb to 92525f5 (2 revisions) (flutter/flutter#189069) 2026-07-07 [email protected] fix android semantics integration test hangs due to postframe callback (flutter/flutter#189043) 2026-07-07 [email protected] Bump goldctl (flutter/flutter#189030) 2026-07-07 [email protected] Roll Skia from 71db7c06c5fe to 80ae1deed9ed (2 revisions) (flutter/flutter#189060) 2026-07-07 [email protected] Collect analytics on AI agent usage (flutter/flutter#187630) 2026-07-07 [email protected] Roll Skia from 125a76cc4cf3 to 71db7c06c5fe (4 revisions) (flutter/flutter#189054) 2026-07-07 [email protected] Roll Dart SDK from 70577d6f2bba to c648e3429d76 (1 revision) (flutter/flutter#189052) 2026-07-07 [email protected] Fix RenderSliverPadding setter assertion (flutter/flutter#187353) 2026-07-07 [email protected] Roll Skia from 2dde156aec3e to 125a76cc4cf3 (3 revisions) (flutter/flutter#189037) 2026-07-07 [email protected] Explain asynchronous causes in the setState() called after dispose() error (flutter/flutter#187294) 2026-07-07 [email protected] Roll Skia from 7dccd1e79a5b to 2dde156aec3e (2 revisions) (flutter/flutter#189035) 2026-07-07 [email protected] Add `STRING_CATALOG_GENERATE_SYMBOLS = YES;` (flutter/flutter#188163) 2026-07-07 [email protected] Print warnings on Intel Macs / targeting Intel Macs (flutter/flutter#188835) 2026-07-07 [email protected] Roll Dart SDK from 4c03f64b19f6 to 70577d6f2bba (1 revision) (flutter/flutter#189031) 2026-07-07 [email protected] Roll Fuchsia Linux SDK from n1Lm2Z4DZkfC3bwj5... to 7RjQJBW3m-3Jl-7jr... (flutter/flutter#189032) 2026-07-06 [email protected] Recommend `OverlayPortal.overlayChildLayoutBuilder` over Target-Follower (flutter/flutter#188894) 2026-07-06 [email protected] Sync CHANGELOG.md from stable (flutter/flutter#189025) 2026-07-06 [email protected] Rename preferredSize to size and preferredConstraints to constraints in the windowing API (flutter/flutter#189017) 2026-07-06 [email protected] Skip locked issues in no-response check (flutter/flutter#188950) 2026-07-06 [email protected] Fix potential race condtion in android_semantics_integration_test (flutter/flutter#188830) 2026-07-06 [email protected] ci: udpate wait-for-engine-build composite action to cocoon (flutter/flutter#189020) 2026-07-06 [email protected] Roll Skia from 2b55eed5500d to 7dccd1e79a5b (3 revisions) (flutter/flutter#189021) 2026-07-06 [email protected] [AGP 9] Update Flutter Template Versions (flutter/flutter#188762) 2026-07-06 [email protected] fix(engine/windows): keep tooltip position rect alive - fix use after free (flutter/flutter#188476) 2026-07-06 [email protected] [Tool] Fix null check operator crash in currentPackageConfig (flutter/flutter#188454) 2026-07-06 [email protected] [Tool] Gracefully handle WDAC/AppLocker blocks for impellerc (flutter/flutter#188452) 2026-07-06 [email protected] [flutter_tools] Throw DaemonException if app fails to start early (flutter/flutter#188921) 2026-07-06 [email protected] Roll Dart SDK from ce7a2567eb59 to 4c03f64b19f6 (2 revisions) (flutter/flutter#189015) 2026-07-06 [email protected] [flutter_tools, engine] Add --disable-service-origin-check option to disable VM service origin checks (flutter/flutter#188745) 2026-07-06 [email protected] [flutter_tools] Fix test flakiness in widget_preview_detection_test.dart (flutter/flutter#188922) 2026-07-06 [email protected] Roll pub packages (flutter/flutter#189009) 2026-07-06 [email protected] Roll Skia from c0e2b9667d91 to 2b55eed5500d (1 revision) (flutter/flutter#189006) 2026-07-06 [email protected] Roll Packages from 2fbe873 to fc00ceb (1 revision) (flutter/flutter#189007) 2026-07-06 [email protected] Roll Skia from b68567542f81 to c0e2b9667d91 (1 revision) (flutter/flutter#189004) 2026-07-06 [email protected] Fixing multiline GetBoxesForRange (flutter/flutter#188803) 2026-07-06 [email protected] Roll Skia from e15ea7a4b927 to b68567542f81 (4 revisions) (flutter/flutter#189000) 2026-07-06 [email protected] Roll Skia from 79806692425f to e15ea7a4b927 (2 revisions) (flutter/flutter#188992) 2026-07-06 [email protected] Roll Skia from 2826ae6dc649 to 79806692425f (1 revision) (flutter/flutter#188991) 2026-07-06 [email protected] Roll Skia from 7f99eee20fd6 to 2826ae6dc649 (1 revision) (flutter/flutter#188990) 2026-07-06 [email protected] Add debugPaintFocusBoxes (flutter/flutter#188288) 2026-07-05 [email protected] Roll Fuchsia Linux SDK from bkK6BLiZDRnE7AQQj... to n1Lm2Z4DZkfC3bwj5... (flutter/flutter#188989) 2026-07-05 [email protected] Roll Skia from 75a4bf6706bd to 7f99eee20fd6 (2 revisions) (flutter/flutter#188988) ...
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
2 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.
Also document that these 2 APIs are not compatible.
With the doc change I would like to discourage the use of
CompositedTransformTargetandCompositedTransformFollowersince their competing APIOverlayPortal.overlayChildLayoutBuilderis generally more powerful but unfortunately is also incompatible withCompositedTransformTargetandCompositedTransformFollower. ExistingCompositedTransformTargetandCompositedTransformFollowerusages in apps may throw when we port framework widgets to the new API.I thought about introducing a convenience
OverlayPortalconstructor that can be used as drop-in replacement ofCompositedTransformTargetandCompositedTransformFollowerbut it seems to me that always following the
targetwithout resizing or re-positioning is not a common use case: in most cases you'd want to adjust the follower to stay in the viewport when the target moves too close to the edge.Pre-launch Checklist
///).If you need help, consider asking for advice on the #hackers-new channel on Discord.
If this change needs to override an active code freeze, provide a comment explaining why. The code freeze workflow can be overridden by code reviewers. See pinned issues for any active code freezes with guidance.
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.