From 5756863e4262f2e060b6c839d4f1ab965c859c47 Mon Sep 17 00:00:00 2001 From: ShaneK Date: Tue, 14 Jul 2026 06:48:21 -0700 Subject: [PATCH 1/3] docs(router): remove ion-nav from coordinated navigation outlets --- docs/api/router.md | 8 ++++---- versioned_docs/version-v7/api/router.md | 8 ++++---- versioned_docs/version-v8/api/router.md | 8 ++++---- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/docs/api/router.md b/docs/api/router.md index 0ecfbf832f0..05e312d8328 100644 --- a/docs/api/router.md +++ b/docs/api/router.md @@ -11,7 +11,7 @@ import Slots from '@ionic-internal/component-api/v9/router/slots.md'; ion-router: Router Component to Coordinate URL Navigation - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -28,11 +28,11 @@ The router is a component for handling routing inside vanilla and Stencil JavaSc Apps should have a single `ion-router` component in the codebase. This component controls all interactions with the browser history and it aggregates updates through an event system. -`ion-router` is just a URL coordinator for the navigation outlets of ionic: `ion-nav`, `ion-tabs`, and `ion-router-outlet`. +`ion-router` is just a URL coordinator for the navigation outlets of ionic: `ion-tabs` and `ion-router-outlet`. -That means the `ion-router` never touches the DOM, it does NOT show the components or emit any kind of lifecycle events, it just tells `ion-nav`, `ion-tabs`, and `ion-router-outlet` what and when to "show" based on the browser's URL. +That means the `ion-router` never touches the DOM, it does NOT show the components or emit any kind of lifecycle events, it just tells `ion-tabs` and `ion-router-outlet` what and when to "show" based on the browser's URL. -In order to configure this relationship between components (to load/select) and URLs, `ion-router` uses a declarative syntax using JSX/HTML to define a tree of routes. +To configure this relationship between components (to load/select) and URLs, `ion-router` uses a declarative syntax using JSX/HTML to define a tree of routes. ## Basic Usage diff --git a/versioned_docs/version-v7/api/router.md b/versioned_docs/version-v7/api/router.md index 122a3f17445..c574f982389 100644 --- a/versioned_docs/version-v7/api/router.md +++ b/versioned_docs/version-v7/api/router.md @@ -13,7 +13,7 @@ import Slots from '@ionic-internal/component-api/v7/router/slots.md'; ion-router: Router Component to Coordinate URL Navigation @@ -28,11 +28,11 @@ Note: This component should only be used with vanilla and Stencil JavaScript pro Apps should have a single `ion-router` component in the codebase. This component controls all interactions with the browser history and it aggregates updates through an event system. -`ion-router` is just a URL coordinator for the navigation outlets of ionic: `ion-nav`, `ion-tabs`, and `ion-router-outlet`. +`ion-router` is just a URL coordinator for the navigation outlets of ionic: `ion-tabs` and `ion-router-outlet`. -That means the `ion-router` never touches the DOM, it does NOT show the components or emit any kind of lifecycle events, it just tells `ion-nav`, `ion-tabs`, and `ion-router-outlet` what and when to "show" based on the browser's URL. +That means the `ion-router` never touches the DOM, it does NOT show the components or emit any kind of lifecycle events, it just tells `ion-tabs` and `ion-router-outlet` what and when to "show" based on the browser's URL. -In order to configure this relationship between components (to load/select) and URLs, `ion-router` uses a declarative syntax using JSX/HTML to define a tree of routes. +To configure this relationship between components (to load/select) and URLs, `ion-router` uses a declarative syntax using JSX/HTML to define a tree of routes. ## Basic Usage diff --git a/versioned_docs/version-v8/api/router.md b/versioned_docs/version-v8/api/router.md index b910f227e46..b65c14eafd3 100644 --- a/versioned_docs/version-v8/api/router.md +++ b/versioned_docs/version-v8/api/router.md @@ -13,7 +13,7 @@ import Slots from '@ionic-internal/component-api/v8/router/slots.md'; ion-router: Router Component to Coordinate URL Navigation @@ -28,11 +28,11 @@ Note: This component should only be used with vanilla and Stencil JavaScript pro Apps should have a single `ion-router` component in the codebase. This component controls all interactions with the browser history and it aggregates updates through an event system. -`ion-router` is just a URL coordinator for the navigation outlets of ionic: `ion-nav`, `ion-tabs`, and `ion-router-outlet`. +`ion-router` is just a URL coordinator for the navigation outlets of ionic: `ion-tabs` and `ion-router-outlet`. -That means the `ion-router` never touches the DOM, it does NOT show the components or emit any kind of lifecycle events, it just tells `ion-nav`, `ion-tabs`, and `ion-router-outlet` what and when to "show" based on the browser's URL. +That means the `ion-router` never touches the DOM, it does NOT show the components or emit any kind of lifecycle events, it just tells `ion-tabs` and `ion-router-outlet` what and when to "show" based on the browser's URL. -In order to configure this relationship between components (to load/select) and URLs, `ion-router` uses a declarative syntax using JSX/HTML to define a tree of routes. +To configure this relationship between components (to load/select) and URLs, `ion-router` uses a declarative syntax using JSX/HTML to define a tree of routes. ## Basic Usage From 35944efc057715a8a012d75123ce646afd2e849a Mon Sep 17 00:00:00 2001 From: ShaneK Date: Tue, 14 Jul 2026 08:00:55 -0700 Subject: [PATCH 2/3] docs(updating): document ion-nav no longer integrating with ion-router in v9 --- docs/updating/9-0.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/docs/updating/9-0.md b/docs/updating/9-0.md index a3099907284..46aea423bc6 100644 --- a/docs/updating/9-0.md +++ b/docs/updating/9-0.md @@ -490,6 +490,34 @@ The `autocorrect` property on `ion-searchbar` is now a `boolean` (default `false - Remove the attribute to keep autocorrect disabled (the default). - Use a property binding to enable it: `[autocorrect]="true"` (Angular), `autocorrect={true}` (React), or `:autocorrect="true"` (Vue). +### Nav + +`ion-nav` no longer integrates with `ion-router`. It is now a standalone imperative stack navigation component, driven only through its own API (`root`, `push`, `pop`, `setRoot`, and so on) and `ion-nav-link`. + +This only affects apps that placed an `ion-nav` inside an `ion-router` (vanilla JavaScript projects) and relied on the router to drive it. If you use `ion-nav` on its own for local, in-page stack navigation, no changes are required. + +The following behaviors have been removed: + +- The router no longer discovers or drives an `ion-nav`. Placing an `ion-nav` inside an `ion-router` no longer turns it into a routed outlet. +- Navigating an `ion-nav` (via `push`, `pop`, `ion-nav-link`, or the swipe-to-go-back gesture) no longer updates the URL, and the router's navigation guards no longer run for `ion-nav` transitions. +- The `setRouteId()` and `getRouteId()` methods and the `updateURL` nav option have been removed. These existed only for the router integration. + +If you relied on `ion-nav` to update the URL, use `ion-router-outlet` for URL-based routing instead: + +```diff +- +- +- ++ +``` + +An `ion-nav` can still be nested inside a routed page for local, URL-less stack navigation: + +```html + + +``` + ## Need Help Upgrading? Be sure to look at the [Ionic 9 Breaking Changes Guide](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-9x) for the complete list of breaking changes. This upgrade guide only covers changes that require action from developers. From 7e0063a8c16a7b073e6350197466c4523677d188 Mon Sep 17 00:00:00 2001 From: ShaneK Date: Thu, 16 Jul 2026 09:49:17 -0700 Subject: [PATCH 3/3] docs(router): add ion-nav within routed page example and clarify migration --- docs/api/router.md | 10 ++ docs/updating/9-0.md | 18 ++-- .../usage/v9/router/nav-within-page/demo.html | 98 +++++++++++++++++++ .../usage/v9/router/nav-within-page/index.md | 11 +++ .../v9/router/nav-within-page/javascript.md | 77 +++++++++++++++ 5 files changed, 204 insertions(+), 10 deletions(-) create mode 100644 static/usage/v9/router/nav-within-page/demo.html create mode 100644 static/usage/v9/router/nav-within-page/index.md create mode 100644 static/usage/v9/router/nav-within-page/javascript.md diff --git a/docs/api/router.md b/docs/api/router.md index 05e312d8328..63dc4d3915c 100644 --- a/docs/api/router.md +++ b/docs/api/router.md @@ -40,6 +40,16 @@ import BasicExample from '@site/static/usage/v9/router/basic/index.md'; +## Using ion-nav within a Routed Page + +`ion-router` and [`ion-nav`](./nav.md) are separate systems. `ion-router` coordinates URL-based navigation through `ion-router-outlet`, while `ion-nav` manages a local stack that is independent of the URL. As of Ionic 9, `ion-nav` no longer integrates with `ion-router`: placing an `ion-nav` inside an `ion-router` does not turn it into a routed outlet, and pushing or popping views on an `ion-nav` never changes the URL. Refer to the [migration guide](../updating/9-0.md#nav) for details. + +The two can still be composed. A routed page rendered by `ion-router-outlet` can host its own `ion-nav` for local, URL-less navigation within that page. In the example below, navigating to Details updates the URL, but stepping through the `ion-nav` inside that page does not. + +import NavWithinPageExample from '@site/static/usage/v9/router/nav-within-page/index.md'; + + + ## Interfaces ### RouterEventDetail diff --git a/docs/updating/9-0.md b/docs/updating/9-0.md index 46aea423bc6..20675f706d6 100644 --- a/docs/updating/9-0.md +++ b/docs/updating/9-0.md @@ -502,21 +502,19 @@ The following behaviors have been removed: - Navigating an `ion-nav` (via `push`, `pop`, `ion-nav-link`, or the swipe-to-go-back gesture) no longer updates the URL, and the router's navigation guards no longer run for `ion-nav` transitions. - The `setRouteId()` and `getRouteId()` methods and the `updateURL` nav option have been removed. These existed only for the router integration. -If you relied on `ion-nav` to update the URL, use `ion-router-outlet` for URL-based routing instead: +If you relied on `ion-nav` to update the URL, use `ion-router-outlet` for URL-based routing instead. Keep the `ion-route` definitions and swap the outlet element: ```diff -- -- -- + + + + + +- + ``` -An `ion-nav` can still be nested inside a routed page for local, URL-less stack navigation: - -```html - - -``` +An `ion-nav` can still be nested inside a routed page for local, URL-less stack navigation. It manages its own stack via `root` and `ion-nav-link`, and the URL never changes as you push and pop. For a complete, working example, refer to [Using ion-nav within a Routed Page](../api/router.md#using-ion-nav-within-a-routed-page). ## Need Help Upgrading? diff --git a/static/usage/v9/router/nav-within-page/demo.html b/static/usage/v9/router/nav-within-page/demo.html new file mode 100644 index 00000000000..3d043e183fc --- /dev/null +++ b/static/usage/v9/router/nav-within-page/demo.html @@ -0,0 +1,98 @@ + + + + + + Router | ion-nav within a Routed Page + + + + + + + + + + + + + + + + + + + + diff --git a/static/usage/v9/router/nav-within-page/index.md b/static/usage/v9/router/nav-within-page/index.md new file mode 100644 index 00000000000..3230e6ae931 --- /dev/null +++ b/static/usage/v9/router/nav-within-page/index.md @@ -0,0 +1,11 @@ +import Playground from '@site/src/components/global/Playground'; + +import javascript from './javascript.md'; + + diff --git a/static/usage/v9/router/nav-within-page/javascript.md b/static/usage/v9/router/nav-within-page/javascript.md new file mode 100644 index 00000000000..55b37205740 --- /dev/null +++ b/static/usage/v9/router/nav-within-page/javascript.md @@ -0,0 +1,77 @@ +```html + + + + + + + + + +```