feat(nav): remove ion-router integration

[ShaneK]

Issue number: internal

---

What is the current behavior?

ion-nav doubles as an ion-router outlet. On load, nav.tsx checks document.querySelector('ion-router') to set a useRouter flag, and ion-nav is listed in the router's OUTLET_SELECTOR. When the router drives it, ion-nav exposes internal setRouteId()/getRouteId() methods, runs router.canTransition() guards inside queueTrns, and calls router.navChanged() on a successful transition so that push/pop, ion-nav-link, and swipe-to-go-back all update the URL. This couples an imperative stack component to URL-based routing

What is the new behavior?

ion-nav is now a standalone imperative stack-navigation component with no ion-router integration. It implements ComponentInterface instead of NavOutlet and drops useRouter, the setRouteId()/getRouteId() methods, the canTransition() guard check, the navChanged() URL update, the root-attribute-with-router warning, and the updateURL nav option. The router no longer lists ion-nav in OUTLET_SELECTOR, so an ion-nav placed inside an ion-router is no longer discovered or driven as a routed outlet

Dropping ion-nav from OUTLET_SELECTOR exposed a hang: a page with an ion-router but no ion-router-outlet or ion-tabs (the #24641 pattern) left waitUntilNavNode() waiting forever, so the router's componentWillLoad never settled and the app never signalled that it finished loading. waitUntilNavNode() now resolves on ionNavWillLoad or a 500ms timeout, and warns in dev when no outlet is found

Does this introduce a breaking change?

• Yes
• No

Apps that relied on ion-nav to update the URL (pushing components and expecting the browser URL to change, or having router guards run on nav transitions) should use ion-router-outlet for URL-based routing. An ion-nav can still be used inside a routed page for local, URL-less stack navigation. See the Nav section in BREAKING.md for the migration path.

Other information

BREAKING.md is updated with a new Nav section and route.tsx doc now lists ion-router-outlet instead of ion-nav as the navigation outlet

Preview (nav routing test page):

• https://ionic-framework-git-fw-6976-ionic1.vercel.app/src/components/nav/test/routing

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview, Comment	Jul 14, 2026 5:41pm

[thetaPC]

LGTM

[thetaPC]

It might be helpful to include the example from the docs PR to let devs know how to update their apps:

- <ion-router>
-   <ion-nav root="page-one"></ion-nav>
- </ion-router>
+ <ion-router-outlet></ion-router-outlet>

[ShaneK]

ecbf364