The local position returned by `AnnotatedRegionLayers` in an annotation search has been changed to be relative to the clipping region instead of the layer. This makes the local position more meaningful and reliable, but breaks code that directly performs annotation searches and uses the local position.
Original behavior
Annotations are metadata that are assigned during the rendering phase to regions on the screen. Searching the annotations with a location gives the contextual information that contains that location. They are used to detect mouse events and the theme of app bars.
New behavior
The `localPosition` returned by an `AnnotatedRegionLayer` is now the local position it received subtracted by `offset`, where `offset` is the location of the clipping area relative to the layer.
- Who is affected
- Applications and packages relying on the previous behaviour or signature. Code that uses AnnotatedRegionLayers, Transform, TransformLayer and related APIs.
- Practical impact
- Behaviour or API differences that can break builds or change runtime behaviour.
- 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.
Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)
Code that is actively using this local position is probably
directly interacting with layers, since using render objects or
widgets have already made this result unreliable. In order to
preserve the previous behavior, you can reimplement
AnnotatedRegionLayer to return a local position without
subtracting the offset.
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 (docs.flutter.dev/release/breaking-changes).
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.
- Official migration guide
- AnnotatedRegionLayer
- AnnotationEntry
- Issue #49568
- Make Annotation's localPosition relative to object
- 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.