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"));

Alert

Display a simple alert dialog.

await navigator.Alert("Error", "Something went wrong", "OK");

Parameter	Type	Description
title	string	Alert title
message	string	Alert body text
acceptText	string	Button text (default: “OK”)

Confirm

Display a confirmation dialog and return the user’s choice.

bool confirmed = await navigator.Confirm(
    "Delete Item",
    "Are you sure you want to delete this?",
    "Delete",
    "Cancel"
);

if (confirmed)
{
    // proceed with deletion
}

Parameter	Type	Description
title	string	Dialog title
message	string	Dialog body text
acceptText	string	Accept button text (default: “OK”)
cancelText	string	Cancel button text (default: “Cancel”)

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, or PopToRoot
    // 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, or PopToRoot
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, or PopToRoot
    // 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, or PopToRoot
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.