maui-shell-navigation

name

maui-shell-navigation

description

.NET MAUI Shell navigation guidance — Shell visual hierarchy, AppShell setup, tab bars, flyout menus, URI-based navigation with GoToAsync, route registration, query parameters, back navigation, and navigation events. USE FOR: "Shell navigation", "GoToAsync", "AppShell", "tab bar", "flyout menu", "route registration", "query parameters navigation", "back navigation", "Shell tabs", "URI navigation", "navigation events". DO NOT USE FOR: deep linking from external URLs (use maui-deep-linking), data binding on pages (use maui-data-binding), or dependency injection setup (use maui-dependency-injection).

.NET MAUI Shell Navigation

Key decisions

ContentTemplate — always use it

Always use ContentTemplate with DataTemplate so pages are created on demand. Using Content directly creates all pages during Shell init, hurting startup time.

<!-- ✅ Lazy — page created on first navigation -->
<ShellContent ContentTemplate="{DataTemplate views:HomePage}" />

<!-- ❌ Eager — page created at Shell startup -->
<ShellContent>
    <views:HomePage />
</ShellContent>

Passing data — prefer IQueryAttributable over QueryProperty

IQueryAttributable gives you all parameters in one call and works on ViewModels:

public class AnimalDetailsViewModel : ObservableObject, IQueryAttributable
{
    public void ApplyQueryAttributes(IDictionary<string, object> query)
    {
        if (query.TryGetValue("id", out var id))
            AnimalId = id.ToString();
    }
}

For complex objects, use ShellNavigationQueryParameters to avoid serializing:

var parameters = new ShellNavigationQueryParameters
{
    { "animal", selectedAnimal }
};
await Shell.Current.GoToAsync("animaldetails", parameters);

Guarding navigation — async deferral pattern

Use GetDeferral() for async checks (e.g., "save unsaved changes?"):

protected override async void OnNavigating(ShellNavigatingEventArgs args)
{
    base.OnNavigating(args);
    if (hasUnsavedChanges && args.Source == ShellNavigationSource.Pop)
    {
        var deferral = args.GetDeferral();
        bool discard = await ShowConfirmationDialog();
        if (!discard)
            args.Cancel();
        deferral.Complete();
    }
}

Common gotchas

1. Duplicate route names — Routing.RegisterRoute throws ArgumentException if a route name is already registered or matches a visual hierarchy route. Every route must be unique across the entire app.

2. Relative routes require registration — you cannot GoToAsync("somepage") unless somepage was registered with Routing.RegisterRoute. Visual hierarchy pages use absolute // routes instead.

3. Pages are created on demand — when using ContentTemplate, the page constructor runs only on first navigation. Don't assume pages exist at startup.

4. Tab.Stack is read-only — you cannot manipulate the navigation stack directly; use GoToAsync for all navigation changes.

5. GoToAsync is async — always await it — fire-and-forget navigation causes race conditions and can silently fail:

   // ❌ Fire-and-forget — race conditions
   Shell.Current.GoToAsync("details");
   
   // ✅ Always await
   await Shell.Current.GoToAsync("details");
   

6. Route hierarchy matters — absolute routes must match the full path through the visual hierarchy (//FlyoutItem/Tab/ShellContent). Getting the path wrong produces silent no-ops, not exceptions.