Navigation API design contradicts Avalonia's own MVVM conventions

[omrzh]

Avalonia 12.0 ships NavigationPage and INavigation under Avalonia.Controls, signaling this as the framework's canonical navigation solution. However, the API design is fundamentally at odds with Avalonia's own established MVVM conventions. Three specific contradictions:

---

1. Contradicts the ViewLocator pattern promoted by Avalonia's own project templates

Avalonia's official project template introduces ViewLocator as the first thing new developers encounter. The entire point of ViewLocator is VM-first: you navigate by ViewModel type, and the framework resolves the View automatically. The new navigation API inverts this entirely — the caller is responsible for instantiating the View directly:

// What Avalonia's own template teaches
// ViewModel → ViewLocator → View (automatic)

// What the new navigation API requires
await Navigation.PushAsync(new PageD()); // caller instantiates the View

These two patterns cannot coherently coexist in the same application. A developer following the project template's conventions has no natural path to adopt this navigation API without abandoning the VM-first model they were taught.

---

2. PopToPageAsync(Page page) forces cross-layer object retention

PopToPageAsync requires the caller to hold a reference to the target Page instance — a View-layer object. In any MVVM architecture, this means a ViewModel must either retain a reference to a View, or retrieve it by walking the navigation stack at call time:

// The only viable implementation in a ViewModel
var target = Navigation.NavigationStack.FirstOrDefault(p => p is PageA);
await Navigation.PopToPageAsync(target!);

This is not a usage concern — it is an inevitable consequence of the interface contract. Any developer needing PopTo semantics in an MVVM application will be pushed toward anti-patterns such as static Page registries or ViewModels holding View references. The interface provides no alternative.

---

3. Avalonia.Controls namespace implies canonical status this API does not warrant

Placing this API under Avalonia.Controls — the same namespace as Button, ListBox, and TextBox — signals to every Avalonia developer that this is the intended, general-purpose navigation solution. In reality, this API is self-consistent only in code-behind / no-DI scenarios similar to Xamarin.Forms or MAUI. For the majority of Avalonia applications that use DI and MVVM, it is a trap.

---

Suggested direction

A VM-first API would be consistent with Avalonia's existing conventions and close this contradiction:

// Consistent with ViewLocator — caller never touches View types
await Navigation.PushAsync<PageDViewModel>();
await Navigation.PopToAsync<PageAViewModel>();

The View resolution can be delegated to ViewLocator (or a registered IDataTemplate) internally, which is exactly the mechanism Avalonia already ships for this purpose.

If the current API is intentionally scoped to mobile / code-behind scenarios, it should be namespaced accordingly (e.g. Avalonia.Controls.Navigation or a dedicated package) and the documentation should make the scope explicit. Placing it under Avalonia.Controls without qualification sets a false expectation for the majority of the Avalonia user base.

[stevemonaco]

I don't really agree. Avalonia is a UI framework so they handle the View side. You can build around it.

The wiring is tricky, but there are a few approaches depending whether you want navigation to be a side effect or whether you need synchronization. You can start by writing a ViewModel-First abstraction around NavigationPage via a service class using your own interface. The concrete version will live within the view and can inject state, such as the NavigationPage if you need tight synchronization. This won't be part of the VM-side interface, so it won't know.

Messaging is another option that we use to decouple and events being another option. This is not too hard if your app is single window, but multiple windows is substantially harder. I use an approach with DI scoping for our multiple window app and while the VM side is completely MVVM pure in this area, I wouldn't recommend it. It's very complex wiring and you need to churn IoC containers or otherwise never use transient IDisposables. I would move to a registration-based approach even if it's a bit less elegant...or maybe a different form of IoC factory trickery.

[omrzh]

I think you are mistaking “this does not impose my preferred architecture” for “this is badly designed”.

Avalonia should provide flexible primitives, not a cookie-cutter navigation framework. Real app navigation gets opinionated very quickly, and pushing one canonical model into the controls layer would be the actual design mistake.

Thanks for the response — but I think "preferred architecture" mischaracterizes the critique.

The contradiction is internal to Avalonia, not between me and Avalonia. The VM-first pattern isn't my preference imposed on the framework — it is the framework's own design language. The DataTemplate-based dispatch mechanism has been central to WPF since its inception, and Avalonia carried it forward and made it more flexible. The entire premise is: you declare a mapping from ViewModel type to View, and the framework resolves it. ViewLocator is just the explicit materialization of this same idea, which is why Avalonia's own project template introduces it on day one.

The new navigation API doesn't just ignore this mechanism — it works against it. When PushAsync requires the caller to instantiate a Page directly, it bypasses the very dispatch layer the framework spent years establishing. That's not a neutral design choice. It's a regression against Avalonia's own conventions, and telling developers to "build around it" means asking them to manually recreate what DataTemplate dispatch already provides.

INavigation is not a flexible primitive — it's a Page-coupled primitive. PushAsync(new PageD()), PopToPageAsync(Page page), NavigationStack — every method in the interface takes or returns Page instances. That's not flexibility; that's the View layer hardcoded as the unit of navigation. A genuinely flexible primitive would accept type tokens or intent objects and let the caller decide the semantics. What's been shipped is a primitive that's flexible only if you're already doing code-behind.

Which brings me to something you said that I want to read back carefully. You said "pushing one canonical model into the controls layer would be the actual design mistake." I agree completely. So does INavigation in Avalonia.Controls not qualify?

You also said real app navigation gets opinionated very quickly. If that's true — and I think it is — then the honest consequence is that this API shouldn't live in Avalonia.Controls. It should have its own namespace, or better yet, its own optional package. That's not a limitation; that's what genuine neutrality looks like. Developers who want this model opt in. Developers building MVVM-first apps aren't handed a namespace-level false signal about what Avalonia considers canonical.

One more thing worth saying explicitly: I'm not here to find fault for its own sake. A built-in navigation API is genuinely good for Avalonia's competitiveness — it lowers the barrier for developers coming from MAUI or Xamarin who expect something out of the box. That's a worthwhile goal. But the API's current placement makes a claim its design can't back up.

I'll also say this plainly: I understand that criticism tends to invite reflexive pushback, and I know that developers who have grown accustomed to working around framework limitations will often read posts like this as overreaction. But the method signatures speak for themselves. The moment PopToPageAsync(Page page) ships as a production API, every MVVM developer who adopts it will face the same forced choice — regardless of whether they prefer view-first or VM-first. The workarounds aren't hypothetical; they're load-bearing consequences of the interface contract.

My position is that these concerns are in Avalonia's interest, not against it. If someone can demonstrate that I'm actually advocating for my own technical preferences rather than for the consistency of the framework's own established conventions, then that's the conversation worth having. Until then, I think the critique stands.

[stevemonaco]

Personally, I would have preferred the navigation be placed into another package (potentially Avalonia.Labs standalone package) given how late it came in the 12.0 cycle. These systems are incredibly hard to get right.

The existence of DataTemplate does not show an MVVM bias even if that's what is mostly used by the ecosystem. They work perfectly well for projecting immutable objects to views. You'll see that DataTemplate is actually a really poor fit when it comes to state-based projection to alternate views because: 1. you need to listening to object changes yourself. 2. you'll likely hit a memory leak because they aware of the visual tree by default.

Page is an abstract type, so it might be easily solved by simply putting a Content property, a ContentPresenter, and letting DataTemplate projection work as usual. Assuming the existing ones don't already have that. Page being more of a wrapper and you write a small utility method so you can push VMs or whatever. Not a big deal.

[omrzh]

Personally, I would have preferred the navigation be placed into another package (potentially Avalonia.Labs standalone package) given how late it came in the 12.0 cycle. These systems are incredibly hard to get right.

The existence of DataTemplate does not show an MVVM bias even if that's what is mostly used by the ecosystem. They work perfectly well for projecting immutable objects to views. You'll see that DataTemplate is actually a really poor fit when it comes to state-based projection to alternate views because: 1. you need to listening to object changes yourself. 2. you'll likely hit a memory leak because they aware of the visual tree by default.

Page is an abstract type, so it might be easily solved by simply putting a Content property, a ContentPresenter, and letting DataTemplate projection work as usual. Assuming the existing ones don't already have that. Page being more of a wrapper and you write a small utility method so you can push VMs or whatever. Not a big deal.

Steve, man — you get it. From our previous exchanges, I can tell you are experienced developer and you've been bitten by exactly these kinds of framework decisions before. You've done the workarounds, felt the friction, and made your peace with it. And that's what makes this conversation worth having — you're not defending the API from the outside. You know the tradeoffs firsthand, and I'd much rather hash this out with someone like that than get a "works as designed" from someone who hasn't shipped anything real with it.

The Page + ContentPresenter workaround is something I've thought through carefully, and yes, it can be made to work. But my concern is precisely that it is a workaround — and one that quietly pushes accidental complexity onto every consumer project. The moment you need a small utility method, a custom Content property, and manual DataTemplate wiring just to do basic ViewModel-first navigation, you've already lost the "it just works" guarantee that a framework-level API should provide.

On the DataTemplate point — I actually agree it's not inherently MVVM-biased in the general sense. But in the context of a navigation API, where the primary job is mapping a ViewModel to a View and managing its lifecycle, DataTemplate is a poor primitive. You even named the exact problems yourself: external change-listening and memory leak exposure. Those aren't edge cases in navigation — they're the core of what navigation has to handle correctly, every time.

And your point about this belonging in Labs rather than core? That resonates deeply. When something this complex and opinionated lands directly under the Avalonia.Controls namespace, it carries an implicit stamp of authority — as if this is the canonical answer. For a problem space where there genuinely isn't one right answer, that framing can quietly mislead the ecosystem. Developers will gravitate toward it not because they've evaluated the tradeoffs, but because it looks official. That's a hard misconception to walk back.

I want to be clear about my intent here: I'm not trying to win an argument or push personal taste. I think we're actually aligned on the core difficulty — we just land in different places on whether to work within the current design or push back on it. Every point I've raised follows directly from Avalonia's own design DNA: DataTemplate-based dispatch, ViewModel-first composition, clear separation between intent and rendering. I'm not importing foreign ideas — I'm asking whether this API is faithful to the principles the framework itself taught us.

[stevemonaco]

But my concern is precisely that it is a workaround — and one that quietly pushes accidental complexity onto every consumer project. The moment you need a small utility method, a custom Content property, and manual DataTemplate wiring just to do basic ViewModel-first navigation, you've already lost the "it just works" guarantee that a framework-level API should provide.

I wrote a terrible XML parser for a data schema slightly more than 20 years ago using C++ and MSXML2. I was naive in believing that library methods should always be consumed directly and learned the value of creating specialized wrappers that suit your app's requirements. Use cases differ and having a flexible library is often more valuable than having a plug-and-play API. I don't even remember if I wrote utility methods for fetching...those all required COM allocations/frees for each bit of text grabbed via BSTR.

[omrzh]

But my concern is precisely that it is a workaround — and one that quietly pushes accidental complexity onto every consumer project. The moment you need a small utility method, a custom Content property, and manual DataTemplate wiring just to do basic ViewModel-first navigation, you've already lost the "it just works" guarantee that a framework-level API should provide.

I wrote a terrible XML parser for a data schema slightly more than 20 years ago using C++ and MSXML2. I was naive in believing that library methods should always be consumed directly and learned the value of creating specialized wrappers that suit your app's requirements. Use cases differ and having a flexible library is often more valuable than having a plug-and-play API. I don't even remember if I wrote utility methods for fetching...those all required COM allocations/frees for each bit of text grabbed via BSTR.

Steve, I could tell right away you're a seasoned developer — and your C++ war story proves it. That's a language I've never managed to tame myself, so I have nothing but respect.

I'm genuinely glad you're starting to see where I'm coming from. We're both people who've been bitten by frameworks. Maybe the difference is that you've earned the wisdom to endure it gracefully, while I'm still the fool who charges at the bull. I'd rather open a discussion than suffer in silence.

When 12.0 dropped with a new navigation API, I was excited — this was something I'd been waiting for, and had even considered rolling myself. But I know how hard that problem actually is. I've spent a long time wondering: why has WPF/Avalonia gone this many years without an official navigation API? My conclusion is almost paradoxical — precisely because the framework is so capable. Even if navigation ultimately reduces to a ContentControl.Content swap, the questions of who owns it, how it's orchestrated, and how side effects are managed have no single clean answer.

So I dug into the 12.0 source and worked through the INavigation contract. My conclusion: whether your project is vm-first or view-first, this API is going to bite you either way. I believe you've probably reasoned through this too — and if you landed somewhere different, I'd genuinely love to hear it.

I want to be clear: I wouldn't have opened this discussion if I didn't actually love Avalonia. I'm not claiming to be a great architect. But my argument isn't rooted in personal taste — it's rooted in the framework's own core primitives. That's what makes it sticky.

So here's the consensus I think we've actually reached: we all want a navigation API. But in its current form, it isn't ready to live in Avalonia.Controls — a namespace that carries real authority. Whether the API is "good" is debatable. What's harder to debate is this: navigation is inherently complex, and any solution to it is opinionated. That alone disqualifies it from a namespace that implies a standard answer.

Thanks for engaging with this so openly, Steve. Means a lot. 🤝

[Gillibald]

The name INavigation may be too generic for what it actually represents. In its current form, it’s a navigation concept tightly coupled to pages, which is why all operations work directly with page types. A truly general navigation abstraction shouldn’t depend on any specific view or viewmodel. That said, as others have pointed out, navigation patterns tend to be highly opinionated, so the right level of abstraction often depends on the architectural style you’re aiming for.

[BreyerW]

probably should have named it IPageNavigation then me think. At this point its just bike shedding but couldnt help myself after reading your reasoning and then whole conversation would be irrelevant as it would directly show that this is entirely by design

The only thing left is that maaaaaaaaaybe it shouldnt land in Avalonia.Controls or at least not in-box but as separate package since its not really generic enough solution to navigation. But that ship already sailed and we gonna live with it for the next 5-10 years i guess.

[robloo]

#21326

[NeverMorewd]

I’m currently integrating NavigationPage into my navigation framework based on my own preferences (a navigation framework inspired by MSDI and Prism-style design). I’ve found that NavigationPage is a very lightweight and fundamental design—you can think of it as a ContentControl with more features.It is not tightly coupled with INavigation.
Whether you follow MVVM or a VM-first approach, the current NavigationPage is fully capable.
For beginners or lightweight applications, using NavigationPage together with INavigation is very convenient. For more complex applications or highly customized scenarios, building another navigation framework on top of NavigationPage does not require more effort than building one based on ContentControl.
My current navigation framework has already integrated NavigationPage while maintaining neutrality at the ViewModel layer.
https://github.com/NeverMorewd/AsyncNavigation/blob/f7a7e08c2b20070b8a30ee26e4b67bb25f5084d7/src/AsyncNavigation.Avalonia/NavigationPageRegion.cs

[omrzh]

Brother, you're welcome to join the discussion, but you need to first understand what my actual arguments and supporting evidence are. I know how to use these APIs in my code—that's not what I'm discussing here.

[NeverMorewd]

I just want to say that INavigation is a simple navigation support provided by Avalonia. I think it’s similar to Splat in RxUI and SimpleIoC in Community.Mvvm. We wouldn’t go so far as to criticize Splat or SimpleIoC as being inadequate IoC containers.

Navigation is something that intersects with MVVM frameworks, IoC frameworks, and UI control libraries, so in the end it usually needs to be implemented according to specific needs. That said, I do agree with your idea—a VM-first navigation framework is something I’d like as well. I just personally lean toward implementing it outside the scope of Avalonia itself.

[omrzh]

I just want to say that INavigation is a simple navigation support provided by Avalonia. I think it’s similar to Splat in RxUI and SimpleIoC in Community.Mvvm. We wouldn’t go so far as to criticize Splat or SimpleIoC as being inadequate IoC containers.

Navigation is something that intersects with MVVM frameworks, IoC frameworks, and UI control libraries, so in the end it usually needs to be implemented according to specific needs. That said, I do agree with your idea—a VM-first navigation framework is something I’d like as well. I just personally lean toward implementing it outside the scope of Avalonia itself.

Friend, interface design is a bit like mathematics—contracts don't lie. The moment INavigation became heavily coupled to Page types, its flexibility was already spent. Any attempt to wrap around it will only face compounding complexity. I want to be clear: this isn't just my opinion—it's what the math says.

I'm glad we're on the same page about my actual argument. My intention in raising this was never to ask for help using the API—it was to encourage the Avalonia team to take an honest look at this design, because the conflict in conventions will inevitably leak complexity into user code.

On a separate note, I'd like to offer a thought on your NavigationPageRegion: it wraps a private NavigationPage internally, and in order to display a view, it's taking the long way around. The region already maintains its own navigation stack via RegionBase—so NavigationPage ends up contributing a second, parallel stack on top of it, with PushAsync being called to both activate and deactivate views. That's two stacks where one would do, and the back-stack state becomes a silent casualty. A plain ContentControl might serve the same purpose more directly—and more honestly, which is something I personally value in code design. This is also, I'd argue, a lived example of exactly the complexity leakage I described at the top of this thread. If there's something I'm missing, happy to discuss over PM.

Thanks for engaging, LaoTie.

[NeverMorewd]

Regarding the design of INavigation, to put it more plainly, it is intended to remain independent of the UI. If your ViewModel is required to stay completely neutral, then there is no need to use INavigation in the ViewModel. In fact, several patterns follow this principle.For example, when triggering notifications within a ViewModel, using WindowNotificationManager or Toplevel would inevitably couple the ViewModel to the UI, thereby breaking its neutrality. Such scenarios typically require additional abstraction or alternative handling.

Thank you for your attention to NavigationPageRegion. From a functional perspective, ContentControl can indeed serve as a replacement for NavigationPage. Accordingly, in my implementation, I have introduced constructs such as ContentRegion, ItemsRegion, TabRegion, as well as a forthcoming TabbedPageRegion.As page containers, my goal is to provide flexibility—users are free to choose the most suitable option, including even custom controls as navigation containers.Additionally, compared to ContentControl, NavigationPage offers extra features such as transition animations and a command bar, which may be advantageous depending on the use case.