1. Home
  2. Docs
  3. Controls and Facades
  4. NativeWebView

NativeWebView

NativeWebView is the embedded browser control for Avalonia. It derives from NativeControlHost and resolves the active platform backend either from an explicitly supplied backend or from NativeWebViewRuntime.

Current repo runtime status: the embedded native host path is implemented on Windows, macOS, and Linux in the default desktop build. Linux uses a GTK3/WebKitGTK child host on X11. iOS and Android runtime support comes from their platform-targeted backend assemblies rather than the default net10.0 contract build, and Browser support comes from the browser-targeted backend assembly. Browser uses Avalonia Browser native hosting plus an embedded iframe; navigation is real, but script execution and window.chrome.webview-style messaging are limited by same-origin browser security rules. Use NativeWebViewPlatformImplementationStatusMatrix.Get(...) when you need the honest current repo status for the current app build.

Companion surfaces are available when embedding is not the right fit: NativeWebDialog for desktop popup windows and WebAuthenticationBroker for auth callback flows.

Core Capabilities

  • Navigation lifecycle and history state.
  • Script execution and web message posting.
  • Feature toggles for DevTools, context menu, status bar, and zoom controls where supported.
  • Printing and print UI where supported.
  • Cookie manager and command manager access where supported.
  • Favicon change notifications and favicon byte retrieval where supported, including raw SVG assets through the Original format.
  • Download queue access where supported.
  • Native handle interop.
  • Airspace-mitigation render modes: Embedded, GpuSurface, and Offscreen.

Key Properties

Property Purpose
Source, CurrentUrl Current navigation target and current URL.
IsInitialized Indicates whether backend initialization completed.
InstanceConfiguration Per-instance environment/controller defaults, including proxy and storage directories.
CanGoBack, CanGoForward Navigation history state.
IsDevToolsEnabled, IsContextMenuEnabled, IsStatusBarEnabled, IsZoomControlEnabled Capability-backed runtime toggles.
ZoomFactor, HeaderString, UserAgentString Backend behavior configuration.
RenderMode, RenderFramesPerSecond Render strategy and frame pump rate for composited modes.
IsUsingSyntheticFrameSource, RenderDiagnosticsMessage, RenderStatistics Composition diagnostics and capture statistics.
MacOsCompositedPassthroughOverride Manual passthrough override for macOS composited mode.

Main Methods

  • InitializeAsync
  • Navigate, Reload, Stop, GoBack, GoForward
  • ExecuteScriptAsync
  • PostWebMessageAsJsonAsync, PostWebMessageAsStringAsync
  • OpenDevToolsWindow
  • PrintAsync, ShowPrintUiAsync
  • GetFaviconAsync
  • TryGetDownloadManager
  • SetZoomFactor, SetUserAgent, SetHeader
  • TryGetCommandManager, TryGetCookieManager
  • MoveFocus
  • SupportsRenderMode
  • SetCompositedPassthroughOverride
  • CaptureRenderFrameAsync, SaveRenderFrameAsync, SaveRenderFrameWithMetadataAsync
  • GetRenderStatisticsSnapshot, ResetRenderStatistics
  • TryGetPlatformHandle, TryGetViewHandle, TryGetControllerHandle

Main Events

Starting with 12.0.4.9, check Features.Supports(NativeWebViewFeature.NavigationCancellation) before relying on navigation interception. Windows and embedded macOS advertise this capability; macOS dialog and authentication-broker instances do not advertise it.

Set NavigationStarted event arguments' Cancel property synchronously in the handler. Posting a decision to the UI dispatcher or awaiting work in the handler cannot cancel a navigation that has already been allowed. Attach handlers before calling Navigate. On embedded macOS, both WebKit policy callback variants honor the decision exactly once; subscriber failures, disposal and superseded requests cancel the affected navigation. Subframe loads do not raise page-navigation events; handle popups separately through NewWindowRequested.

Terminal browser-process failures on Windows and embedded macOS are reported through NavigationCompleted with IsSuccess = false and Error = "browser-process-failed". Applications should cancel pending browser operations or offer recovery rather than waiting indefinitely for an authentication redirect.

Embedded macOS messaging and state

The page bridge supports window.chrome.webview.postMessage, addEventListener("message", handler) and removeEventListener("message", handler). PostWebMessageAsJsonAsync delivers parsed JSON in the listener's event.data; PostWebMessageAsStringAsync delivers a string. Host messages are not echoed back as managed WebMessageReceived events. JSON is decoded as data, including properties named __proto__.

The macOS native view must be attached before host-to-page messaging; otherwise the operation throws InvalidOperationException. Cancellation and disposal are honored. Each document owns its listeners; register them again after a new document loads.

Source, CurrentUrl, CanGoBack and CanGoForward reflect the retained WKWebView. Reattaching a presenter preserves its document and history without restarting the current navigation. Read control/native state on the UI thread; applications that need background access should publish a snapshot. IsContextMenuEnabled is applied to both newly created and retained native views.

Event list

  • Initialization: CoreWebView2Initialized, CoreWebView2EnvironmentRequested, CoreWebView2ControllerOptionsRequested
  • Browser state: StatusTextChanged, ZoomFactorChanged, FaviconChanged
  • Navigation: NavigationStarted, NavigationCompleted, NavigationHistoryChanged
  • Favicons: FaviconChanged
  • Downloads: DownloadStarting, DownloadStarted, DownloadChanged, DownloadCompleted
  • Messaging and interception: WebMessageReceived, NewWindowRequested, WebResourceRequested, ContextMenuRequested
  • Window integration: RequestCustomChrome, RequestParentWindowPosition, BeginMoveDrag, BeginResizeDrag, DestroyRequested
  • Rendering: RenderFrameCaptured

Unsupported Operations

Backends advertise support through Features. When a backend does not support an operation, capability flags expose that in advance and the method call throws PlatformNotSupportedException if invoked anyway.

Features describe platform capability contracts. They are not a substitute for NativeWebViewPlatformImplementationStatusMatrix when you need to know whether this repository already ships a real native host path for the current target.

Typical Initialization Pattern

NativeWebViewRuntime.EnsureCurrentPlatformRegistered();
WebViewControl.InstanceConfiguration.EnvironmentOptions.UserDataFolder = "./artifacts/webview-a";
WebViewControl.InstanceConfiguration.ControllerOptions.ProfileName = "webview-a";
await WebViewControl.InitializeAsync();
WebViewControl.Navigate("https://example.com");

Render Diagnostics

Use composited-mode diagnostics when you need capture telemetry or airspace investigation:

  • IsUsingSyntheticFrameSource
  • RenderDiagnosticsMessage
  • RenderStatistics
  • GetRenderStatisticsSnapshot
  • CaptureRenderFrameAsync
  • SaveRenderFrameWithMetadataAsync
  • ResetRenderStatistics

Render statistics expose capture counters and last-frame metadata, including attempt, success, failure, and skip counts together with last failure details.

Sidecar metadata includes FrameId, CapturedAtUtc, RenderMode, Origin, PixelDataLength, and PixelDataSha256. Use NativeWebViewRenderFrameMetadataSerializer.ReadFromFileAsync to load the sidecar JSON and TryVerifyIntegrity to validate captured frames against the stored integrity fields.

Favicon Notes

  • Check Features.Supports(NativeWebViewFeature.Favicon) before calling GetFaviconAsync.
  • GetFaviconAsync(NativeWebViewFaviconFormat.Original) returns raw favicon bytes when available. SVG favicons are returned as image/svg+xml bytes and are not rasterized by the control.
  • Windows uses WebView2 favicon APIs for PNG/JPEG and downloads the favicon URI for SVG originals. Linux and iOS resolve declared document favicon links and download the resolved URI. Android uses native bitmap callbacks for PNG/JPEG and document-link resolution for SVG originals.
  • Browser targets do not currently advertise favicon support because cross-origin iframe restrictions make document favicon discovery unreliable.

Download Notes

  • Check Features.Supports(NativeWebViewFeature.Downloads) or TryGetDownloadManager before showing download UI.
  • Downloads are currently advertised by the Windows and Linux desktop backends. macOS, mobile, and browser targets do not advertise downloads in this repo version.
  • DownloadStarting is raised before the transfer starts. Use GetDeferral() when showing an async save-location picker, then set DestinationPath or set Cancel = true.
  • The download manager keeps an in-memory queue per view instance. Items remain available after completed, canceled, or failed states until the manager is cleared or the owning view is disposed.
  • Use immutable NativeWebViewDownloadSnapshot values from DownloadStarted, DownloadChanged, and DownloadCompleted to update UI. Snapshots include URI, suggested filename, destination, state, bytes, progress, transfer rate, timestamps, error details, and action capability flags.
  • Windows maps to WebView2 download operations and supports progress, completion/failure, cancel, and native pause/resume when WebView2 reports those actions as available.
  • Linux maps to WebKitGTK download signals and supports destination selection, progress, completion/failure, and cancel. Native pause/resume is not available.
  • Restart is intentionally not advertised in this iteration because the programmatic restart pipeline is not yet reliable across backends.

Proxy Notes

  • Check NativeWebViewPlatformImplementationStatusMatrix.Get(platform) before assuming the current target has a real embedded runtime path.
  • Check Features.Supports(NativeWebViewFeature.ProxyConfiguration) before relying on runtime proxy application.
  • In the current repo implementation, per-instance proxy application is effective on the embedded Windows and Linux NativeWebView controls, on macOS 14+, and on iOS 17+ when the iOS backend is built with the .NET 8 Apple workload.
  • The macOS runtime path supports explicit http, https, and socks5 proxy servers plus bypass domains.
  • The iOS runtime path supports explicit http, https, and socks5 proxy servers, credentials, and bypass domains on iOS 17+.
  • The Windows runtime path applies proxy settings through WebView2 AdditionalBrowserArguments.
  • The Linux runtime path applies explicit proxy settings through WebKitGTK website data manager settings on X11.
  • The Android runtime path is real, but Android proxy override remains app-wide and is not applied per WebView instance by this repo.
  • The Browser runtime path is real, but browser security rules still apply: pages may refuse framing, and cross-origin pages cannot be script-driven through the embedded iframe host.
  • Proxy.AutoConfigUrl is not applied by the current Apple runtime integrations in this repo.

Direct connections

Set InstanceConfiguration.EnvironmentOptions.Proxy = new NativeWebViewProxyOptions { NoProxy = true } before initialization/showing. Do not combine it with a server, PAC URL, or bypass list. See NoProxy for platform support and profile behavior.