docs(react,angular): use ionPage prop for nested outlets and add navigation playgrounds by ShaneK · Pull Request #4454 · ionic-team/ionic-docs

ShaneK · 2026-03-30T12:22:13Z

Resolves #2183

Description

Currently, several examples for using React Router are incorrectly showing wrapping IonRouter with IonPage instead of using the ionPage prop. Additionally, React and Angular have hard-coded links to StackBlitz that we do not control and have since moved away from in favor of playgrounds.

This PR does multiple things:

Fixes React Router demonstrations
Removes direct extremely outdated StackBlitz "Live Examples" in favor of Playgrounds

Change Type

Examples

Angular Navigation/Routing - Live Example

React Navigation/Routing - Should no longer have IonPage wrapping IonRouter and should use the ionPage prop instead. Additionally, stackblitz link under Live Example swapped for Playground

…tion guide

…mple

vercel · 2026-03-30T12:22:18Z

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

Project	Deployment	Actions	Updated (UTC)
ionic-docs	Ready	Preview, Comment	Mar 31, 2026 0:31am

brandyscarney · 2026-03-30T19:54:30Z

docs/angular/navigation.md

 ## Live Example

-If you would prefer to get hands on with the concepts and code described above, please checkout our [live example](https://stackblitz.com/edit/ionic-angular-routing?file=src/app/app-routing.module.ts) of the topics above on StackBlitz.
+<NavigationPlayground />


Suggested change

<NavigationPlayground />

import NavigationPlayground from '@site/static/usage/v9/angular/navigation/index.md';

<NavigationPlayground />

We normally import the playgrounds right before they're used:

ionic-docs/docs/api/accordion.md

Lines 55 to 57 in 9443312

import Multiple from '@site/static/usage/v8/accordion/multiple/index.md';

<Multiple />

This was done as part of my move to a unified Playground (spread across two commits, linked in a reply to another comment)

brandyscarney · 2026-03-30T19:54:46Z

docs/angular/navigation.md

 ---

 import useBaseUrl from '@docusaurus/useBaseUrl';
+import NavigationPlayground from '@site/static/usage/v9/angular/navigation/index.md';


Suggested change

import NavigationPlayground from '@site/static/usage/v9/angular/navigation/index.md';

See my first comment lower in this file

This was done as part of my move to a unified Playground (spread across two commits, linked in a reply to another comment)

brandyscarney · 2026-03-30T19:55:20Z

docs/react/navigation.md

 ## Live Example

-If you would prefer to get hands on with the concepts and code described above, please checkout our [live example](https://stackblitz.com/edit/ionic-react-routing?file=src/index.tsx) of the topics above on StackBlitz.
+<NavigationPlayground />


Suggested change

<NavigationPlayground />

import NavigationPlayground from '@site/static/usage/v9/react/navigation/index.md';

<NavigationPlayground />

We normally import the playgrounds right before they're used:

ionic-docs/docs/api/accordion.md

Lines 55 to 57 in 9443312

import Multiple from '@site/static/usage/v8/accordion/multiple/index.md';

<Multiple />

This was done as part of my move to a unified Playground (spread across two commits, linked in a reply to another comment)

brandyscarney · 2026-03-30T19:55:39Z

docs/react/navigation.md

 ---

 import useBaseUrl from '@docusaurus/useBaseUrl';
+import NavigationPlayground from '@site/static/usage/v9/react/navigation/index.md';


Suggested change

import NavigationPlayground from '@site/static/usage/v9/react/navigation/index.md';

See my first comment lower in this file

This was done as part of my move to a unified Playground (spread across two commits, linked in a reply to another comment)

brandyscarney · 2026-03-30T19:59:33Z

static/usage/v9/navigation/index.md

+  size="large"
+  includeIonContent={false}


Suggested change

size="large"

includeIonContent={false}

includeIonContent={false}

devicePreview={true}

Can we put this inside a device preview so it looks a bit nicer?

I didn't know how to do this before, thanks! This was done as part of my move to a unified Playground

brandyscarney · 2026-03-30T20:00:07Z

static/usage/v9/react/navigation/index.md

+  size="large"
+  includeIonContent={false}


Suggested change

size="large"

includeIonContent={false}

includeIonContent={false}

devicePreview={true}

Can we put this inside a device preview so it looks a bit nicer?

I didn't know how to do this before, thanks! This was done as part of my move to a unified Playground

brandyscarney · 2026-03-30T20:08:02Z

static/usage/v9/navigation/index.md

Rather than putting these under separate angular and react folders should we do one playground with both frameworks? Structure:

static └── usage └── v9 └── navigation ├── angular │ ├── app_component_html.md │ ├── app_component_ts.md │ ├── app_routes_ts.md │ ├── dashboard_page_component_html.md │ ├── dashboard_page_component_ts.md │ ├── example_component_html.md │ ├── example_component_ts.md │ ├── item_detail_page_component_html.md │ ├── item_detail_page_component_ts.md │ ├── settings_page_component_html.md │ └── settings_page_component_ts.md ├── react │ ├── dashboard_page_tsx.md │ ├── item_detail_page_tsx.md │ ├── main_tsx.md │ └── settings_page_tsx.md ├── demo.html └── index.md

This would allow us to add a JavaScript and Vue one if we would like.

So the reason was we couldn't previously is because then the React playground would show the Angular playground by default (unless you happened to have selected React from a component view before, in which case Angular would have shown React by default), which is a bad UX.

This inspired me to fix this, though, so in this commit (de72886) I added support for default frameworks and made the React and Angular pages use it, most of the work for combining them was done in this commit though (58873e4)

static/usage/v9/navigation/angular/dashboard_page_component_ts.md

static/usage/v9/angular/navigation/angular/dashboard_page_component_ts.md

brandyscarney · 2026-03-30T20:38:37Z

docs/react/navigation.md

-  );
-};
+const DashboardPage: React.FC = () => (
+  <IonRouterOutlet ionPage>


I don't understand why ionPage is now required. We have never recommended adding this as a property and it is not added to any of the playgrounds.

It's never been recommended because the docs have been known to be wrongly recommending wrapping IonRouterOutlet in IonPages for several years and nobody has fixed it (note the age of the issue this resolves).

Using the ionPage prop on the router outlet directly benefits mostly nested routes (it's required by them, technically). When you have an outlet containing routes and one of those routes renders another outlet, like in a tab layout, the inner outlet needs to know about and be able to participate in the outer outlet's page transitions. Setting the prop makes the inner outlet itself the animatable page element, so the outer StackManager can transition it properly.

It's generally best to do this everywhere so you don't have to remember to do it in the special nested routing edge cases, and that will also be the case in RR6.

…e directory

…act navigation live example to use one playground

ShaneK added 10 commits December 11, 2025 14:19

docs(react-router): working on v9 migration docs for react router

2b442d1

docs(react-router): update navigation guide and expand v5-to-v6 migra…

8fcf1cf

…tion guide

chore(lint): running lint

bcf73fe

fix(build): fixing build error

12981ad

docs(react-router): fixing several issues

1bd69b1

docs(react-router): converting playground example to rr6

d0f6f2f

docs(react-router): updating dependencies, reverting phrasing change

76552ed

docs(react): fix nested IonRouterOutlet examples and replace live exa…

d2401a0

…mple

fix(docs): use playground component for angular navigation

5228288

merge

30ac7db

ShaneK requested a review from a team as a code owner March 30, 2026 12:22

ShaneK requested review from brandyscarney and removed request for a team March 30, 2026 12:22

vercel bot deployed to Preview March 30, 2026 12:27 View deployment

chore(lint): running lint

686435b

vercel bot deployed to Preview March 30, 2026 12:33 View deployment

brandyscarney requested changes Mar 30, 2026

View reviewed changes

ShaneK added 2 commits March 30, 2026 13:48

fix(angular): add missing RouterLink import to dashboard component

12e3f60

refactor: consolidate angular/react navigation playgrounds into singl…

58873e4

…e directory

vercel bot deployed to Preview March 30, 2026 21:21 View deployment

ShaneK added 2 commits March 31, 2026 05:23

feat(playground): add default framework setting, migration angular/re…

de72886

…act navigation live example to use one playground

chore(git): merge

75c1dc0

vercel bot deployed to Preview March 31, 2026 12:31 View deployment

	import Multiple from '@site/static/usage/v8/accordion/multiple/index.md';

	<Multiple />

Conversation

ShaneK commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Change Type

Examples

Uh oh!

vercel bot commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ShaneK Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ShaneK commented Mar 30, 2026 •

edited

Loading

vercel bot commented Mar 30, 2026 •

edited

Loading

ShaneK Mar 31, 2026 •

edited

Loading

ShaneK Mar 31, 2026 •

edited

Loading

ShaneK Mar 31, 2026 •

edited

Loading

ShaneK Mar 30, 2026 •

edited

Loading