Flutter Semantics and Native Platform Accessibility Tree Synchronization

Focus Order When Native Platform Overrides Flutter Semantics

The final focus order is primarily determined by the platform-native accessibility traversal algorithm when the Flutter semantics tree does not explicitly override it. On Android, TalkBack defaults to the visual view hierarchy and focusable flags; on iOS, VoiceOver follows the UIAccessibility hierarchy with its own traversal rules. Identical Semantics configurations may therefore produce different navigation paths across platforms. Note: Flutter version affects semantics synchronization timing; older versions may not update the native tree as promptly as newer releases, which can amplify focus-order discrepancies during rapid transitions.

Likely explanation

When no sortKey is provided, the native platform interprets the mapped semantics nodes according to its internal hierarchy. On Android, this aligns with the view tree order and the focusable attribute. On iOS, traversal is hierarchical and can be affected by layout position and accessibility container rules. Identical Flutter Semantics widgets thus may result in divergent focus orders.

Confirmed facts

• Flutter rebuilds the semantics tree each frame via applySemantics; sortKey explicitly instructs the native platform to follow a custom order.
• MergeSemantics collapses children into a single native element, overriding individual sortKey logic for those children.
• Rapid UI transitions can introduce a one-frame latency between the Flutter rebuild and the native tree update, causing screen readers to briefly announce stale content or lose focus.

Practical steps

1. Set sortKey on root or critical Semantics widgets to enforce consistent traversal across iOS and Android.
2. Avoid relying on MergeSemantics when individual child focus is required; use explicit focusable and sortKey instead.
3. Profile the semantics rebuild time with flutter run --profile and inspect frame-sync latency during UI transitions.
4. Use platform-native tools (Android AccessibilityExplorer, iOS Accessibility Inspector) to verify the actual focus trail after each change.

If you are using PlatformView (embedded native views) within these layouts, native views bypass the Flutter semantics tree entirely, creating synchronization gaps that sortKey and MergeSemantics cannot resolve. Confirming this determines whether the recommended steps will fully address the focus-order discrepancy.