Maui Shell Navigation

.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.

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 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.

1. Relative routes require registration — you cannot GoToAsync("somepage")

unless somepage was registered with Routing.RegisterRoute. Visual hierarchy pages use absolute // routes instead.

1. Pages are created on demand — when using ContentTemplate, the page

constructor runs only on first navigation. Don't assume pages exist at startup.

1. Tab.Stack is read-only — you cannot manipulate the navigation stack directly;

use GoToAsync for all navigation changes.

1. GoToAsync is async — always await it — fire-and-forget navigation causes

race conditions and can silently fail: ```csharp // ❌ Fire-and-forget — race conditions Shell.Current.GoToAsync("details");

// ✅ Always await await Shell.Current.GoToAsync("details"); ```

1. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: davidortinau
• Source: davidortinau/maui-skills
• License: MIT

Install and usage instructions live in the source repository linked above.