[Android] Fix for Shell colors change before navigation completes on Android in .NET 10

[BagavathiPerumal]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Issue details

On Android (.NET MAUI 10), Shell toolbar colors are applied before navigation completes during tab/page transitions, causing the current page to briefly display the destination page’s colors. This is a regression from .NET MAUI 9 and results in incorrect visual behavior during navigation.

Root Cause

The issue occurs because of the toolbar appearance update being triggered before the tab navigation is fully completed when switching tabs in a Shell with TabBar. During the tab change, the destination tab colors are applied immediately while the previous tab content is still visible on screen, which causes a brief color flash. This is especially noticeable when different child pages use different toolbar colors. The behavior started after an earlier change where the appearance update was added during tab switching but executed before the section change was committed.

Description of Change

The fix involves changing the execution order so the section change is committed first, and the appearance update happens only after the tab switch is successfully accepted. This ensures the Shell internal state is updated to the correct tab before applying the toolbar colors, preventing premature color changes while the previous tab is still visible. The update is also skipped when the tab switch is rejected or cancelled, so colors continue to refresh correctly on every tab switch, but now at the correct time.

Why Tests were not added:

Regarding the test case: No automated test case was added for this fix, as the issue is a brief visual color flash that occurs during the tab-switch animation on Android and cannot be reliably captured through the existing automated test infrastructure.

Screenshot-based tests cannot consistently capture the exact transition frame where the issue occurs, and the current baseline comparison approach is unable to accurately differentiate correct and incorrect toolbar color timing during the animation.

Tested the behavior in the following platforms.

• Android
• Mac
• iOS
• Windows

Regression PR: The PR 25870 as the primary regression source. PR 32882 appears to be a later overlapping change affecting Shell color timing.

The PR 25870 as the primary regression source. PR 32882 appears to be a later overlapping change affecting Shell color timing.

Issues Fixed

Fixes #35060

Output

Before Issue Fix	After Issue Fix
35060-BeforeFix.mov	35060-AfterFix.mov

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 35295

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 35295"

[sheiksyedm]

/azp run maui-pr-uitests , maui-pr-devicetests

[azure-pipelines]

Azure Pipelines successfully started running 2 pipeline(s).

[Copilot]

Pull request overview

This PR adjusts Android Shell tab switching so toolbar appearance updates are triggered only after a section change is accepted, avoiding premature color updates during navigation transitions.

Changes:

• Reorders ShellItemRenderer.ChangeSection to call ProposeSection first and only then invoke IShellController.AppearanceChanged when the proposal is accepted.

[MauiBot]

🤖 Automated review — alternative fix proposed

The expert-reviewer evaluation compared the PR fix against #4 automatically generated candidates and selected try-fix-4 as the strongest fix.

Why: try-fix-4 builds on the PR's correct core fix (call ProposeSection first, gate AppearanceChanged on acceptance) and adds three targeted improvements that align with existing MAUI code conventions: null-safe shell access via ShellContext?.Shell (matching the pattern in Destroy()), an else branch that explicitly restores the current section's appearance when navigation is cancelled, and a clear comment explaining the ordering invariant to prevent future regressions.

Please consider applying the candidate diff below (or use it as guidance). Once you push an update, this workflow will re-trigger and re-evaluate.

Candidate diff (`try-fix-4`)

--- a/src/Controls/src/Core/Compatibility/Handlers/Shell/Android/ShellItemRenderer.cs
+++ b/src/Controls/src/Core/Compatibility/Handlers/Shell/Android/ShellItemRenderer.cs
@@ -155,9 +155,18 @@ namespace Microsoft.Maui.Controls.Platform.Compatibility
 		protected virtual bool ChangeSection(ShellSection shellSection)
 		{
-			// Update shell appearance based on the new shell section when switching between tabs
-			((IShellController)ShellContext.Shell).AppearanceChanged(shellSection, false);
-			return ((IShellItemController)ShellItem).ProposeSection(shellSection);
+			// ProposeSection must be called before AppearanceChanged so that navigation guards
+			// can accept or reject the tab switch. Applying appearance changes only after
+			// acceptance prevents toolbar colors from flashing to the new section's values
+			// during navigation transitions that are ultimately rejected or still in progress.
+			var result = ((IShellItemController)ShellItem).ProposeSection(shellSection);
+
+			if (result)
+			{
+				((IShellController)ShellContext?.Shell)?.AppearanceChanged(shellSection, false);
+			}
+			else
+			{
+				// Navigation was rejected; explicitly restore appearance for the current active
+				// section in case any visual state changed during the selection attempt.
+				((IShellController)ShellContext?.Shell)?.AppearanceChanged(ShellItem.CurrentItem, false);
+			}
+
+			return result;
 		}

Resetting for re-review

[MauiBot]

Expert Review — 2 findings

See inline comments for details.

[MauiBot]

🤖 AI Summary

👋 @BagavathiPerumal — new AI review results are available. Please review the latest session below.

📊 Review Session — 5318a4a · fix-35060 — Made code changes in ShellItemRenderer.cs to fix the issue where Shell toolbar colors were updating prematurely before the tab switch completed on Android. · 2026-05-07 21:25 UTC

---

🚦 Gate — Test Before & After Fix

---

Gate Result: ⚠️ SKIPPED

No tests were detected in this PR.

Recommendation: Add tests to verify the fix using the write-tests-agent.

---

🧪 UI Tests — Category Detection

---

Full UI test matrix will run (no specific categories detected from PR changes).

---

🔍 Regression Cross-Reference

---

🔍 Regression Cross-Reference

🟢 No regression risks detected. No labeled bug-fix PRs in the last 6 months touched the modified files.

---

🔍 Pre-Flight — Context & Validation

---

Pre-Flight: PR #35295

Summary

• Title: [Android] Fix for Shell colors change before navigation completes on Android in .NET 10
• Author: BagavathiPerumal (Syncfusion partner)
• Target branch: inflight/current (merged 2026-05-07)
• Issue: Shell colors change before navigation completes on Android in .NET 10 #35060 (regression in 9.0.30; milestone .NET 10 SR7)
• Files changed: 1 (src/Controls/src/Core/Compatibility/Handlers/Shell/Android/ShellItemRenderer.cs)
• Diff size: +6 / -3
• Tests added: None (author rationale: animation-frame-timing flash; existing screenshot infra cannot reliably capture the transient color flash).
• Labels: platform/android, area-controls-shell, community ✨, partner/syncfusion, s/agent-reviewed.

Issue Context

On Android with .NET MAUI 10, when switching tabs in a Shell TabBar, the destination tab's toolbar/Shell colors are applied while the previous tab's content is still visible — producing a brief visual color flash. iOS/Windows are unaffected; .NET 9 is unaffected.

Reproduction repo: aalsamoht/ReproBranches (maui/shell-colors-slow). Two tabs each with a child page that delays content via OnAppearing; each child sets distinct Shell foreground/background/title colors.

Root Cause (per author)

In BottomNavViewAppearanceTracker.ChangeSection (Android), the previous order was:

1. Synchronously call IShellController.AppearanceChanged(shellSection, false) — pushes destination tab's colors immediately.
2. Then call IShellItemController.ProposeSection(shellSection) — actually commits the section change.

Because AppearanceChanged runs first, the Shell appearance for the destination section is applied while the OLD section's page is still visible/animating, causing the flash.

The regression appears to originate from PR #25870, which introduced the eager AppearanceChanged call inside ChangeSection. PR #32882 is also referenced as a possibly-overlapping change.

Fix Submitted

Reorder so ProposeSection runs first, and AppearanceChanged only runs when ProposeSection returns true (the section change was accepted).

protected virtual bool ChangeSection(ShellSection shellSection)
{
    var result = ((IShellItemController)ShellItem).ProposeSection(shellSection);
    if (result)
    {
        ((IShellController)ShellContext.Shell).AppearanceChanged(shellSection, false);
    }
    return result;
}

Ancillary Findings

• IShellItemController.ProposeSection(ShellSection, bool setValue = true) (in Shell/ShellItem.cs) calls controller.ProposeNavigation(...) and (when accepted) sets CurrentItem = shellSection. It is synchronous, so by the time AppearanceChanged runs in the new ordering, Shell.CurrentItem reflects the new section and observers wired through IShellController.AppearanceChanged look up the correct merged appearance via Shell.GetAppearanceForPivot.
• The previous comment "Update shell appearance based on the new shell section when switching between tabs" is removed; the new code's intent is implicit via if (result) block.
• ChangeSection has two call sites: OnItemSelected (bottom-nav tap) and OnMoreItemSelected (more sheet). Both benefit from the new ordering.
• No call site relied on AppearanceChanged firing when ProposeSection returned false (no other Android handler does this).

Risks

• Low blast radius — single Android-only file, single method.
• Behavior change when ProposeSection is rejected: previously colors changed even on rejection; now they don't. This is a correctness improvement (matches user expectation), so risk is minimal.
• No new tests — partner-flagged as untestable via existing screenshot infra. A Page.NavigatedTo / Shell.Navigated event-based test could potentially observe the regression but would not catch a one-frame flash.

Gate

Already executed in prior step — ⚠️ SKIPPED (no tests detected). Author should be encouraged to add a regression test (see Phase 3 / report).

CI signal

PR is merged; reviewer (kubaflo) merged on 2026-05-07 after maui-pr-uitests + maui-pr-devicetests were re-triggered.

---

🔧 Fix — Analysis & Comparison

---

Try-Fix Aggregate Narrative

Four independent candidate fixes were generated, each loading domain knowledge from a different maui-expert-reviewer dimension to keep them diverse:

Candidate	Dimension	Approach	Runtime delta vs PR	Risk
try-fix-1	Threading & async ordering	Defer AppearanceChanged via _bottomView.Post(...)	+1 frame delay, extra closure	Low
try-fix-2	Handler lifecycle & observer wiring	Remove the eager AppearanceChanged entirely; trust the observer chain	Behavioral — may regress whatever #25870 fixed	High
try-fix-3	Regression-pattern analysis	Same runtime as PR + load-bearing comment + helper rename to lock invariant	None	None
try-fix-4	Platform-specifics (Android paint pipeline)	Decouple appearance from ChangeSection; trigger on DisplayedPage change	Event-driven, new state	Medium-High

None of the four were built/run on-device (autonomous environment has no Android SDK). All four were analyzed against the merged PR's diff and the surrounding ShellItem.cs / ShellItemRenderer.cs code paths.

Summary recommendation:

• try-fix-3 is the strongest improvement over the raw PR fix: it preserves the PR's exact runtime behavior while encoding the regression as an explicit, named invariant in code so PR Fix android image loading race condition and improve logging #25870-style refactors cannot silently reintroduce Shell colors change before navigation completes on Android in .NET 10 #35060.
• try-fix-1 is a viable defensive alternative if on-device testing reveals the PR's synchronous reorder is still racy on slower devices.
• try-fix-2 and try-fix-4 are higher-risk and should not be preferred without targeted device verification.

---

📋 Report — Final Recommendation

---

Phase 3 — Comparative Analysis & Winner Selection

Candidates evaluated

#	Name	Runtime behavior	Tests run	Notes
1	pr	Reorder Propose→Appearance, gate on accepted	None added (gate skipped, no tests in PR)	Merged.
2	pr-plus-reviewer	Same as pr	Same as pr	Adds explanatory comment; renames result→accepted. No runtime delta.
3	try-fix-1	Same ordering + Post() defer	Not built	+1 frame; defends future async refactors.
4	try-fix-2	Removes explicit AppearanceChanged	Not built	Risks regressing PR #25870.
5	try-fix-3	Same as pr-plus-reviewer + load-bearing invariant comment	Not built	Comment-only delta.
6	try-fix-4	Decouples appearance from ChangeSection; ties to DisplayedPage	Not built (sketch)	Highest complexity.

Regression-test gating

Per the gate phase, this PR added no tests, so there is no regression-test signal to rank candidates by. None of the candidates were built in the autonomous environment (no Android SDK). Per task rule "candidates that failed regression tests MUST be ranked lower than candidates that passed them," all candidates are treated equally on this axis (no pass, no fail).

Ranking (best → worst)

1. try-fix-3 — strict superset of pr-plus-reviewer: same minimal runtime change as the PR, plus a load-bearing comment that names the regression and forbids splitting the paired call. Best long-term protection against PR Fix android image loading race condition and improve logging #25870-style reverts.
2. pr-plus-reviewer — PR fix + reviewer-suggested explanatory comment + cleaner local name. Equivalent runtime to PR, slightly less anti-regression strength than try-fix-3.
3. pr — correct, minimal, already merged. The only thing missing is the explanatory comment.
4. try-fix-1 — defensive Post() variant. Adds latency and allocation; worth it only if on-device tests show Shell colors change before navigation completes on Android in .NET 10 #35060 is not fully addressed by synchronous reorder.
5. try-fix-4 — most architecturally robust against paint-frame races, but highest complexity, untested, and the OnDisplayedPageChanged wire-up was not fully resolved offline.
6. try-fix-2 — speculative; removing the explicit AppearanceChanged may re-introduce whatever PR Fix android image loading race condition and improve logging #25870 fixed. Lowest rank.

Recommendation

The PR has already landed and is correct. The best forward action is to apply the try-fix-3 (≡ pr-plus-reviewer + invariant comment) delta as a follow-up commit. This is what's selected as the winner.

Because the runtime change is identical to the merged PR, the candidate diff for the winner is purely additive (comment + local rename) — it builds on top of the merged PR rather than replacing it.

Notes for PR author / area owner

• Strongly consider a follow-up unit test that asserts IShellController.AppearanceChanged is not invoked until after ShellItem.CurrentItem has flipped — this would lock the ordering invariant without depending on animation timing.
• Consider auditing whether the explicit AppearanceChanged call in ChangeSection is now redundant with Shell.CurrentItem-driven appearance propagation. Out of scope for SR7, but a useful tech-debt item.

---

[MauiBot]

🤖 Automated review — alternative fix proposed

The expert-reviewer evaluation compared the PR fix against #3 automatically generated candidates and selected try-fix-3 as the strongest fix.

Why: try-fix-3 is a strict superset of the merged PR fix: same minimal runtime change (reorder ProposeSection → AppearanceChanged, gated on acceptance) plus a load-bearing comment that explicitly names issue #35060 and the regressing PR #25870, encoding the paired-call invariant so a future refactor cannot silently split the two calls and re-introduce the flash. Identical runtime to pr/pr-plus-reviewer with strictly better anti-regression maintainability.

Please consider applying the candidate diff below (or use it as guidance). Once you push an update, this workflow will re-trigger and re-evaluate.

Candidate diff (`try-fix-3`)

diff --git a/src/Controls/src/Core/Compatibility/Handlers/Shell/Android/ShellItemRenderer.cs b/src/Controls/src/Core/Compatibility/Handlers/Shell/Android/ShellItemRenderer.cs
index a54d9ae085ec..0000000000000 100644
--- a/src/Controls/src/Core/Compatibility/Handlers/Shell/Android/ShellItemRenderer.cs
+++ b/src/Controls/src/Core/Compatibility/Handlers/Shell/Android/ShellItemRenderer.cs
@@ -154,9 +154,21 @@ protected virtual void SetAppearance(ShellAppearance appearance)
 
 		protected virtual bool ChangeSection(ShellSection shellSection)
 		{
-			// Update shell appearance based on the new shell section when switching between tabs
-			((IShellController)ShellContext.Shell).AppearanceChanged(shellSection, false);
-			return ((IShellItemController)ShellItem).ProposeSection(shellSection);
+			// INVARIANT: Propose first, apply appearance second.
+			//
+			// ProposeSection synchronously sets ShellItem.CurrentItem when it
+			// returns true; AppearanceChanged then resolves the merged Shell
+			// appearance against the *new* CurrentItem. Reversing this order
+			// causes the destination tab's toolbar colors to be applied while
+			// the previous tab is still visible during the BottomNavigationView
+			// transition (issue #35060; regressed by PR #25870).
+			//
+			// Do NOT inline this method or split the two calls.
+			bool accepted = ((IShellItemController)ShellItem).ProposeSection(shellSection);
+			if (accepted)
+			{
+				((IShellController)ShellContext.Shell).AppearanceChanged(shellSection, false);
+			}
+			return accepted;
 		}
 
 		protected virtual Drawable CreateItemBackgroundDrawable()