chore(react): enforce React 18 as the minimum supported version

[ShaneK]

Issue number: internal

---

What is the current behavior?

Currently, BREAKING.md and the v9 upgrade guide both state that Ionic 9 requires React 18, but nothing enforces it. @ionic/react and @ionic/react-router still declare react: >=16.8.6 in peerDependencies, byte-identical to v8, so a React 17 app installs Ionic 9 without an error. CI still builds and tests a react17 app, and both test-app sync scripts pass --legacy-peer-deps, which hides the mismatch.

The only signal a React 17 user gets today is a pair of npm warn ERESOLVE overriding peer dependency lines, coming from @stencil/react-output-target, which declares react: ^18 || ^19 and is a runtime dependency of @ionic/react. Because that peer is nested rather than direct, npm overrides it and installs anyway, so the documented floor never actually applies.

What is the new behavior?

Both packages now declare react: ^18 || ^19. Installing @ionic/react into a React 17 project fails with ERESOLVE, and the error names @ionic/react rather than the output target. We deleted the react17 test app and dropped it from the react matrix in build.yml and stencil-nightly.yml.

packages/react-router was still building against React 17 types, so its React devDependencies move to 18 alongside packages/react. That surfaced one genuine error the old types were hiding: StackManagerProps relied on the implicit children that @types/react 18 removed from React.Component, so it declares children: React.ReactNode now.

Does this introduce a breaking change?

• Yes
• No

Applications on React 17 need to move to React 18 or 19 before upgrading to Ionic 9. This changes enforcement rather than policy: #31063 dropped React 17 back in April with a BREAKING CHANGE footer and added the BREAKING.md row. What changes here is that npm install now refuses instead of installing with a warning. Technically React 17 may still work, but we do not officially support it.

Other information

On why the React 18 types weren't already breaking react-router: #31063 moved packages/react to React 18 in April and did the implicit-children migration in the same commit, adding explicit children: React.ReactNode declarations to IonPage, IonRouterOutlet, OutletPageManager, NavManager and others. It never touched packages/react-router, which stayed on @types/react: ^17.0.79. The two packages have separate tsconfigs and separate typecheck steps in CI, so nothing forced react-router to see React 18 types, and StackManager leaning on implicit children kept compiling against 17. It only failed once the devDependency bump in this PR put the 18 types in front of it.

The range is ^18 || ^19 rather than a >=18.0.0 floor so it matches @stencil/react-output-target exactly.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview	Aug 14, 2026 2:45pm

[brandyscarney]

Looks good! Just one question on a change.