Skip to content

docs(router): remove ion-nav from coordinated navigation outlets #4585

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ShaneK wants to merge 2 commits into
base: major-9.0
Choose a base branch
from
+40 −12
Open

docs(router): remove ion-nav from coordinated navigation outlets #4585

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5756863
docs(router): remove ion-nav from coordinated navigation outlets
ShaneK Jul 14, 2026
35944ef
docs(updating): document ion-nav no longer integrating with ion-route…
ShaneK Jul 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/api/router.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import Slots from '@ionic-internal/component-api/v9/router/slots.md';

<head>
<title>ion-router: Router Component to Coordinate URL Navigation</title>
<meta name="description" content="ion-router is a URL coordinator for navigation outlets of ionic: ion-nav and ion-tabs. Router components handle routing inside vanilla and Stencil JavaScript." />
<meta name="description" content="ion-router is a URL coordinator for navigation outlets of ionic: ion-tabs and ion-router-outlet. Router components handle routing inside vanilla and Stencil JavaScript." />
</head>

import EncapsulationPill from '@components/page/api/EncapsulationPill';
Expand All @@ -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

Expand Down
28 changes: 28 additions & 0 deletions docs/updating/9-0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
- <ion-router>
- <ion-nav root="page-one"></ion-nav>
- </ion-router>
+ <ion-router-outlet></ion-router-outlet>
```

An `ion-nav` can still be nested inside a routed page for local, URL-less stack navigation:

```html
<!-- Inside a routed page component -->
<ion-nav root="page-one"></ion-nav>
```

## 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.
Expand Down
8 changes: 4 additions & 4 deletions versioned_docs/version-v7/api/router.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import Slots from '@ionic-internal/component-api/v7/router/slots.md';
<title>ion-router: Router Component to Coordinate URL Navigation</title>
<meta
name="description"
content="ion-router is a URL coordinator for navigation outlets of ionic: ion-nav and ion-tabs. Router components handle routing inside vanilla and Stencil JavaScript."
content="ion-router is a URL coordinator for navigation outlets of ionic: ion-tabs and ion-router-outlet. Router components handle routing inside vanilla and Stencil JavaScript."
/>
</head>

Expand All @@ -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

Expand Down
8 changes: 4 additions & 4 deletions versioned_docs/version-v8/api/router.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ import Slots from '@ionic-internal/component-api/v8/router/slots.md';
<title>ion-router: Router Component to Coordinate URL Navigation</title>
<meta
name="description"
content="ion-router is a URL coordinator for navigation outlets of ionic: ion-nav and ion-tabs. Router components handle routing inside vanilla and Stencil JavaScript."
content="ion-router is a URL coordinator for navigation outlets of ionic: ion-tabs and ion-router-outlet. Router components handle routing inside vanilla and Stencil JavaScript."
/>
</head>

Expand All @@ -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

Expand Down
Loading