MAUI Handler not working with Custom WebView and showing blank white screen.

Hello @Sushma Vaddepally (OSV) ,

Thanks for your time troubleshooting in this thread.

For anyone else who may be experiencing this issue, it will be addressed in MAUI SR7, which is expected to be released on May 12, 2026.

Github link

For more information, you can refer to the official release notes or announcements from the MAUI team.

But if you have any questions or need further assistance, please feel free to ask.

I hope this information helps. If my response was informative, please consider leaving a feedback following this guidance

Thank you for your understanding and patience as we work to resolve this issue.

Hi @Sushma Vaddepally (OSV) ,

Thanks for reaching out.

I have tested a simple .NET MAUI 9 app that demonstrates how to properly load a URL with custom headers in a WebView on Android, without getting a blank white screen. You can refer this code example below.

File Android/Handler/CustomWebViewHandler.cs

#if ANDROID
using Android.Webkit;
using Microsoft.Maui.Handlers;
using Microsoft.Maui.Platform;

namespace CustomWebViewDemo;

public partial class CustomWebViewHandler : WebViewHandler
{
    protected override void ConnectHandler(Android.Webkit.WebView platformView)
    {
        base.ConnectHandler(platformView);

        platformView.Settings.JavaScriptEnabled = true;
        platformView.Settings.DomStorageEnabled = true;

        var customView = VirtualView as CustomWebView;
        var headers = customView?.Headers ?? new Dictionary<string, string>();

        platformView.SetWebViewClient(new CustomWebViewClient(this, headers));
    }
}

public class CustomWebViewClient : MauiWebViewClient
{
    private readonly Dictionary<string, string> _headers;

    public CustomWebViewClient(WebViewHandler handler, Dictionary<string, string> headers)
        : base(handler)
    {
        _headers = headers;
    }

    public override bool ShouldOverrideUrlLoading(Android.Webkit.WebView view, IWebResourceRequest request)
    {
        var url = request.Url?.ToString();

        if (_headers.Count > 0)
        {
            view.LoadUrl(url, _headers);
        }
        else
        {
            view.LoadUrl(url);
        }

        return true;
    }
}
#endif

File CustomWebView.cs (in root)

namespace CustomWebViewDemo
{
    public class CustomWebView : WebView
    {
        public static readonly BindableProperty HeadersProperty = BindableProperty.Create(nameof(Headers), typeof(Dictionary<string, string>), typeof(CustomWebView));

        public Dictionary<string, string> Headers
        {
            get => (Dictionary<string, string>)GetValue(HeadersProperty);
            set => SetValue(HeadersProperty, value);
        }
    }
}

Hope this helps. If you found my response helpful or informative, I would greatly appreciate it if you could follow this guidance provide feedback.

Thank you.

On Android in .NET MAUI, a blank WebView plus ShouldOverrideUrlLoading not being hit usually indicates that the native WebViewClient/handler isn’t wired the way it was in the old renderer model, or that navigation is being short‑circuited by always returning true.

Key points and fixes:

1. Do not always return true from ShouldOverrideUrlLoading

Returning true tells Android: “this navigation is handled manually; do not continue with the default load.”

In the current code:

public override bool ShouldOverrideUrlLoading(Android.Webkit.WebView view, IWebResourceRequest request)
{
    string url = request.Url.ToString();

    if (_headerParams.Count > 0)
    {
        view.LoadUrl(url, _headerParams);
    }
    else
    {
        view.LoadUrl(url);
    }

    return true; // <- blocks default navigation
}

If this method is not called for the initial navigation, the WebView never loads anything and stays white. When it is called and you also call LoadUrl from inside it, returning true can cause re‑entry and loops.

Typical pattern:

• Return false when the URL should be handled by the WebView itself.
• Return true only when handling the URL externally (e.g., opening system browser) and not calling LoadUrl again on the same WebView.

For header injection, consider:

public override bool ShouldOverrideUrlLoading(Android.Webkit.WebView view, IWebResourceRequest request)
{
    var url = request.Url.ToString();

    if (_headerParams.Count > 0)
    {
        view.LoadUrl(url, _headerParams);
        return true; // handled once, do not re‑enter
    }

    return false; // let WebView proceed normally when no headers
}

Then ensure the first navigation is either:

• Started with LoadUrl(url, _headerParams) from outside ShouldOverrideUrlLoading, or
• Allowed to proceed with return false so the WebView can render.

2. Avoid calling ShouldOverrideUrlLoading manually

Calling this method from OnPageStarted causes the infinite loop:

• LoadUrl → triggers navigation → OnPageStarted → calls ShouldOverrideUrlLoading → LoadUrl again → repeat.

ShouldOverrideUrlLoading is a callback for the WebView; it should not be invoked manually. Remove any manual calls from OnPageStarted or other events.

3. Ensure the custom client/handler is actually attached

In MAUI handlers, the custom Android WebViewClient must be set on the native control inside the handler’s ConnectHandler/OnConnect equivalent. If the default client is still in place, the override will never fire and the WebView stays blank.

Verify that:

• The custom handler is registered for WebView in MauiProgram.
• Inside the handler, PlatformView.SetWebViewClient(new YourCustomClient(...)); (or equivalent) is called so that ShouldOverrideUrlLoading belongs to the active client.

4. Respect MAUI/WebView lifecycle on Windows (if testing cross‑platform)

On Windows, WebView2 is stricter about when navigation can start. If the same page is blank on Windows when created dynamically, ensure the WebView is fully attached to the visual tree before setting Source or calling LoadUrl, for example by deferring navigation until after the control is loaded.

5. Check for _blank/multiple windows behavior

If the target URL uses links with target="_blank", Android WebView in MAUI will not navigate unless OnCreateWindow is implemented or multiple windows are disabled. To force links to open in the same WebView, disable multiple windows in the handler:

#if ANDROID
Microsoft.Maui.Handlers.WebViewHandler.Mapper.AppendToMapping("SupportMultipleWindows", (handler, view) =>
{
    handler.PlatformView.Settings.SetSupportMultipleWindows(false);
});
#endif

This prevents navigation attempts that would otherwise fail silently and appear as a white screen.

Summary of changes to try:

1. Remove any manual calls to ShouldOverrideUrlLoading (especially from OnPageStarted).
2. Only return true from ShouldOverrideUrlLoading when explicitly handling the navigation and not re‑calling LoadUrl for the same request; otherwise return false.
3. Ensure the custom WebViewClient is actually set on the native WebView in the MAUI handler.
4. If links use target="_blank", disable multiple windows as shown above.

References:

• WebView (devices-android)
• WebView with remote url on windows not loading - Microsoft Q&A
• Maui Android web handler - Microsoft Q&A