Shell | Navigation

All navigation in Shiny Shell goes through the INavigator interface. Inject it into your ViewModels via constructor injection.

public class MyViewModel(INavigator navigator)
{
    // navigator is ready to use
}

NavigateTo (Route)

Navigate to a registered route by name, optionally passing arguments as key-value tuples.

// Simple route navigation
await navigator.NavigateTo("details");

// With arguments
await navigator.NavigateTo("details", ("Id", 42), ("Name", "Allan"));

Arguments are received on the target ViewModel via IQueryAttributable.ApplyQueryAttributes.

NavigateTo (ViewModel)

Navigate by ViewModel type with an optional configuration action for strongly-typed argument passing.

// Navigate to a ViewModel
await navigator.NavigateTo<DetailViewModel>();

// With strongly-typed property setup
await navigator.NavigateTo<DetailViewModel>(vm => vm.Id = 42);

// With additional route arguments
await navigator.NavigateTo<DetailViewModel>(
    vm => vm.Id = 42,
    ("ExtraArg", "value")
);

Note

If you are setting properties on the ViewModel during navigation, those properties should be observable (e.g. use [ObservableProperty] or raise PropertyChanged) if they are bound on the Page.

SetRoot

Replace the navigation stack with a new root ViewModel.

// Set a new root
await navigator.SetRoot<HomeViewModel>();

// With configuration
await navigator.SetRoot<HomeViewModel>(vm => vm.WelcomeMessage = "Hello!");

GoBack

Navigate back one or more pages, optionally passing arguments to the previous ViewModel.

// Simple go back
await navigator.GoBack();

// Go back with arguments
await navigator.GoBack(("Result", "saved"), ("Timestamp", DateTime.UtcNow));

// Go back multiple pages
await navigator.GoBack(2);

// Go back multiple pages with arguments
await navigator.GoBack(2, ("Result", "saved"));

PopToRoot

Pop the entire navigation stack back to the root page.

await navigator.PopToRoot();

// With arguments
await navigator.PopToRoot(("Status", "complete"));

SwitchShell

Replace the entire active Shell at runtime. Useful for switching between different app experiences (e.g. tabbed layout, flyout menu, onboarding flow).

// Switch to a new Shell instance
await navigator.SwitchShell(new AdminShell());

// Switch to a Shell resolved from DI
await navigator.SwitchShell<AdminShell>();

The current Shell’s ViewModel receives OnNavigatingFrom before the switch, and the Navigating event fires with NavigationType.SwitchShell.

Note

The new Shell must be a fresh instance — do not reuse a Shell that was previously displayed. Shell instances resolved via SwitchShell<TShell>() are created from the DI container each time.

Navigation Events

INavigator exposes two events for observing navigation lifecycle:

Navigating (Pre-Navigation)

Fires before navigation occurs. Provides the source ViewModel instance and destination route.

navigator.Navigating += (sender, args) =>
{
    // args.FromUri         — current location URI
    // args.FromViewModel   — source ViewModel instance (object?)
    // args.ToUri           — destination route URI
    // args.NavigationType  — Push, SetRoot, GoBack, PopToRoot, or SwitchShell
    // args.Parameters      — navigation parameters
};

Property	Type	Description
FromUri	string?	The current Shell location URI
FromViewModel	object?	The source page’s ViewModel instance
ToUri	string	The destination route URI
NavigationType	NavigationType	Push, SetRoot, GoBack, PopToRoot, or SwitchShell
Parameters	IReadOnlyDictionary<string, object>	Navigation parameters

Navigated (Post-Navigation)

Fires after navigation completes and the destination page’s ViewModel is resolved.

navigator.Navigated += (sender, args) =>
{
    // args.ToUri           — destination route URI
    // args.ToViewModel     — destination ViewModel instance (object?)
    // args.NavigationType  — Push, SetRoot, GoBack, PopToRoot, or SwitchShell
    // args.Parameters      — navigation parameters
};

Property	Type	Description
ToUri	string	The destination route URI
ToViewModel	object?	The destination page’s ViewModel instance
NavigationType	NavigationType	Push, SetRoot, GoBack, PopToRoot, or SwitchShell
Parameters	IReadOnlyDictionary<string, object>	Navigation parameters

Example: Navigation Logger

Use IMauiInitializeService to hook events for cross-cutting concerns like logging or analytics:

public class NavigationLogger(
    ILogger<NavigationLogger> logger,
    INavigator navigator
) : IMauiInitializeService
{
    public void Initialize(IServiceProvider services)
    {
        navigator.Navigating += (_, args) =>
        {
            logger.LogInformation(
                "Navigating from '{FromUri}' to '{ToUri}' | Type: {NavigationType} | FromViewModel: {FromViewModel}",
                args.FromUri,
                args.ToUri,
                args.NavigationType,
                args.FromViewModel?.GetType().Name
            );
        };

        navigator.Navigated += (_, args) =>
        {
            logger.LogInformation(
                "Navigated to '{ToUri}' | Type: {NavigationType} | ToViewModel: {ToViewModel}",
                args.ToUri,
                args.NavigationType,
                args.ToViewModel?.GetType().Name
            );
        };
    }
}

// Register in MauiProgram.cs
builder.Services.AddSingleton<IMauiInitializeService, NavigationLogger>();

Passing Arguments

Arguments passed during navigation are delivered via the MAUI built-in IQueryAttributable interface.

public class DetailViewModel : IQueryAttributable
{
    public int Id { get; set; }

    public void ApplyQueryAttributes(IDictionary<string, object> query)
    {
        if (query.TryGetValue("Id", out var id))
            Id = (int)id;
    }
}

This works for arguments passed via NavigateTo, GoBack, and PopToRoot.

Tip

When using ViewModel-based navigation (NavigateTo<TViewModel>), you can skip IQueryAttributable entirely and set properties directly via the configuration action. This is the recommended approach for strongly-typed navigation.