[Windows] Fix WebView background color not being applied

[SubhikshaSf4851]

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 whether this change resolves your issue. Thank you!

Root Cause :

The root cause was the absence of a proper property mapping and update mechanism for the Background property in the Windows WebViewHandler. As a result, the MAUI WebView.Background value was never applied to the native WebView2, leading to the inability to override the background color.

Description of Change

WebView background color support (Windows):

• Added a new internal method MapBackground in WebViewHandler.Windows.cs to map the Background property for WebView controls. This method calls a new extension method to update the background color on the platform view.
• Registered the Background property mapping in the handler's property mapper for Windows in WebViewHandler.cs.
• Implemented the UpdateBackground extension method in WebViewExtensions.cs to set the DefaultBackgroundColor of the Windows WebView2 control based on the provided Background value, and to adjust the preferred color scheme accordingly.
• Ensured the background color is updated when the WebView2 control is initialized in WebViewHandler.Windows.cs.

Testing:

• Added a new test page (Issue34518.cs in TestCases.HostApp) to demonstrate and verify that the background color of a WebView can be set to green on Windows.
• Added a corresponding UI test (Issue34518.cs in TestCases.Shared.Tests) to validate that the background color is correctly applied.

Issues Fixed

Fixes #34518

Tested the behavior on the following platforms

• Windows
• Android
• iOS
• Mac

Before Issue Fix	After Issue Fix

[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://github.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 34599

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

This PR addresses a Windows-specific regression where WebView.Background was not being applied to the native WinUI WebView2, preventing apps from overriding the WebView background (notably in dark mode).

Changes:

• Adds a Windows Background property mapping for WebViewHandler and applies it to WebView2.DefaultBackgroundColor.
• Updates the Windows WebView initialization path to apply the background once CoreWebView2 is initialized.
• Adds an issue page + UI screenshot test (with Android/iOS baselines) for verifying background application.

Reviewed changes

Copilot reviewed 5 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/Core/src/Platform/Windows/WebViewExtensions.cs	Introduces UpdateBackground for WebView2 and adjusts color scheme behavior.
src/Core/src/Handlers/WebView/WebViewHandler.cs	Registers the Windows property mapping for background.
src/Core/src/Handlers/WebView/WebViewHandler.Windows.cs	Adds MapBackground and applies background during CoreWebView2 initialization.
src/Controls/tests/TestCases.HostApp/Issues/Issue34518.cs	Adds a repro page setting a green WebView.BackgroundColor.
src/Controls/tests/TestCases.Shared.Tests/Tests/Issues/Issue34518.cs	Adds a screenshot-based UI test for background color.
src/Controls/tests/TestCases.Android.Tests/snapshots/android/WebViewBackgroundColorShouldBeApplied.png	Adds Android screenshot baseline for the new test.
src/Controls/tests/TestCases.iOS.Tests/snapshots/ios/WebViewBackgroundColorShouldBeApplied.png	Adds iOS screenshot baseline for the new test.

[sheiksyedm]

/azp run maui-pr-uitests

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[MauiBot]

🚦 Gate — Test Verification

📊 Expand Full Gate — 7f9e780 · Resolve test failures

---

Gate Result: ✅ PASSED

Platform: WINDOWS

Tests Detected

#	Type	Test Name	Filter
1	UITest	Issue34518	Issue34518

Verification

Step	Expected	Actual	Result
Without fix	FAIL	FAIL	✅
With fix	PASS	PASS	✅

Details

• ❌ Failed: WebViewBackgroundColorShouldBeApplied [5 s]
• 📋 Error: VisualTestUtils.VisualTestFailedException :
  Snapshot different than baseline: WebViewBackgroundColorShouldBeApplied.png (26.16% difference)
  If the correct baseline has changed (this isn't a a bug),...

Fix Files Reverted

• eng/pipelines/ci-copilot.yml
• src/Core/src/Handlers/WebView/WebViewHandler.Windows.cs
• src/Core/src/Handlers/WebView/WebViewHandler.cs
• src/Core/src/Platform/Windows/WebViewExtensions.cs

---

Base Branch: main | Merge Base: 720a9d4

---

[MauiBot]

🤖 AI Summary

📊 Expand Full Review — 7f9e780 · Resolve test failures

---

🔍 Pre-Flight — Context & Validation

---

Issue: #34518 - WebView background color has changed after update, can't override
PR: #34599 - [Windows] Fix WebView background color not being applied
Platforms Affected: Windows (primary); snapshot baselines added for Android, iOS, iOS-26, Mac, Windows
Files Changed: 3 implementation (WebViewHandler.Windows.cs, WebViewHandler.cs, WebViewExtensions.cs), 7 test/snapshot files

Key Findings

• Root bug (Issue WebView background color has changed after update, can't override. #34518): On Windows, WebView2 in dark mode shows a black background and BackgroundColor="White" can't override it. WebViewHandler had no property mapper for Background on Windows.
• PR fix: Adds [nameof(IView.Background)] = MapBackground (Windows-only #if WINDOWS) to WebViewHandler.cs, implements internal static void MapBackground in WebViewHandler.Windows.cs, and adds UpdateBackground extension in WebViewExtensions.cs.
• UpdateBackground behavior: Sets WebView2.DefaultBackgroundColor from SolidPaint or GradientPaint.StartColor. Forces PreferredColorScheme.Light when any background is set; resets to Auto when background is null.
• PreferredColorScheme.Light always forced (🚨 critical): Regardless of whether the set color is dark or light, the code forces Light color scheme. A dark BackgroundColor (e.g., Colors.Black) would still force Light scheme for web content, breaking prefers-color-scheme: dark media queries. Author's rationale: choosing Dark makes WebView2's dark-mode rendering override DefaultBackgroundColor. This argument applies only when a LIGHT background is set; forcing Light for ALL colors is overly broad.
• DefaultBackgroundColor not reset in else branch (⚠️ correctness bug): Prior reviewer suggested adding platformWebView.DefaultBackgroundColor = Colors.Transparent.ToWindowsColor() in the else branch; author responded "I have updated the suggestion" but the code on disk still lacks this reset. The thread was marked outdated (possibly due to a new commit that didn't fully apply the fix).
• TODO: Make it public in .NET 11. comment: No tracking issue/link. Thread resolved without fix applied.
• PlatformAffected.UWP in test: Should be PlatformAffected.Windows for .NET MAUI on Windows.
• Snapshots: All 4 platform baselines now present (Android, Mac, WinUI, iOS, iOS-26) — this was missing in the prior review and is now fixed.
• Prior agent review (same PR, 2026-03-27): Gate failed at that time; agent ran 4 try-fix attempts (all passing); recommended REQUEST CHANGES. Gate now ✅ PASSED after snapshot updates.
• iOS already has MapBackground: WebViewHandler.cs line 37 has [nameof(IWebView.Background)] = MapBackground for iOS — the Windows addition is correctly guarded with #if WINDOWS.

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
PR	PR #34599	Add MapBackground/UpdateBackground using DefaultBackgroundColor + PreferredColorScheme.Light always when color set	✅ PASSED (Gate)	WebViewHandler.Windows.cs, WebViewHandler.cs, WebViewExtensions.cs	Gate passes; code quality issues remain (forced Light, missing reset, TODO, PlatformAffected)

---

🔧 Fix — Analysis & Comparison

---

Fix Candidates

#	Source	Approach	Test Result	Files Changed	Notes
1	try-fix (claude-opus-4.6)	Luminance-based PreferredColorScheme (BT.601) + DefaultBackgroundColor transparent reset in else branch + remove TODO	✅ PASS	WebViewExtensions.cs, WebViewHandler.Windows.cs, WebViewHandler.cs	More correct color scheme selection; proper reset; removes TODO
2	try-fix (claude-sonnet-4.6)	DefaultBackgroundColor only — no PreferredColorScheme changes; reset to transparent in else branch	✅ PASS	WebViewExtensions.cs, WebViewHandler.Windows.cs, WebViewHandler.cs	Simplest approach; zero CSS media-query side-effects
3	try-fix (gpt-5.3-codex)	DefaultBackgroundColor + CSS injection via AddScriptToExecuteOnDocumentCreatedAsync	✅ PASS	WebViewExtensions.cs, WebViewHandler.Windows.cs, WebViewHandler.cs	Most robust for opaque HTML; no PreferredColorScheme changes
4	try-fix (gpt-5.4)	Fix in shared ViewExtensions.UpdatePlatformViewBackground pipeline, special-casing WebView2	✅ PASS	ViewExtensions.cs, WebViewExtensions.cs	Most principled — fixes shared pipeline; fewer WebView-specific files
PR	PR #34599	DefaultBackgroundColor + PreferredColorScheme.Light always forced when color set	✅ PASSED (Gate)	WebViewHandler.Windows.cs, WebViewHandler.cs, WebViewExtensions.cs	Gate passes; PreferredColorScheme.Light forced for ALL colors; missing DefaultBackgroundColor reset; TODO comment without tracking

Cross-Pollination

Model	Round	New Ideas?	Details
claude-opus-4.6	2	NO NEW IDEAS	All structural approaches covered (DefaultBackgroundColor, luminance, CSS injection, shared pipeline)
claude-sonnet-4.6	2	NO NEW IDEAS	Confirmed exhausted

Exhausted: Yes
Selected Fix: Attempt 2 (DefaultBackgroundColor-only + transparent reset) — Simplest minimal change; removes the forced PreferredColorScheme.Light side-effect entirely; adds missing DefaultBackgroundColor reset; leaves web content prefers-color-scheme media queries unaffected. The PR author should adopt this approach in WebViewExtensions.cs.

---

📋 Report — Final Recommendation

---

⚠️ Final Recommendation: REQUEST CHANGES

Phase Status

Phase	Status	Notes
Pre-Flight	✅ COMPLETE	Issue #34518, Windows WebView2 background color
Gate	✅ PASSED	Windows — tests fail without fix, pass with fix
Try-Fix	✅ COMPLETE	4 attempts, all 4 passing; gemini-3-pro-preview unavailable, substituted gpt-5.4
Report	✅ COMPLETE

Summary

PR #34599 correctly identifies the root cause and adds the right infrastructure (MapBackground + UpdateBackground using WebView2.DefaultBackgroundColor) to fix Windows WebView background color. The Gate passes. However, the UpdateBackground implementation has a correctness issue (PreferredColorScheme.Light forced for all background colors) and a missing reset (DefaultBackgroundColor not cleared in else branch). Four independent alternatives all pass, with the simplest (DefaultBackgroundColor-only) being the recommended fix. The PR author should update WebViewExtensions.cs before merging.

Root Cause

WebView2 does not inherit from WinUI Control, so the standard ViewHandler.MapBackground pipeline never reaches it. WebView2.DefaultBackgroundColor is the correct API to set the pre-render background. The fix correctly adds a Windows-specific IView.Background mapper to WebViewHandler.

Fix Quality

What the PR gets right:

• ✅ Correct mapper registration: [nameof(IView.Background)] = MapBackground inside #if WINDOWS
• ✅ Correct API: WebView2.DefaultBackgroundColor
• ✅ Calls UpdateBackground in OnCoreWebView2Initialized (re-applies after async WebView2 init)
• ✅ Handles both SolidPaint and GradientPaint (best-effort for gradient)
• ✅ Tests added with baseline snapshots for all 4 platforms (Android, iOS, iOS-26, Mac, Windows)
• ✅ PlatformAffected.UWP is correct — the PlatformAffected enum has no Windows member; UWP is the established convention for Windows in this codebase

Issues requiring changes:

1. PreferredColorScheme.Light always forced (🚨 correctness issue):

   // Current (PROBLEMATIC):
   platformWebView.CoreWebView2.Profile.PreferredColorScheme = CoreWebView2PreferredColorScheme.Light;
   // Forces ALL web content into Light mode whenever ANY background color is set,
   // even dark colors (Colors.Black). Web apps using `prefers-color-scheme: dark`
   // CSS media queries will have their dark-mode styles suppressed.

   Recommended fix: Remove PreferredColorScheme changes entirely (Attempt 2 approach). DefaultBackgroundColor works independently of PreferredColorScheme — the color scheme setting affects how web content renders, not whether the background color property is respected.

   // Recommended UpdateBackground in WebViewExtensions.cs:
   internal static void UpdateBackground(this WebView2 platformWebView, IWebView webView)
   {
       Color? backgroundColor = null;
       if (webView.Background is SolidPaint solidPaint)
           backgroundColor = solidPaint.Color;
       else if (webView.Background is GradientPaint gradientPaint)
           backgroundColor = gradientPaint.StartColor;
   
       platformWebView.DefaultBackgroundColor = backgroundColor is not null
           ? backgroundColor.ToWindowsColor()
           : Colors.Transparent.ToWindowsColor();
   }

2. DefaultBackgroundColor not reset in else branch (⚠️ correctness bug):
   The current else branch only resets PreferredColorScheme but leaves DefaultBackgroundColor at a stale previously-set color if the developer later clears their BackgroundColor. The recommended fix above addresses this unconditionally.

3. TODO: Make it public in .NET 11. comment without tracking issue (🔧 minor):

   //TODO: Make it public in .NET 11.
   internal static void MapBackground(IWebViewHandler handler, IWebView webView)

   Either remove this comment or replace with a linked GitHub issue. Version-targeted TODOs without tracking issues create dead-end comments.

Best Alternative Found

Attempt 2 (DefaultBackgroundColor-only, claude-sonnet-4.6): Same 3-file structure as the PR, but removes all PreferredColorScheme logic and properly resets DefaultBackgroundColor to transparent in the else branch. Minimal delta from current code, zero side-effects on CSS media queries. This is the recommended path for the PR author.

Selected Fix: Attempt 2 — simpler, more correct, and leaves web content rendering unaffected.

---

[kubaflo]

Could you please review the AI's summary?

[SubhikshaSf4851]

@kubaflo I have reviewed the recommended Attempt 2, which sets the background color to Transparent when the color is null. I verified that applying Transparent causes the WebView to inherit the platform default, which is due to a known WinUI issue microsoft/microsoft-ui-xaml#6527