Visitar URL original
Recommend `OverlayPortal.overlayChildLayoutBuilder` over Target-Follower by LongCatIsLooong · Pull Request #188894 · flutter/flutter · GitHub
Skip to content

Recommend OverlayPortal.overlayChildLayoutBuilder over Target-Follower - #188894

Merged
auto-submit[bot] merged 4 commits into
flutter:masterfrom
LongCatIsLooong:docs-change
Jul 7, 2026
Merged

Recommend OverlayPortal.overlayChildLayoutBuilder over Target-Follower#188894
auto-submit[bot] merged 4 commits into
flutter:masterfrom
LongCatIsLooong:docs-change

Conversation

@LongCatIsLooong

@LongCatIsLooong LongCatIsLooong commented Jul 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

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

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-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.

@flutter-dashboard flutter-dashboard Bot added the CICD Run CI/CD label Jul 1, 2026
@github-actions github-actions Bot added the framework flutter/packages/flutter repository. See also f: labels. label Jul 1, 2026
gemini-code-assist[bot]
gemini-code-assist Bot reviewed Jul 1, 2026
View reviewed changes

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

Comment thread packages/flutter/lib/src/widgets/basic.dart Resolved
loic-sharma
loic-sharma reviewed Jul 2, 2026
View reviewed changes
Comment thread packages/flutter/lib/src/widgets/basic.dart Outdated
/// {@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]

@loic-sharma loic-sharma Jul 2, 2026 •
edited
Loading

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.

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
loic-sharma previously approved these changes Jul 2, 2026
View reviewed changes

@loic-sharma loic-sharma 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.

This looks good to me, but maybe consider moving the recommendation to prefer OverlayPortal.overlayChildLayoutBuilder in the See also: section to improve discoverability.

loic-sharma
loic-sharma approved these changes Jul 2, 2026
View reviewed changes

@loic-sharma loic-sharma 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.

Re-LGTM!

@loic-sharma loic-sharma mentioned this pull request Jul 2, 2026
Closed
10 tasks done
@LongCatIsLooong LongCatIsLooong added the autosubmit Merge PR when tree becomes green via auto submit App label Jul 6, 2026
@auto-submit
auto-submit Bot added this pull request to the merge queue Jul 6, 2026
Merged via the queue into flutter:master with commit 6589519 Jul 7, 2026
91 checks passed
@flutter-dashboard flutter-dashboard Bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Jul 7, 2026
@engine-flutter-autoroll engine-flutter-autoroll mentioned this pull request Jul 7, 2026
Closed
Rusino pushed a commit to Rusino/flutter that referenced this pull request Jul 7, 2026
@LongCatIsLooong @Rusino
Recommend OverlayPortal.overlayChildLayoutBuilder over Target-Follo…
05db77f 
…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
Closed
Closed
Closed
Closed
Closed
Closed
Closed
Merged
auto-submit Bot pushed a commit to flutter/packages that referenced this pull request Jul 8, 2026
@engine-flutter-autoroll
Manual roll Flutter from 6995038d96ef to 91939cc4db78 (48 revisions) (#…
52d84d6 
…12137)

Manual roll Flutter from 6995038d96ef to 91939cc4db78 (48 revisions)

Manual roll requested by stuartmorgan@google.com

flutter/flutter@6995038...91939cc

2026-07-07 engine-flutter-autoroll@skia.org Roll Skia from 80ae1deed9ed to 075fbe4778d9 (6 revisions) (flutter/flutter#189067)
2026-07-07 katelovett@google.com Bump customer testing version for new registrants (flutter/flutter#189070)
2026-07-07 engine-flutter-autoroll@skia.org Roll Packages from fc00ceb to 92525f5 (2 revisions) (flutter/flutter#189069)
2026-07-07 47866232+chunhtai@users.noreply.github.com fix android semantics integration test hangs due to postframe callback (flutter/flutter#189043)
2026-07-07 katelovett@google.com Bump goldctl (flutter/flutter#189030)
2026-07-07 engine-flutter-autoroll@skia.org Roll Skia from 71db7c06c5fe to 80ae1deed9ed (2 revisions) (flutter/flutter#189060)
2026-07-07 magder@google.com Collect analytics on AI agent usage (flutter/flutter#187630)
2026-07-07 engine-flutter-autoroll@skia.org Roll Skia from 125a76cc4cf3 to 71db7c06c5fe (4 revisions) (flutter/flutter#189054)
2026-07-07 engine-flutter-autoroll@skia.org Roll Dart SDK from 70577d6f2bba to c648e3429d76 (1 revision) (flutter/flutter#189052)
2026-07-07 vuhoangminh97@gmail.com Fix RenderSliverPadding setter assertion (flutter/flutter#187353)
2026-07-07 engine-flutter-autoroll@skia.org Roll Skia from 2dde156aec3e to 125a76cc4cf3 (3 revisions) (flutter/flutter#189037)
2026-07-07 49402500+fahaddoc@users.noreply.github.com Explain asynchronous causes in the setState() called after dispose() error (flutter/flutter#187294)
2026-07-07 engine-flutter-autoroll@skia.org Roll Skia from 7dccd1e79a5b to 2dde156aec3e (2 revisions) (flutter/flutter#189035)
2026-07-07 116356835+AbdeMohlbi@users.noreply.github.com Add `STRING_CATALOG_GENERATE_SYMBOLS = YES;` (flutter/flutter#188163)
2026-07-07 31859944+LongCatIsLooong@users.noreply.github.com Print warnings on Intel Macs / targeting Intel Macs (flutter/flutter#188835)
2026-07-07 engine-flutter-autoroll@skia.org Roll Dart SDK from 4c03f64b19f6 to 70577d6f2bba (1 revision) (flutter/flutter#189031)
2026-07-07 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from n1Lm2Z4DZkfC3bwj5... to 7RjQJBW3m-3Jl-7jr... (flutter/flutter#189032)
2026-07-06 31859944+LongCatIsLooong@users.noreply.github.com Recommend `OverlayPortal.overlayChildLayoutBuilder` over Target-Follower (flutter/flutter#188894)
2026-07-06 154381524+flutteractionsbot@users.noreply.github.com Sync CHANGELOG.md from stable (flutter/flutter#189025)
2026-07-06 matt.kosarek@canonical.com Rename preferredSize to size and preferredConstraints to constraints in the windowing API (flutter/flutter#189017)
2026-07-06 6655696+guidezpl@users.noreply.github.com Skip locked issues in no-response check (flutter/flutter#188950)
2026-07-06 47866232+chunhtai@users.noreply.github.com Fix potential race condtion in android_semantics_integration_test (flutter/flutter#188830)
2026-07-06 codefu@google.com ci: udpate wait-for-engine-build composite action to cocoon (flutter/flutter#189020)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from 2b55eed5500d to 7dccd1e79a5b (3 revisions) (flutter/flutter#189021)
2026-07-06 jesswon@google.com [AGP 9] Update Flutter Template Versions (flutter/flutter#188762)
2026-07-06 126701490+richyo-codes@users.noreply.github.com fix(engine/windows): keep tooltip position rect alive - fix use after free (flutter/flutter#188476)
2026-07-06 bkonyi@google.com [Tool] Fix null check operator crash in currentPackageConfig (flutter/flutter#188454)
2026-07-06 bkonyi@google.com [Tool] Gracefully handle WDAC/AppLocker blocks for impellerc (flutter/flutter#188452)
2026-07-06 bkonyi@google.com [flutter_tools] Throw DaemonException if app fails to start early (flutter/flutter#188921)
2026-07-06 engine-flutter-autoroll@skia.org Roll Dart SDK from ce7a2567eb59 to 4c03f64b19f6 (2 revisions) (flutter/flutter#189015)
2026-07-06 bkonyi@google.com [flutter_tools, engine] Add --disable-service-origin-check option to disable VM service origin checks (flutter/flutter#188745)
2026-07-06 bkonyi@google.com [flutter_tools] Fix test flakiness in widget_preview_detection_test.dart (flutter/flutter#188922)
2026-07-06 137456488+flutter-pub-roller-bot@users.noreply.github.com Roll pub packages (flutter/flutter#189009)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from c0e2b9667d91 to 2b55eed5500d (1 revision) (flutter/flutter#189006)
2026-07-06 engine-flutter-autoroll@skia.org Roll Packages from 2fbe873 to fc00ceb (1 revision) (flutter/flutter#189007)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from b68567542f81 to c0e2b9667d91 (1 revision) (flutter/flutter#189004)
2026-07-06 Rusino@users.noreply.github.com Fixing multiline GetBoxesForRange (flutter/flutter#188803)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from e15ea7a4b927 to b68567542f81 (4 revisions) (flutter/flutter#189000)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from 79806692425f to e15ea7a4b927 (2 revisions) (flutter/flutter#188992)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from 2826ae6dc649 to 79806692425f (1 revision) (flutter/flutter#188991)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from 7f99eee20fd6 to 2826ae6dc649 (1 revision) (flutter/flutter#188990)
2026-07-06 737941+loic-sharma@users.noreply.github.com Add debugPaintFocusBoxes (flutter/flutter#188288)
2026-07-05 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from bkK6BLiZDRnE7AQQj... to n1Lm2Z4DZkfC3bwj5... (flutter/flutter#188989)
2026-07-05 engine-flutter-autoroll@skia.org 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
@engine-flutter-autoroll @kalyujniy
Manual roll Flutter from 6995038d96ef to 91939cc4db78 (48 revisions) (f…
0897332 
…lutter#12137)

Manual roll Flutter from 6995038d96ef to 91939cc4db78 (48 revisions)

Manual roll requested by stuartmorgan@google.com

flutter/flutter@6995038...91939cc

2026-07-07 engine-flutter-autoroll@skia.org Roll Skia from 80ae1deed9ed to 075fbe4778d9 (6 revisions) (flutter/flutter#189067)
2026-07-07 katelovett@google.com Bump customer testing version for new registrants (flutter/flutter#189070)
2026-07-07 engine-flutter-autoroll@skia.org Roll Packages from fc00ceb to 92525f5 (2 revisions) (flutter/flutter#189069)
2026-07-07 47866232+chunhtai@users.noreply.github.com fix android semantics integration test hangs due to postframe callback (flutter/flutter#189043)
2026-07-07 katelovett@google.com Bump goldctl (flutter/flutter#189030)
2026-07-07 engine-flutter-autoroll@skia.org Roll Skia from 71db7c06c5fe to 80ae1deed9ed (2 revisions) (flutter/flutter#189060)
2026-07-07 magder@google.com Collect analytics on AI agent usage (flutter/flutter#187630)
2026-07-07 engine-flutter-autoroll@skia.org Roll Skia from 125a76cc4cf3 to 71db7c06c5fe (4 revisions) (flutter/flutter#189054)
2026-07-07 engine-flutter-autoroll@skia.org Roll Dart SDK from 70577d6f2bba to c648e3429d76 (1 revision) (flutter/flutter#189052)
2026-07-07 vuhoangminh97@gmail.com Fix RenderSliverPadding setter assertion (flutter/flutter#187353)
2026-07-07 engine-flutter-autoroll@skia.org Roll Skia from 2dde156aec3e to 125a76cc4cf3 (3 revisions) (flutter/flutter#189037)
2026-07-07 49402500+fahaddoc@users.noreply.github.com Explain asynchronous causes in the setState() called after dispose() error (flutter/flutter#187294)
2026-07-07 engine-flutter-autoroll@skia.org Roll Skia from 7dccd1e79a5b to 2dde156aec3e (2 revisions) (flutter/flutter#189035)
2026-07-07 116356835+AbdeMohlbi@users.noreply.github.com Add `STRING_CATALOG_GENERATE_SYMBOLS = YES;` (flutter/flutter#188163)
2026-07-07 31859944+LongCatIsLooong@users.noreply.github.com Print warnings on Intel Macs / targeting Intel Macs (flutter/flutter#188835)
2026-07-07 engine-flutter-autoroll@skia.org Roll Dart SDK from 4c03f64b19f6 to 70577d6f2bba (1 revision) (flutter/flutter#189031)
2026-07-07 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from n1Lm2Z4DZkfC3bwj5... to 7RjQJBW3m-3Jl-7jr... (flutter/flutter#189032)
2026-07-06 31859944+LongCatIsLooong@users.noreply.github.com Recommend `OverlayPortal.overlayChildLayoutBuilder` over Target-Follower (flutter/flutter#188894)
2026-07-06 154381524+flutteractionsbot@users.noreply.github.com Sync CHANGELOG.md from stable (flutter/flutter#189025)
2026-07-06 matt.kosarek@canonical.com Rename preferredSize to size and preferredConstraints to constraints in the windowing API (flutter/flutter#189017)
2026-07-06 6655696+guidezpl@users.noreply.github.com Skip locked issues in no-response check (flutter/flutter#188950)
2026-07-06 47866232+chunhtai@users.noreply.github.com Fix potential race condtion in android_semantics_integration_test (flutter/flutter#188830)
2026-07-06 codefu@google.com ci: udpate wait-for-engine-build composite action to cocoon (flutter/flutter#189020)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from 2b55eed5500d to 7dccd1e79a5b (3 revisions) (flutter/flutter#189021)
2026-07-06 jesswon@google.com [AGP 9] Update Flutter Template Versions (flutter/flutter#188762)
2026-07-06 126701490+richyo-codes@users.noreply.github.com fix(engine/windows): keep tooltip position rect alive - fix use after free (flutter/flutter#188476)
2026-07-06 bkonyi@google.com [Tool] Fix null check operator crash in currentPackageConfig (flutter/flutter#188454)
2026-07-06 bkonyi@google.com [Tool] Gracefully handle WDAC/AppLocker blocks for impellerc (flutter/flutter#188452)
2026-07-06 bkonyi@google.com [flutter_tools] Throw DaemonException if app fails to start early (flutter/flutter#188921)
2026-07-06 engine-flutter-autoroll@skia.org Roll Dart SDK from ce7a2567eb59 to 4c03f64b19f6 (2 revisions) (flutter/flutter#189015)
2026-07-06 bkonyi@google.com [flutter_tools, engine] Add --disable-service-origin-check option to disable VM service origin checks (flutter/flutter#188745)
2026-07-06 bkonyi@google.com [flutter_tools] Fix test flakiness in widget_preview_detection_test.dart (flutter/flutter#188922)
2026-07-06 137456488+flutter-pub-roller-bot@users.noreply.github.com Roll pub packages (flutter/flutter#189009)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from c0e2b9667d91 to 2b55eed5500d (1 revision) (flutter/flutter#189006)
2026-07-06 engine-flutter-autoroll@skia.org Roll Packages from 2fbe873 to fc00ceb (1 revision) (flutter/flutter#189007)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from b68567542f81 to c0e2b9667d91 (1 revision) (flutter/flutter#189004)
2026-07-06 Rusino@users.noreply.github.com Fixing multiline GetBoxesForRange (flutter/flutter#188803)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from e15ea7a4b927 to b68567542f81 (4 revisions) (flutter/flutter#189000)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from 79806692425f to e15ea7a4b927 (2 revisions) (flutter/flutter#188992)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from 2826ae6dc649 to 79806692425f (1 revision) (flutter/flutter#188991)
2026-07-06 engine-flutter-autoroll@skia.org Roll Skia from 7f99eee20fd6 to 2826ae6dc649 (1 revision) (flutter/flutter#188990)
2026-07-06 737941+loic-sharma@users.noreply.github.com Add debugPaintFocusBoxes (flutter/flutter#188288)
2026-07-05 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from bkK6BLiZDRnE7AQQj... to n1Lm2Z4DZkfC3bwj5... (flutter/flutter#188989)
2026-07-05 engine-flutter-autoroll@skia.org Roll Skia from 75a4bf6706bd to 7f99eee20fd6 (2 revisions) (flutter/flutter#188988)
...
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@loic-sharma loic-sharma loic-sharma approved these changes
+1 more reviewer
@gemini-code-assist gemini-code-assist[bot] gemini-code-assist[bot] left review comments
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

CICD Run CI/CD framework flutter/packages/flutter repository. See also f: labels.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@LongCatIsLooong @loic-sharma