Build together, debug together. Join the community on Discord.→

Navigation in Uno Platform: A Comprehensive Guide to Uno.Extensions Navigation

When developing applications, effective navigation is crucial for creating intuitive and efficient user experiences. This guide focuses specifically on Uno Platform’s Uno.Extensions Navigation feature, a powerful routing framework that extends beyond the capabilities of native frame navigation in Uno Platform.

Uno.Extensions Navigation provides a comprehensive system designed to handle a wide range of navigation scenarios in modern app development. It’s important to note that this navigation framework is distinct from the basic frame navigation native to Uno Platform, offering more advanced features and flexibility.

Navigation Types

Uno Platform’s navigation system is designed to handle:

Traditional page-to-page navigation within a Frame
Switching between menu items in a NavigationView
Loading content dynamically into a ContentControl
Managing visibility of child elements in a Grid
Displaying Popups or Flyouts
Prompting users with ContentDialogs or MessageDialogs

Navigation Triggers

Navigation in Uno Platform can be triggered for various reasons:

Changing views based on the type of View or ViewModel
Displaying data based on the type of data to show
Prompting or requesting data from the user.

Navigation Accessibility

The platform’s architecture ensures that navigation is accessible from anywhere in your app:

In the View’s code-behind
Declaratively in XAML using attached properties
In ViewModels, decoupled from the UI layer

Moreover, Uno Platform’s navigation system is designed to make efficient use of available data, supporting:

URI-based navigation for deep linking
Passing existing data objects between views
Navigation based on ViewModel or View types

Navigation Tutorials

In this guide, we’ll explore eight key aspects of navigation using the Uno.Extensions Navigation, each with its own dedicated tutorial:

Each section will provide an overview of the concept, code examples, and a link to a detailed step-by-step tutorial. Whether you’re new to Uno Platform or looking to master its navigation capabilities, this article will equip you with the knowledge to implement efficient and user-friendly navigation in your apps.

Let’s dive in and explore the power and flexibility of navigation in Uno Platform.

1. Page Navigation

At its core, navigation in Uno Platform revolves around moving between different pages or views. The platform provides multiple ways to achieve this:

Code-behind navigation: Utilize the Navigator() extension method to obtain an INavigator instance and call NavigateViewAsync<T>().
ViewModel-based navigation: Adjust your ViewModel to take a dependency on INavigator and utilize NavigateViewModelAsync<T>()

				
					// Code-behind navigation example
_ = this.Navigator()?.NavigateViewAsync<SecondPage>(this);

// ViewModel-based navigation example
await _navigator.NavigateViewModelAsync<SecondViewModel>(this);

Tutorial: How-To: Navigate Between Pages

2. Navigating in Code

When you need more control over navigation logic, you can implement navigation directly in your code:

Use the Navigator() extension method in code-behind files.
Inject INavigator into your ViewModels for navigation.
Implement backwards navigation using NavigateBackAsync().

				
					public class MainViewModel
{
    private readonly INavigator _navigator;
    
    public MainViewModel(INavigator navigator)
    {
        _navigator = navigator;
    }

    public async Task NavigateToSecondPage()
    {
        await _navigator.NavigateViewModelAsync<SecondViewModel>(this);
    }
}

Tutorial: How-To: Navigate in Code

3. Navigating in XAML

Uno Platform allows for declarative navigation directly in your XAML:

Use the Navigation.Request attached property for navigation.
Implement data passing with the Navigation.Data attached property.

				
					<Button Content="Go to Second Page"
        uen:Navigation.Request="Second"
        uen:Navigation.Data="{Binding SelectedItem}" />

Tutorial: How-To: Navigate in XAML

4. Defining Routes

For more complex navigation scenarios, Uno Platform allows you to define custom routes:

Use ViewMap to associate views with view models.
Implement RouteMap to define the navigation structure, including nested routes.
Utilize DataViewMap for data-driven navigation.

				
					views.Register(
    new ViewMap<MainPage, MainViewModel>(),
    new DataViewMap<SecondPage, SecondViewModel, Entity>()
);

routes.Register(
    new RouteMap("", View: views.FindByViewModel<ShellViewModel>(),
        Nested: [
            new ("Main", View: views.FindByViewModel<MainViewModel>()),
            new ("Second", View: views.FindByViewModel<SecondViewModel>()),
        ]
    )
);

Tutorial: How-To: Define Routes

5. Displaying Message Dialogs

Uno Platform’s navigation system extends to displaying dialogs:

Use ShowMessageDialogAsync() for simple prompts or confirmations.
Implement localized message dialogs with LocalizableMessageDialogViewMap.

				
					var result = await _navigator.ShowMessageDialogAsync<string>(
    this,
    title: "Confirm Action",
    content: "Are you sure?",
    buttons: [
        new DialogAction("Yes"),
        new DialogAction("No")
    ]
);

Tutorial: How-To: Display a Message Dialog

6. Selecting Values

For scenarios where you need to navigate to select a value:

Use GetDataAsync<T>() to navigate and retrieve selected data
Implement ResultDataViewMap<TView, TViewModel, TData> for type-safe navigation with return values
Use Navigation.Request="-" for navigating back with selected data

				
					// Define the data type
public record Widget(string Name, double Weight);

// In SecondViewModel
public Widget[] Widgets { get; } =
[
    new Widget("NormalSpinner", 5.0),
    new Widget("HeavySpinner", 50.0)
];

// In MainViewModel
public async Task GoToSecondPage()
{
    var widget = await _navigator.GetDataAsync<SecondViewModel, Widget>(this);
    // Use the selected widget
}

In XAML, you can set up a ListView for selection:

				
					<ListView ItemsSource="{Binding Widgets}"
          uen:Navigation.Request="-"
          HorizontalAlignment="Center"
          VerticalAlignment="Center">
    <ListView.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal"
                        Padding="10">
                <TextBlock Text="{Binding Name}" />
                <TextBlock Text="{Binding Weight}" />
            </StackPanel>
        </DataTemplate>
    </ListView.ItemTemplate>
</ListView>

For more efficient navigation, you can use ResultDataViewMap:

				
					// In route registration
new ResultDataViewMap<SecondPage, SecondViewModel, Widget>()

// Updated navigation in MainViewModel
public async Task GoToSecondPage()
{
    var widget = await _navigator.GetDataAsync<Widget>(this);
}

This approach allows Navigation to resolve the correct view based on the requested data type.

Tutorial: How-To: Select a Value

7. Displaying Dialogs (Modal or Flyout)

Uno Platform supports both modal and flyout dialogs:

Use Qualifiers.Dialog for displaying content as a dialog.
Control whether content appears as a flyout or modal based on the view type (Page vs ContentDialog).

				
					// Displaying a dialog
_ = this.Navigator()?.NavigateViewAsync<SamplePage>(this, qualifier: Qualifiers.Dialog);

				
					// In XAML
<Button Content="Show Dialog"
        uen:Navigation.Request="!Sample" />

Tutorial: How-To: Display a Dialog (modal or flyout)

Displaying Item Details

For data-driven navigation scenarios like master-detail views:

Use DataViewMap<TView, TViewModel, TData> to associate views, view models, and data types.
Implement NavigateDataAsync() for type-safe navigation with data.

				
					// Navigating with data
var widget = new Widget("ExampleWidget", 10.0);
await _navigator.NavigateDataAsync(this, data: widget);

// Receiving data in the destination ViewModel
public class SecondViewModel
{
    public SecondViewModel(Widget widget)
    {
        // Use the widget data
    }
}

Tutorial: How-To: Display Item Details

Conclusion

The trick here? Focus on understanding how your app’s structure and user flow work together. Start small with basic navigation and, as you get more comfortable, feel free to add those more advanced techniques to easily create everything from simple page transitions to more intricate, data-driven flows.

And hey, if you ever need more help or a step-by-step breakdown, don’t hesitate to dive into the official Uno Platform docs linked in this article or join the community on Discord.

Happy Coding!

Next Steps

Ready to boost your productivity and simplify cross-platform .NET development? Try Uno Platform by downloading our extension for your preferred IDE and dive into our tutorials and samples.