1. Home
  2. Docs
  3. Getting Started
  4. Overview

Getting Started with NativeWebView

NativeWebView is split into a small set of focused packages so you can compose only the browser surface you need:

  • NativeWebView: Avalonia NativeControlHost surface for embedding the native browser view.
  • NativeWebView.Core: controller layer, diagnostics, capability model, and backend abstractions.
  • NativeWebView.Dialog: dialog/window facade for desktop browser windows.
  • NativeWebView.Auth: authentication broker facade for OAuth and sign-in flows.
  • NativeWebView.Interop: native handle contracts and interop structs.
  • NativeWebView.Platform.*: platform registrations and backend implementations.

What You Will Build

By the end of this section you will have:

  • An Avalonia window hosting NativeWebView.
  • Platform backend registration for the current runtime.
  • Runtime readiness checks before first navigation.
  • A working choice between Embedded, GpuSurface, and Offscreen render modes.
  • Clear handoff points to NativeWebDialog for desktop popup windows and WebAuthenticationBroker for auth callback flows.
  1. Installation
  2. Quickstart
  3. Render Modes
  4. Platform Notes
  5. Platform Prerequisites

Pick the Right Integration Path

Choose the primary surface first:

  • Use NativeWebView when the browser must live inside an Avalonia layout.
  • Use NativeWebDialog when the browser should live in a separate desktop window on Windows, macOS, or Linux.
  • Use WebAuthenticationBroker when the main goal is an auth callback flow. The repo now ships runtime implementations across Windows, macOS, Linux, iOS, Android, and Browser.

Mobile and workload-specific note: the iOS and Android runtime paths come from their platform-targeted backend assemblies rather than the default net8.0 contract build. Browser authentication is popup-based and does not provide NativeWebDialog.

Choose the render mode next:

  • Embedded: best native fidelity and input behavior.
  • GpuSurface: composited capture path for reduced airspace issues while staying GPU-backed.
  • Offscreen: fully managed composition path for overlays, captures, and host-controlled layering.

Operational Model

NativeWebView assumes startup validation is part of the application contract:

  1. Register the current platform backend.
  2. Read diagnostics for the target platform.
  3. Fail fast on blocking issues.
  4. Create and initialize the control or facade.
  5. Enable optional CI/reporting scripts when shipping packages.

Next