feat(react): type overlay hook component props

[ShaneK]

Issue number: resolves #28680

---

What is the current behavior?

Currently, useIonModal and useIonPopover take componentProps as any, so nothing checks the props against the component being presented. Typos and missing props show up at runtime instead of at build time.

This has been attempted three times. #28685 and #29058 stalled in review, and #29158 was auto-closed when the feature-8.0 branch was deleted rather than rejected. All three were deferred on the grounds that the added strictness needed a major, which is what this branch is. The most recent community attempt, #31183, leaves componentProps optional, which brings back the gap that earlier review had already settled: a component with required props still type checks when you pass no props at all.

What is the new behavior?

Both hooks now infer Props from the component and check componentProps against it, and componentProps is required when the component declares required props. Passing a JSX element is unchanged and stays permissive.

Props comes from the component alone, using NoInfer on componentProps. That part isn't cosmetic. The overlay docs pass dismiss back in through componentProps, and inferring from that argument needs the type of dismiss while the same statement is still declaring it, which TypeScript rejects as circular. The cost is that a component declared inline needs its props annotated.

NoInfer lands in the published types, so @ionic/react now needs TypeScript 5.4. @ionic/angular already required 5.4, so this lines them up, and a new react-typescript migration raises the pin for React apps the same way angular-typescript does.

Writing this turned up two existing mistakes that the old any was hiding: the root modal in the React test app was rendering with type and count undefined, and the v9 modal controller docs example didn't type check. Both are fixed.

Does this introduce a breaking change?

• Yes
• No

Apps passing props that don't match their component will get new compile errors, which is the point of the change. The fix is to correct the call sites. Apps below TypeScript 5.4 need to upgrade, and npx @ionic/migrate handles the pin. Notes are in BREAKING.md and the v9 upgrade guide.

Other information

The overload shape comes from Liam's #29158, the requirement that componentProps can't be omitted comes from Alexander's review on #29058, and the compile-time spec pattern comes from Ren yiwei's #31183. All three are credited as co-authors on the commit.

Nothing to preview. The change is types only at runtime.

Also, I'm aware this is way too close to the release of v9. This may need to be held off until v10, which won't be too long after v9 comes out.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
ionic-framework	Ready	Preview	Aug 16, 2026 4:56pm