The `OverlayPortal.targetsRootOverlay` property was deprecated and replaced with `overlayLocation`.
Original behavior
A `overlayLocation` parameter was added to the `OverlayPortal` default constructor to control where the overlay child renders. As a result, the `OverlayPortal.targetsRootOverlay` constructor is no longer useful.
New behavior
The `OverlayPortal.targetsRootOverlay` constructor is deprecated.
- Who is affected
- Code that still calls the deprecated API; it keeps working until removal but produces analyzer warnings. Code that uses OverlayPortal.targetsRootOverlay, Overlay.of, Overlay.maybeOf and related APIs.
- Practical impact
- Warnings now; removal in a future release. Plan the migration but no immediate break.
- What action should I take?
- Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
Before and after (from the official guide)
| 1 | Widget build(BuildContext context) { | |
| 2 | − | return OverlayPortal.targetsRootOverlay( |
| 3 | controller: myController, | |
| 4 | overlayChildBuilder: _myBuilder, | |
| 5 | child: myChild, | |
| 6 | ); | |
| 7 | } |
| 1 | Widget build(BuildContext context) { | |
| 2 | + | return OverlayPortal( |
| 3 | + | overlayLocation: OverlayChildLocation.rootOverlay, |
| 4 | controller: myController, | |
| 5 | overlayChildBuilder: _myBuilder, | |
| 6 | child: myChild, | |
| 7 | ); | |
| 8 | } |
Raw before / after
Widget build(BuildContext context) {
return OverlayPortal.targetsRootOverlay(
controller: myController,
overlayChildBuilder: _myBuilder,
child: myChild,
);
}Widget build(BuildContext context) {
return OverlayPortal(
overlayLocation: OverlayChildLocation.rootOverlay,
controller: myController,
overlayChildBuilder: _myBuilder,
child: myChild,
);
}Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)
If you are using OverlayPortal.targetsRootOverlay,
use OverlayPortal with overlayLocation instead.
Case 1: trivial case
Code before migration:
Widget build(BuildContext context) {
return OverlayPortal.targetsRootOverlay(
controller: myController,
overlayChildBuilder: _myBuilder,
child: myChild,
);
}Code after migration:
Widget build(BuildContext context) {
return OverlayPortal(
overlayLocation: OverlayChildLocation.rootOverlay,
controller: myController,
overlayChildBuilder: _myBuilder,
child: myChild,
);
}If you expect Overlay.of and Overlay.maybeOf to lookup past LookupBoundary,
use findAncestorStateOfType instead.
Code before migration:
Widget build(BuildContext context) {
Overlay.of(context);
// ...
}Code after migration:
Widget build(BuildContext context) {
context.findAncestorStateOfType<OverlayState>();
// ...
}AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.Listed in the official breaking-changes index; title states deprecation.
An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.
- Source commit
- b3045439b7c0
- Source last updated
- Oct 21, 2026
- Last synchronized
- Oct 21, 2026
- Publication status
- published
Publication history
- Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.