Uno Navigation
Uno.Extensions.Navigation is route-based: pages and ViewModels are registered once in App.xaml.cs, then navigation happens by route name from XAML (uen:Navigation.Request) or code (INavigator). Shells (TabBar, NavigationView, responsive) are built from regions, where the framework injects registered views into an empty container at runtime. Generic agents reliably get this wrong: they hand-wire Frame.Navigate, pre-populate the content area with collapsed pages, put Region.Attached in Shell.xaml, or call navigation methods on the wrong type. This skill stops those mistakes and routes you to the reference for the task.
Workflow
- Pick a shell (below) if the app has no navigation yet, then find each task in the topic map and read the matching
references/*.mdbefore writing code. Shell references point to complete, compilable templates with placeholders; copy those rather than composing shell XAML from memory. - The reference answers the common case; the docs pages it names are for what it leaves out. Then search with
uno_platform_docs_search(...)and fetch only the section you need:uno_platform_docs_fetch(sourcePath="…", anchor="…"), both values from a search result. A whole page is 2,000 to 6,000 tokens that stay in context for the rest of the session. Never pass a URL,.htmllink, or hand-built path. - Check the generated XAML and route registration against the critical rules below before finishing. Most navigation bugs are a mismatch between a route name and a
Region.Name/Navigation.Requestvalue, or a container that is not empty.
Choose a shell
- TabBar (bottom tabs): 3 to 5 top-level pages, mobile-first or consumer apps. The default when the prompt does not say desktop or enterprise.
references/tabbar.md. - NavigationView (sidebar/hamburger): more than 5 pages, hierarchical content, desktop, admin, dashboard, or enterprise apps.
references/navigationview.md. - Responsive: must work well on both phone and desktop; TabBar under 700px, NavigationView above.
references/responsive-shell.md. - Frame (linear): 1 or 2 pages, navigation is secondary, no tabs or sidebar. Buttons with
uen:Navigation.Request.references/xaml.md.
Topic map
| Task | Read | Key APIs |
|---|---|---|
| Add navigation to a project, configure the host, understand Shell.xaml | references/setup.md |
<UnoFeatures>Navigation;Toolkit</UnoFeatures>, .UseNavigation(RegisterRoutes), .UseToolkitNavigation() |
| Register pages and ViewModels, nest routes | references/routes.md |
ViewMap, DataViewMap, ResultDataViewMap, RouteMap |
| Navigate from a Button, list item, or any control without code-behind | references/xaml.md (+ references/shell-frame-template.md) |
uen:Navigation.Request, - (back), -/Route, ./Region |
| Navigate from a ViewModel, code-behind, or service | references/code.md |
INavigator, this.Navigator(), NavigateViewModelAsync<T>(this), NavigateRouteAsync(this, "Route"), NavigateBackAsync(this), *ForResultAsync |
| Pass an entity or ID to a details page, return a result | references/data.md |
DataViewMap, NavigateDataAsync, uen:Navigation.Data, NavigateBackWithResultAsync |
| Alert, confirmation, modal, or flyout | references/dialogs.md |
ShowMessageDialogAsync, !Route or Qualifiers.Dialog, ContentDialog vs Page |
| Clear the back stack (after login), drop the current page, open dialogs by prefix | references/qualifiers.md |
-/Route, -Route, !Route, Qualifiers.ClearBackStack, Qualifiers.Dialog |
| Link a navigation control to a content area, nested regions | references/regions.md |
uen:Region.Attached, uen:Region.Name, uen:Region.Navigator |
| Bottom-tab shell | references/tabbar.md (+ references/shell-tabbar-template.md) |
utu:TabBar, TabBarItem + Region.Name, BottomTabBarStyle, BottomTabBarItemStyle |
| Sidebar/hamburger shell, Settings item | references/navigationview.md (+ references/shell-navigationview-template.md) |
NavigationView + Region.Attached, NavigationViewItem + Region.Name, Settings in FooterMenuItems |
| One shell for phone and desktop | references/responsive-shell.md (+ references/shell-responsive-template.md) |
VisualStateManager breakpoints, shared Region.Name, ResponsiveExtension |
| Content area that swaps views by visibility (inside shells) | references/panel-visibility.md |
empty Grid with Region.Attached + Region.Navigator="Visibility" |
| Swap content in one pane with no back stack | references/contentcontrol.md |
ContentControl + Region.Attached |
| Blank page, route not found, back not working, data not arriving | references/troubleshooting.md |
checklist of the rules below |
Critical rules
- Every page is registered. Each View/ViewModel pair needs a
ViewMap(orDataViewMap/ResultDataViewMap) and aRouteMapentry inRegisterRoutes; an unregistered route yields a blank page or a runtime error. Route names usually match the page name without thePagesuffix. - Route names must match in three places. The
RouteMapname, theuen:Region.Nameon the tab or menu item, and anyuen:Navigation.Requeststring are compared literally. In TabBar and NavigationView shells, nest page routes under the"Main"shell route so only the content area changes; in a plain Frame shell, register pages as siblings of"Main", as the template does: under the""root in an app created with-shell, at the top level otherwise (the template default has no Shell). - Never put
Region.Attached="True"inShell.xamlor ExtendedSplashScreen content. The navigation host is not ready there. Regions belong in the shell page (SHELL_PAGE_NAME.xaml) that the host navigates to. - The content area is a
Grid, never aStackPanelor other panel: on anything else the Visibility navigator gets no control, the request bubbles to the parent region, and tapping a tab or menu item replaces the whole page. It needs bothuen:Region.Attached="True"anduen:Region.Navigator="Visibility". Keep it empty (the framework injects registered views at runtime and toggles their visibility), or give every pre-placed child auen:Region.Namematching its route, as the docs' responsive walkthrough does. Never drop unnamed collapsed pages in it. - The navigation control and the content area share a parent that has
Region.Attached="True", and the control itself also hasRegion.Attached="True". TabBar and NavigationView both need it, and in a responsive shell both use identicalRegion.Namevalues because they drive the same content area. - Prefer
uen:Navigation.Requestin XAML over code-behind for simple transitions; it works on any element withClickorTapped. Secondary pages get a back button withuen:Navigation.Request="-". - Navigation methods are extension methods on
INavigator, and every one takessenderfirst. Get the navigator via constructor injection orthis.Navigator()on a view (nullable), thenawait navigator.NavigateViewModelAsync<T>(this),NavigateRouteAsync(this, "Route"),NavigateBackAsync(this). CallingNavigateRouteAsyncon a string or a view is a compile error (CS1929, or CS1061 ifUno.Extensions.Navigationis not imported).Region.GetNavigator(element)is unrelated: it returns theRegion.Navigatorstring. Alwaysawait. - Pick the result overload when a value comes back.
NavigateViewModelForResultAsync<TViewModel, TResult>(this)plusNavigateBackWithResultAsync(this, data: value)on the destination; the plain overload silently discards the result. The response's.Resultis aTask<Option<TResult>>, soawait response!.Resultand testIsSome. Register the pair withResultDataViewMap. - Data arrives through the ViewModel constructor. Register a
DataViewMap<TView, TViewModel, TData>and pass the entity withNavigateDataAsyncoruen:Navigation.Data="{Binding Item}"; the framework resolves the destination from the data type. - Use qualifiers for back-stack intent.
-/Home(orQualifiers.ClearBackStack) after login clears the whole back stack so back cannot return to the login page;-Homedrops only the current page;!Route(orQualifiers.Dialog) opens a route as a dialog: aPagetarget shows as a flyout, aContentDialogtarget as a modal (aContentDialogroute opens as a modal even without!). Simple prompts need no route at all:ShowMessageDialogAsync<string>(this, title:, content:, buttons:)returns the chosenDialogAction.Id(or itsLabelwhenIdis null); the non-generic overload returns plainTask. - Do not use the built-in NavigationView Settings item.
NavigationViewNavigatoronly enumeratesMenuItemsandFooterMenuItems, so aRegion.SetNameonSettingsItemnavigates but never syncs selection: navigating to Settings from code or a deep link leaves the previous item highlighted. SetIsSettingsVisible="False"and add a normalNavigationViewItemwithuen:Region.Name="Settings"toNavigationView.FooterMenuItems. - Namespaces:
xmlns:uen="using:Uno.Extensions.Navigation.UI"for regions and attached properties,xmlns:utu="using:Uno.Toolkit.UI"forTabBar.Toolkitmust be in<UnoFeatures>alongsideNavigationfor TabBar and NavigationBar. - Host setup registers the routes.
.UseToolkitNavigation()on theIApplicationBuilder, then.UseNavigation(RegisterRoutes)on the host, or.UseNavigation(ReactiveViewModelMappings.ViewModelMappings, RegisterRoutes)with MVUX. A bare.UseNavigation()compiles and registers nothing. - Tab items use the alias style keys.
BottomTabBarStyleon theTabBar,BottomTabBarItemStyleon eachTabBarItem. Only the Material and Simple toolkit themes define these aliases;MaterialBottomTabBarItemStyleexists only in Material and resolves to null under Simple, the template default (unstyled item on WebAssembly/Skia, an exception only on the Windows head). On Fluent (the-preset blankdefault) omit theStyleattributes; on Cupertino useCupertinoBottomTabBarStyle/CupertinoBottomTabBarItemStyle. The same applies to the page background:BackgroundBrushexists only in Uno.Themes, so on Fluent useApplicationPageBackgroundThemeBrushand on CupertinoCupertinoSystemBackgroundBrush, as the template does.
Related skills
uno-mvuxfor the Models that pages bind to; MVUX*Modelrecords are whatViewMap/DataViewMapregister as the ViewModel type.uno-toolkitfor the controls used inside shells:references/tabbar.md(TabBar styling, badges, orientations),references/navigationbar.md(page app bar with native back button),references/responsive.md(breakpoint markup extension).uno-toolkitalso owns the shell style keys (BottomTabBarStyle,BottomTabBarItemStyle; seereferences/tabbar.mdandreferences/material-theme.md);uno-themesfor restyling navigation chrome with semantic brushes.