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/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. 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