# Uno Navigation Code

> Programmatic navigation via `INavigator` extension methods (`NavigateRouteAsync`, `NavigateViewModelAsync`, `NavigateBackAsync`, and the `*ForResultAsync` overloads).

- Skill: `unoplatform/uno-navigation-code` (Agent Skill)
- Install (CLI): `npx skillmds@latest add unoplatform/uno-navigation-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/unoplatform/uno-navigation-code/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: unoplatform (https://skillmd.com/u/unoplatform)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/unoplatform/uno-navigation-code

---


# Uno Navigation from Code — Agent Skill

## Workflow

> **Docs lookup:** call `uno_platform_docs_search(...)` first, then `uno_platform_docs_fetch(sourcePath="…")` using the `sourcePath` field from a result (a relative `.md` path; add the result's `anchor` for a section). Never pass a URL, a `.html` link, or a hand-built path.

### Step 1: Fetch the Code Navigation Documentation

```
uno_platform_docs_search("Uno Navigation code programmatic NavigateRouteAsync NavigateViewModelAsync")
```

Primary documentation pages:
- **Navigation via Code Behind (Chefs)**: `external/uno.chefs/doc/navigation/NavigationCodeBehind.md`
- **Navigation Overview (Code section)**: `external/uno.extensions/doc/Learn/Navigation/NavigationOverview.md`

Fetch the Chefs code-behind page:

```
uno_platform_docs_fetch(sourcePath="external/uno.chefs/doc/navigation/NavigationCodeBehind.md")
```

### Step 2: For Specific Navigation Methods

The documentation covers two parallel families:

**Non-result overloads** — navigate to a destination, don't expect a return value:
- `NavigateRouteAsync("routeName")` — navigate by route string
- `NavigateViewAsync<TView>()` — navigate to a specific view type
- `NavigateViewModelAsync<TViewModel>()` — navigate to the route registered for a ViewModel type
- `NavigateDataAsync<TData>(data)` — navigate with data; the destination is resolved from the data type
- `NavigateBackAsync()` — pop one level off the back stack

**Result overloads** — navigate AND retrieve a typed result from the destination page:
- `NavigateRouteForResultAsync<TResult>("routeName")`
- `NavigateViewForResultAsync<TView, TResult>()`
- `NavigateViewModelForResultAsync<TViewModel, TResult>()`
- `NavigateDataForResultAsync<TData, TResult>()`
- `NavigateBackWithResultAsync(data)` — used on the destination page to return data to the caller

The result overloads return `Task<NavigationResult<TResult>>`. The caller awaits, then reads `.Result` for the returned value.

### Step 3: For Advanced Navigation Techniques

```
uno_platform_docs_search("Uno Navigation advanced back stack clear navigate techniques")
```

Key page:
- **Advanced Page Navigation**: `external/uno.extensions/doc/Learn/Navigation/Walkthrough/AdvancedPageNavigation.md`

## Critical Rules

- **Pick the correct overload for the navigation scenario.** Non-result overloads (`NavigateViewModelAsync<TViewModel>`) are for one-way navigation. Result overloads (`NavigateViewModelForResultAsync<TViewModel, TResult>`) are for request-and-await-response flows where the destination page calls `NavigateBackWithResultAsync(data)` to return a value. Using the non-result overload when a return value is needed silently throws away the result.
- Navigation methods are **extension methods on `INavigator`** — they are not extension methods on `string`, `Route`, or any view type. Get an `INavigator` instance first (constructor injection or `this.GetNavigator()`), then call `await navigator.Navigate*Async(...)`.

## Key Principles (Stable)

- Get `INavigator` via constructor injection or `this.GetNavigator()` extension method
- All navigation methods are async; non-result overloads return `Task<NavigationResponse>`, result overloads return `Task<NavigationResultResponse<TResult>>`
- `NavigateViewModelAsync` is the most common one-way overload — maps to the route registered for that ViewModel
- `NavigateBackAsync()` goes back one level
- Combine with `Qualifiers.ClearBackStack` to clear navigation history
- Always `await` navigation calls

## Common Pitfall Example

The second Critical Rule above (extension methods on `INavigator`) is the most-seen mistake. Concrete example:

```csharp
// WRONG: CS1929 — string has no NavigateRouteAsync
await "/details".NavigateRouteAsync(...);

// CORRECT: Get INavigator first
var navigator = this.GetNavigator();
await navigator.NavigateRouteAsync(this, route: "/details");
```

In XAML, prefer the `uen:Navigation.Request` attached property instead of code-behind navigation:

```xml
<Button Content="Go to Details"
        uen:Navigation.Request="Details"/>
```

## Related Skills

- [[uno-navigation-routes]] — Route registration (required for code navigation)
- [[uno-navigation-data]] — Passing data during navigation
- [[uno-navigation-qualifiers]] — Navigation qualifiers (clear back stack, etc.)
- [[uno-navigation-xaml]] — Declarative alternative to code navigation