Put a .NET MAUI app on the web

Overview #

MauiWeb runs your .NET MAUI app on an ASP.NET Core server and sends the browser real HTML. Every browser tab gets its own instance of your app, and MauiWeb's handlers turn each control into HTML.

The first request returns the finished page. After that, a WebSocket carries the visitor's taps and typing to your app and brings back only the parts of the page that changed. There is no WebAssembly to download and no splash screen.

How it works #

Every visitor gets their own instance of your MAUI app on the server. MauiWeb's handlers turn each control into HTML, and a small script in the page keeps the two in step.

Requirements #

• .NET 11 SDK and .NET MAUI 11. MauiWeb is built and tested on MAUI 11 release candidate 2; .NET 9 and 10 are not supported.
• Your app's pages, view models and services in a project that can target plain net11.0, next to its phone targets.
• A host that runs ASP.NET Core and allows WebSockets. Linux, Windows and macOS all work.

Add a web project #

Create an ASP.NET Core project beside your app. It references your shared MAUI project and the MauiWeb package.

dotnet new web -n MyApp.Web
cd MyApp.Web
dotnet add package MauiWeb
dotnet add reference ../MyApp/MyApp.csproj

Then map MauiWeb in Program.cs. UseMauiWeb() replaces the native handlers with browser handlers; handlers you register after it still win, so your own controls can override any of them.

using MauiWeb.Hosting;

var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

app.MapMauiWeb(() => MauiProgram.CreateMauiApp(b => b.UseMauiWeb()), options =>
{
    options.Title = "My App";
    options.LicenseKey = builder.Configuration["MauiWeb:LicenseKey"];
});

app.Run();

Share your app #

Give CreateMauiApp a hook for the platform setup. Your phone heads call it as before; the web head passes UseMauiWeb().

public static class MauiProgram
{
    public static MauiApp CreateMauiApp(Action<MauiAppBuilder>? platform = null)
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts => fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular"));

        platform?.Invoke(builder);
        builder.Services.AddTransient<MainViewModel>();
        return builder.Build();
    }
}

Fonts, images and raw files are served from the web project's Resources folder. Copy them from the shared project at build time:

<ItemGroup>
  <None Include="..\MyApp\Resources\**" CopyToOutputDirectory="PreserveNewest"
        Link="Resources\%(RecursiveDir)%(Filename)%(Extension)" />
</ItemGroup>

Run it #

dotnet run --urls http://localhost:5280

Open http://localhost:5280. Every tab you open gets its own copy of your app. Reloading a tab, or a short network drop, reconnects to the same session for 45 seconds.

On localhost, private addresses and *.local, *.test, *.localhost and *.internal hosts, no license key is needed.

Options #

Set these in the second argument of MapMauiWeb.

Session isolation #

Every visitor always gets their own MauiApp: its own DI container, Application, windows and pages. What visitors can share is the process, and with it any static fields.

• None (default). All sessions share one process and one UI thread, like the windows of a desktop app. Fast and light. Use it when per-user state lives in pages, view models and scoped services.
• Process. Each session runs in its own copy of your app's process, so even static fields belong to one visitor. Use it for code written with a single user in mind, as phone apps often are.

app.MapMauiWeb(() => MauiProgram.CreateMauiApp(b => b.UseMauiWeb()), options =>
{
    options.Isolation = SessionIsolation.Process;
    options.WarmProcesses = 2;   // started ahead, so nobody waits for a boot
    options.MaxSessions = 50;    // most processes at once
});

Themes #

Controls come in two looks. "web" follows the shadcn/ui style that fits a website. "ios" follows iOS 26, with glass bars, for apps that should feel the same as on an iPhone. Both have light and dark versions and follow the visitor's system setting unless you set ColorScheme.

Compare them in the live gallery with the theme switch above the app.

Page addresses #

Give a page a web address when you register it with dependency injection. The address shows in the browser when the page is shown, works with the Back button, and opens the same page when someone shares or reloads the link, already in the first HTML, so search engines see it too.

using MauiWeb.Navigation;

builder.Services.AddWebPage<ShopPage>("shop");
builder.Services.AddWebPage<ProductPage, ProductViewModel>("shop/{id}/{slug?}");
builder.Services.AddWebPage<CartPage>("store/cart");          // a tab of a TabbedPage
builder.Services.AddWebPage<SettingsPage>("account/settings"); // a FlyoutPage section

The values in the address reach the view model the same way Shell passes query parameters, through IQueryAttributable. The view model gives its values back through IWebRouteValues, so the address follows what the page shows. A {slug} it doesn't supply is made from the page title.

public class ProductViewModel : IQueryAttributable, IWebRouteValues
{
    public int Id { get; private set; }

    // Address to page: "/shop/42" gives id = "42".
    public void ApplyQueryAttributes(IDictionary<string, object> query) =>
        Id = int.Parse((string)query["id"]);

    // Page to address: shown as "/shop/42/red-shoes" (the slug comes from the title).
    public IReadOnlyDictionary<string, object?> RouteValues =>
        new Dictionary<string, object?> { ["id"] = Id };
}

• Navigation stacks: pushing a registered page, with PushAsync or await WebNavigation.GoToAsync("shop/42"), shows its address. A link to /shop/42 opens the product with the shop below it, so Back stays in your app.
• Tabs: each registered tab page has its own address, and a link to it opens that tab. Switching tabs replaces the address instead of adding Back steps.
• Flyout: registered sections without values (account/settings) open as the detail; pages with values are pushed inside the section.
• Pages you don't register still get an address made from their title, but a link can't rebuild them.
• Registration uses generic types only, so it is safe for NativeAOT and trimming. On iOS and Android, AddWebPage is an ordinary DI registration.

See it live: stack, tabs, flyout.

Web platform-specifics #

Like Android's toolbar placement, On<Web>() sets options that only apply in the browser. The tab bar of a TabbedPage or Shell can sit where a website needs it.

using MauiWeb.PlatformConfiguration;
using MauiWeb.PlatformConfiguration.WebSpecific;

tabs.On<Web>().SetTabBarPlacement(WebTabBarPlacement.Navbar);
shell.On<Web>().SetTabBarPlacement(WebTabBarPlacement.Left);

HtmlView #

HtmlView puts raw HTML or a web component inside a MAUI layout. In the browser it is real inline HTML; on Android, iOS, Mac Catalyst and Windows the same HTML shows in a WebView that sizes itself to its content. DOM events you name are reported to C# on every platform.

using MauiWeb.Controls;

var view = new HtmlView
{
    Html = "<button id=\"buy\">Buy now</button>",
    Events = "click",
};
view.EventRaised += (s, e) =>
{
    if (e.Name == "click" && e.TargetId == "buy")
        Checkout();
};

Essentials #

MAUI Essentials APIs work through the visitor's browser, where the browser offers the feature and the visitor allows it. Preferences are saved in the visitor's browser and sent with every new session, so they survive reloads.

For WebAuthenticator, map the callback page that ends the sign-in: app.MapMauiWebAuthCallback(); (served at /_maui/auth-callback).

Add-ons #

.NET MAUI Community Toolkit

Package MauiWeb.Toolkit. Adds Popup, MediaElement, TouchBehavior, DrawingView, Snackbar, Toast and FileSaver.

SkiaSharp

Package MauiWeb.SkiaSharp. SKCanvasView and SKGLView are drawn on the server and sent as frames. Choose lossless WebP, PNG or lossy frames, the quality, and a frame-rate limit.

Maps

Package MauiWeb.Maps. The Map control uses Leaflet with OpenStreetMap tiles by default, or Google Maps when you set a key. Restrict a Google key to your site's address in the Google Cloud console: the browser receives it.

app.MapMauiWeb(() => MauiProgram.CreateMauiApp(b => b
    .UseMauiWeb()
    .UseMauiWebToolkit()
    .UseMauiWebSkiaSharp(skia => skia.MaxFps = 30)
    .UseMauiWebMaps(maps => maps.GoogleMapsApiKey = builder.Configuration["Maps:Key"])));

Custom handlers #

A handler builds a server-side DOM element for your control. Derive from WebViewHandler<TView, DomElement>: size, margin, background, transforms, visibility, alignment, semantics, shadow and clip are already handled.

using MauiWeb.Dom;
using MauiWeb.Handlers;

public class RatingHandler : WebViewHandler<RatingView, DomElement>
{
    public static readonly PropertyMapper<RatingView, RatingHandler> Mapper =
        new(WebViewHandler.ViewMapper)
        {
            [nameof(RatingView.Value)] = (h, v) => h.PlatformView.SetAttribute("data-value", v.Value.ToString()),
        };

    public RatingHandler() : base(Mapper) { }

    protected override DomElement CreatePlatformView() => new DomElement("div", "rating");

    // Each tap adds a star, then starts again after five.
    protected override void ConnectHandler(DomElement element) =>
        element.On("click", _ => VirtualView.Value = VirtualView.Value % 5 + 1);
}

Register it after UseMauiWeb(): builder.ConfigureMauiHandlers(h => h.AddHandler<RatingView, RatingHandler>()). The element API includes SetAttribute, SetStyle, AddClass, SetProperty, On for events and Document.InvokeAsync to call your own browser script.

Deploying #

A MauiWeb site is an ordinary ASP.NET Core app. Publish it as a single native binary with NativeAOT, so no .NET assemblies sit on the server.

dotnet publish -c Release -r linux-x64 -p:PublishAot=true

• Allow WebSockets on your proxy or platform, for /_maui/ws.
• Use sticky sessions when you run more than one instance: a visitor's socket must reach the instance that holds their app.
• Health check: GET /_maui/health answers ok sessions=….
• Behind a proxy, forward the original host and scheme so the license check sees your real domain.

License key #

A MauiWeb key lists the domains it covers, such as shop.example.com and www.shop.example.com. It is checked on your server, inside your app, so pages never wait for a license server.

export MAUIWEB_LICENSE_KEY="MW1.…"

On a live domain the key does not cover, visitors see an "Unlicensed MauiWeb" notice when the page opens, and again every few minutes after they close it. The site keeps working. The notice is drawn by the server, like any alert.

About once a day, in the background, your server tells our license service which licensed domain it runs on: the key's id, the domain and the MauiWeb version, nothing else. If the service can't be reached, nothing changes for a week; after that, visitors see a notice asking the site owner to let the server reach the internet, and the site keeps working. A domain you remove from your license, or a revoked key, shows the "Unlicensed MauiWeb" notice at the next check. To use a different address for the check, set MauiWebOptions.LicenseCheckUrl or MAUIWEB_LICENSE_CHECK_URL.

A key can include an "updates until" date: it keeps working with every MauiWeb release published before that date. See licensing and pricing.

Performance #

Measured on 25 October 2026 with the gallery's /basics page (about 60 controls), Debug build, server and load generator on one Apple Silicon Mac.

• Each new visitor costs about 10 ms of UI-thread time, so one process starts around 100 visitors a second. For more, run several processes behind a load balancer with sticky sessions.
• Bigger pages and more app state use more memory. Release builds do better than these numbers.