[iOS/MacCatalyst] Fix Shell.BackgroundColor not applied to bottom TabBar

[Shalini-Ashokan]

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

Setting Shell.BackgroundColor only applies the background color to the top navigation bar. The bottom tab bar does not reflect the color change on iOS/Mac Catalyst 26.

Root Cause

iOS/Mac Catalyst 26 changed tab bar rendering (Liquid Glass material). Setting UITabBarAppearance.BackgroundColor alone doesn't visually apply; iOS 26 uses a different rendering path.

Description of Change

Added direct tabBar.BackgroundColor = effectiveBarColor assignment for iOS 26+, which bypasses the appearance pipeline and directly sets the color on the tab bar, ensuring custom background colors display correctly on iOS 26.

Validated the behavior in the following platforms

• Android
• Windows
• iOS
• Mac

Issues Fixed

Fixes #35380
Fixes #35381

Test case

The test case is already in Main source.

Output ScreenShot

Before	After
35380-Before-IOS.mov	35380-iOS.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 -- 35545

Or

• Run remotely in PowerShell:

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

[dotnet-policy-service]

Hey there @@Shalini-Ashokan! Thank you so much for your PR! Someone from the team will get assigned to your PR shortly and we'll get it reviewed.

[kubaflo]

/review -b feature/regression-check -p ios

[MauiBot]

🤖 Automated review — alternative fix proposed

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

Why: try-fix-2 fixes both real defects in the PR (the missing Mac Catalyst 26 gate and the stuck-color-on-clear) AND solves the root cause by staying inside the UITabBarAppearance pipeline (ConfigureWithOpaqueBackground when a color is set, ConfigureWithDefaultBackground when cleared). It is the only candidate that correctly restores Liquid Glass on runtime color-clear, making it the most idiomatic and lowest-risk fix. Builds cleanly on net10.0-ios26.0 and net10.0-maccatalyst26.0.

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-2`)

diff --git a/src/Core/src/Platform/iOS/TabbedViewExtensions.cs b/src/Core/src/Platform/iOS/TabbedViewExtensions.cs
index 6c5ae4cf06..e164c9d0de 100644
--- a/src/Core/src/Platform/iOS/TabbedViewExtensions.cs
+++ b/src/Core/src/Platform/iOS/TabbedViewExtensions.cs
@@ -46,11 +46,36 @@ namespace Microsoft.Maui.Platform
 			}
 
 			var effectiveBarColor = (barBackgroundColor == null) ? defaultBarColor : barBackgroundColor.ToPlatform();
-			// Set BarBackgroundColor
+
+			// Set BarBackgroundColor.
+			//
+			// On iOS 26 / Mac Catalyst 26+ the tab bar uses a Liquid Glass material as its
+			// BackgroundEffect when configured with ConfigureWithDefaultBackground(). That blur
+			// composites over UITabBarAppearance.BackgroundColor, so an explicitly requested
+			// Shell.BackgroundColor / Shell.TabBarBackgroundColor visually disappears (issues
+			// #35380 / #35381). When the user actively requests a color we switch the
+			// appearance to an opaque configuration so the color renders as a flat fill,
+			// matching pre-26 behavior. When no explicit color is set we re-apply the default
+			// (Liquid Glass) configuration so clearing the color at runtime restores the
+			// material instead of leaving a stale opaque background.
+			var isLiquidGlassEra =
+				OperatingSystem.IsIOSVersionAtLeast(26) ||
+				OperatingSystem.IsMacCatalystVersionAtLeast(26);
+
 			if (effectiveBarColor != null)
 			{
+				if (isLiquidGlassEra)
+				{
+					_tabBarAppearance.ConfigureWithOpaqueBackground();
+				}
+
 				_tabBarAppearance.BackgroundColor = effectiveBarColor;
 			}
+			else if (isLiquidGlassEra)
+			{
+				// No explicit color: keep / restore Liquid Glass.
+				_tabBarAppearance.ConfigureWithDefaultBackground();
+			}
 
 			// Set BarTextColor
 

[kubaflo]

/review -b feature/regression-check -p ios

[kubaflo]

/review -b feature/regression-check -p ios

[MauiBot]

🤖 AI Summary

👋 @Shalini-Ashokan — new AI review results are available. Please review the latest session below.

📊 Review Session — 599f28d · Simplified the fix · 2026-05-20 18:51 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 — ViewBaseTests

Detected UI test categories: ViewBaseTests

🧪 UI Test Execution Results

⏭️ SKIPPED — 0 passed, 0 failed, 1 skipped (platform: ios)

Category	Result	Tests	Duration	Notes
ViewBaseTests	⏭️ SKIPPED	—	0s	Runner threw an exception

Failures here are informational only — they do not block the gate or affect try-fix candidate scoring.

---

🔍 Pre-Flight — Context & Validation

Pre-Flight — PR #35545

PR Summary

• Title: [iOS/MacCatalyst] Fix Shell.BackgroundColor not applied to bottom TabBar
• Author: Shalini-Ashokan (partner/syncfusion)
• Branch: Shalini-Ashokan/maui:fix-35380 → dotnet/maui:main
• State: open, draft, blocked
• Files changed: 1 (+5 / −1)
• Fixes: [MacCatalyst] Shell.BackgroundColor not applied to bottom TabBar #35380, [Catalyst] Shell.TabBarBackgroundColor is not applied #35381

Issues

• [MacCatalyst] Shell.BackgroundColor not applied to bottom TabBar #35380 — [MacCatalyst] Shell.BackgroundColor not applied to bottom TabBar (macOS, Catalyst 26).
• [Catalyst] Shell.TabBarBackgroundColor is not applied #35381 — [Catalyst] Shell.TabBarBackgroundColor is not applied (macOS, Catalyst 26).

Both reports are explicitly MacCatalyst 26. iOS 26 is not mentioned in either issue.

Root cause (per PR description)

iOS/MacCatalyst 26 changed tab bar rendering to use the Liquid Glass material. With the new material, setting only UITabBarAppearance.BackgroundColor no longer paints the bar — the system material overrides the appearance color.

PR's current fix

File: src/Core/src/Platform/iOS/TabbedViewExtensions.cs, inside UpdateiOS15TabBarAppearance:

if (effectiveBarColor != null)
{
    _tabBarAppearance.BackgroundColor = effectiveBarColor;
    if (OperatingSystem.IsIOSVersionAtLeast(26))
    {
        tabBar.BackgroundColor = effectiveBarColor;
    }
}

It assigns UITabBar.BackgroundColor directly (a UIView property) in addition to the appearance, but only when OperatingSystem.IsIOSVersionAtLeast(26) is true.

Critical defects in the current fix

1. Wrong OS check for MacCatalyst. OperatingSystem.IsIOSVersionAtLeast(26) returns false on MacCatalyst. The MAUI codebase consistently uses IsIOSVersionAtLeast(26) || IsMacCatalystVersionAtLeast(26) (see NavigationRenderer.cs 12 sites, ShellSectionRenderer.cs, ShellPageRendererTracker.cs, EntryHandler.iOS.cs, ProgressBarHandler.iOS.cs, StepperExtensions.cs, AlertManager.iOS.cs). The PR's check does not fire on Catalyst, yet both filed issues are Catalyst-only. The PR likely does not fix either of the issues it claims to fix.

2. UITabBar.BackgroundColor is fragile. It's a UIView property; Apple's own docs say to set the bar's appearance via UITabBarAppearance. Directly poking BackgroundColor on a UITabBar can be visually overridden when the system re-renders the material on trait changes, rotation, scroll-edge transitions, sidebar/floating mode, etc. There is no symmetric "unset" path either: if effectiveBarColor is null on a subsequent invocation, the previously-assigned tabBar.BackgroundColor lingers.

3. No tests. Gate phase reported no tests in the PR. There is an existing ShellTabBarTests device-tests file with iOS26/Catalyst26 guards — a regression test belongs there.

4. Possible interaction with ConfigureWithDefaultBackground() — the appearance is configured with the default (translucent material) background. On 26 the material wins. The more conventional fix for "I want a solid custom color" is ConfigureWithOpaqueBackground() (or explicitly setting BackgroundEffect = null).

Gate

⚠️ SKIPPED — no tests detected in this PR.

Files of interest

• src/Core/src/Platform/iOS/TabbedViewExtensions.cs (the patched file)
• src/Controls/src/Core/Compatibility/Handlers/Shell/iOS/SafeShellTabBarAppearanceTracker.cs (Shell caller)
• src/Controls/src/Core/Compatibility/Handlers/TabbedPage/iOS/TabbedRenderer.cs (TabbedPage caller)
• src/Controls/tests/DeviceTests/Elements/Shell/ShellTabBarTests.cs (existing test home)

---

🔧 Fix — Analysis & Comparison

Try-Fix Aggregate — PR #35545

Three alternative fix candidates were explored, all targeting the same file (src/Core/src/Platform/iOS/TabbedViewExtensions.cs). All three build cleanly for both net10.0-ios and net10.0-maccatalyst. The gate phase was skipped (no tests in the PR), so device-test verification on actual iOS 26 / Catalyst 26 hardware was not possible in this environment.

Background

PR #35545 fixes #35380 and #35381 — both report on MacCatalyst 26 that the Shell tab bar ignores Shell.BackgroundColor / Shell.TabBarBackgroundColor. The root cause is the new Liquid Glass material in iOS/MacCatalyst 26 visually overriding UITabBarAppearance.BackgroundColor when the appearance is configured with the default (translucent) background.

The current PR adds tabBar.BackgroundColor = effectiveBarColor (a UIView.BackgroundColor write) inside an OperatingSystem.IsIOSVersionAtLeast(26) guard.

Two defects in the current fix:

1. IsIOSVersionAtLeast(26) returns false on MacCatalyst. The entire MAUI codebase pairs it with IsMacCatalystVersionAtLeast(26) (see NavigationRenderer.cs ~12 sites, ShellPageRendererTracker, EntryHandler.iOS.cs, ProgressBarHandler.iOS.cs, StepperExtensions.cs, AlertManager.iOS.cs). The PR ships a no-op on the very platform users reported.
2. Even with the predicate corrected, UITabBar.BackgroundColor writes to the view's backing layer, which sits behind the Liquid Glass material. The user sees a blended/desaturated approximation, not the requested color.

Candidates

#	Approach	OS check correct?	Uses Apple-sanctioned API?	Round-trips on clear?	Behavior change on pre-26?	Recommendation
try-fix-1	Reconfigure appearance to opaque on 26+, clear BackgroundEffect, restore default on clear	✅	✅ (UITabBarAppearance)	✅	None	PREFERRED
try-fix-2	Keep current PR strategy, only fix predicate	✅	❌ (UIView poke)	❌	None	Comparison only
try-fix-3	Always allocate a fresh UITabBarAppearance; configure opaque on 26+	✅	✅	✅	Yes — appearance is rebuilt on every call for all OS versions	Defer to separate PR

Build verification

All three candidates compiled clean (0 warnings, 0 errors) for both net10.0-ios and net10.0-maccatalyst against the current repo (.NET SDK 10.0.100).

Test gap

The PR has no tests, and the existing src/Controls/tests/DeviceTests/Elements/Shell/ShellTabBarTests.cs actively skips iOS-26/Catalyst-26 at lines 26/57/81/103 ("Skip on iOS 26+ due to UITabBar internal API changes"). Whichever candidate is adopted, a device-test regression case is needed:

• Build a Shell with Shell.TabBarBackgroundColor = Colors.Red.
• After layout, snapshot the tab bar region and sample a pixel inside it.
• Assert the sampled color matches red within tolerance — assert on rendered output, not the appearance object (the appearance object reports red even when the rendered bar is still glass).
• Add a clear-to-null assertion that the default translucent material returns.
• Ensure both the iOS and MacCatalyst CI legs exercise it.

Recommendation

Adopt Candidate 1 (try-fix-1). It corrects the OS predicate, replaces the fragile UIView.BackgroundColor poke with UITabBarAppearance.ConfigureWithOpaqueBackground() + BackgroundEffect = null (Apple's documented way to opt out of Liquid Glass for a specific bar), and cleanly restores the default translucent material when the user clears the color. Behavior on iOS/Catalyst pre-26 is unchanged.

The author should also:

• Re-validate on real MacCatalyst 26 (the current PR's videos cannot have come from this code path).
• Add the regression test described above.
• Consider a follow-up audit of SearchBarExtensions.cs (lines 156/183/217) and SliderExtensions.cs:80 which share the same one-sided IsIOSVersionAtLeast(26) pattern.

Per-candidate detail

• try-fix-1/content.md — Approach A (recommended)
• try-fix-2/content.md — Approach D (minimal predicate fix; suboptimal)
• try-fix-3/content.md — Approach C (always-fresh appearance; wider scope)

---

📋 Report — Final Recommendation

Comparative Report — PR #35545 candidates

Candidates evaluated

Candidate	Source	Diff
pr	The PR as submitted	+tabBar.BackgroundColor = effectiveBarColor; guarded by IsIOSVersionAtLeast(26) only
pr-plus-reviewer	PR + reviewer feedback applied	expert-pr-eval/content.md (functionally identical to try-fix-1)
try-fix-1	STEP 6a Approach A — opaque appearance + round-trip	try-fix-1/cand1.diff
try-fix-2	STEP 6a Approach D — minimal predicate fix only	try-fix-2/cand2.diff
try-fix-3	STEP 6a Approach C — always-fresh appearance	try-fix-3/cand3.diff

Gate was skipped (no tests in PR). No candidate authored a regression test, so no candidate failed regression tests — the "passed > failed" tiebreaker does not split the field. Ranking proceeds on correctness, API fitness, round-trip, and scope.

Scorecard

Criterion	pr	pr-plus-reviewer	try-fix-1	try-fix-2	try-fix-3
OS check correct (covers MacCatalyst, the platform issues filed for)	❌	✅	✅	✅	✅
Uses Apple-sanctioned API (appearance, not UIView.BackgroundColor)	❌	✅	✅	❌	✅
Survives Liquid Glass repaint (material override)	❌	✅	✅	❌	✅
Round-trips when user clears the color	❌	✅	✅	❌	✅
Behavior unchanged on pre-26	✅	✅	✅	✅	❌ (rebuilds appearance every call)
Build clean iOS + Catalyst	✅ (already in repo)	✅	✅	✅	✅
Regression test added	❌	❌	❌	❌	❌
Scope minimal & surgical	✅	✅	✅	✅	⚠️ (touches default-init path)

Discussion

pr (raw PR). Two blocking problems. (1) The IsIOSVersionAtLeast(26) guard does not fire on MacCatalyst, yet both linked issues (#35380, #35381) are MacCatalyst 26 only — the PR effectively ships a no-op on the reported platform. (2) Even when the guard does fire (iOS 26), UITabBar.BackgroundColor writes to a layer that sits behind the Liquid Glass material and produces a blended/desaturated result that the system can repaint on trait/rotation changes. Also no round-trip on clear. Rank: last.

try-fix-2. Fixes only defect #1 (adds || IsMacCatalystVersionAtLeast(26)). Keeps the wrong API and the lack of round-trip. Better than pr because it at least runs on the reported platform, but the rendered color is still subject to Liquid Glass override. Rank: 4th.

try-fix-3. Correct outcome (opaque appearance on 26+, default elsewhere) but achieves it by allocating a fresh UITabBarAppearance on every call regardless of OS, dropping the prior _tabBarAppearance == null guard. That changes behavior on all OS versions (any per-call mutations not re-applied here will be lost) and broadens the blast radius unnecessarily. Belongs in a separate refactor PR. Rank: 3rd.

try-fix-1 and pr-plus-reviewer. Functionally identical diffs: keep the _tabBarAppearance == null guard, on 26+ call ConfigureWithOpaqueBackground() + clear BackgroundEffect, then set BackgroundColor; round-trip via ConfigureWithDefaultBackground() when the user clears the color. Surgical, Apple-sanctioned, behavior unchanged on pre-26.

Tiebreak: pr-plus-reviewer vs try-fix-1

Same diff. Preference goes to pr-plus-reviewer because:

1. It preserves attribution to the PR author (Shalini-Ashokan / Syncfusion partner) — the recommended path is "improve this PR" not "replace this PR".
2. It's the natural outcome of the standard review-and-iterate workflow: post the four inline findings, author applies them, PR merges.
3. There is no functional benefit to abandoning the PR for try-fix-1 when the corrected PR is identical code.

Final ranking

1. pr-plus-reviewer ← winner
2. try-fix-1 (functionally tied; pick on attribution/workflow grounds above)
3. try-fix-3
4. try-fix-2
5. pr

Outstanding work for whichever candidate ships

• Author a device-test regression in src/Controls/tests/DeviceTests/Elements/Shell/ShellTabBarTests.cs that builds a Shell with Shell.TabBarBackgroundColor = Colors.Red, snapshots the tab bar region, samples a pixel, asserts on the rendered color (not the appearance object), and exercises clear-to-null. Run on both iOS and MacCatalyst legs.
• Re-validate on real MacCatalyst 26 hardware — the screenshots/videos attached to the PR cannot have come from a code path that never fires on Catalyst.
• Consider a follow-up audit of SearchBarExtensions.cs (lines 156/183/217) and SliderExtensions.cs:80, which share the same one-sided IsIOSVersionAtLeast(26) pattern.

---

[Shalini-Ashokan]

Gate Failed:
The test is already present in the main source, as mentioned in the PR template.

Concern 1: Wrong OS check — IsIOSVersionAtLeast(26) is missing the MacCatalyst guard
This is not valid. OperatingSystem.IsIOSVersionAtLeast(26) works correctly for both iOS and Mac. Therefore, I did not add a separate condition for Mac.

Concern 2: UITabBar.BackgroundColor is fragile — no symmetric "unset" path
We removed the reset else block because it was causing other issues.

Concern 3: ConfigureWithDefaultBackground() interaction — opaque background not used
This is not needed because we are only setting a shell background.