Ionic React

Develop Ionic Framework apps with React — project structure, IonReactRouter, React-specific components, lifecycle hooks, state management, and best practices.

Prerequisites

Ionic Framework 7 or 8 with
```
@ionic/react
```
.
React 18 or later.
Node.js and npm installed.
For iOS: Xcode installed.
For Android: Android Studio installed.

Agent Behavior

Auto-detect before asking. Check the project for
```
package.json
```
dependencies (
```
@ionic/react
```
,
```
@ionic/react-router
```
,
```
react
```
,
```
@capacitor/core
```
), platforms (
```
android/
```
,
```
ios/
```
), build tools, and TypeScript usage. Only ask the user when something cannot be detected.
Guide step-by-step. Walk the user through the process one step at a time. Never present multiple unrelated questions at once.
Adapt to the project. Detect the existing code style (TypeScript vs. JavaScript, state management library, routing setup) and generate code that matches.

Procedures

Step 1: Analyze the Project

Auto-detect the following by reading project files:

Ionic version: Read
```
@ionic/react
```
version from
```
package.json
```
.
React version: Read
```
react
```
version from
```
package.json
```
.
Capacitor version: Read
```
@capacitor/core
```
version from
```
package.json
```
(if present).
TypeScript: Check if
```
tsconfig.json
```
exists and if
```
.tsx
```
files are used.

Router: Check if

@ionic/react-router

and

react-router-dom

are in

package.json

State management: Check

package.json

for

redux

@reduxjs/toolkit

zustand

jotai

@tanstack/react-query

, or similar.

Platforms: Check which directories exist (
```
android/
```
,
```
ios/
```
).

Build tool: Check for

vite.config.ts

angular.json

webpack.config.js

, etc.

Step 2: Project Structure

A standard Ionic React project follows this structure:

project-root/
├── android/                  # Android native project (Capacitor)
├── ios/                      # iOS native project (Capacitor)
├── public/
├── src/
│   ├── components/           # Reusable UI components
│   ├── hooks/                # Custom React hooks
│   ├── pages/                # Page components (one per route)
│   ├── services/             # Service modules for API and native calls
│   ├── context/              # React context providers
│   ├── theme/
│   │   └── variables.css     # Ionic CSS custom properties
│   ├── App.tsx               # Root component with IonReactRouter
│   └── main.tsx              # Entry point with setupIonicReact()
├── capacitor.config.ts       # Capacitor configuration
├── ionic.config.json         # Ionic CLI configuration
├── package.json
├── tsconfig.json
└── vite.config.ts            # Or other bundler config

If the project does not follow this structure, adapt all guidance to the project's actual directory layout. Do not restructure the project unless the user explicitly asks.

Step 3: App Initialization

The entry point must call

setupIonicReact()

before rendering the app. This function initializes the Ionic Framework for React.

Verify that

src/main.tsx

(or

src/index.tsx

) contains:

typescript

import { setupIonicReact } from '@ionic/react';

setupIonicReact();

setupIonicReact()

accepts an optional configuration object for global settings:

typescript

setupIonicReact({
  mode: 'ios',          // Force iOS mode on all platforms ('ios' | 'md')
  rippleEffect: false,  // Disable Material Design ripple effect
  animated: true,       // Enable/disable all animations
});

setupIonicReact()

is missing or called after rendering, Ionic components will not function correctly.

Step 4: Routing and Navigation

Read

references/routing.md

for complete routing patterns including:

```
IonReactRouter
```
setup
```
IonRouterOutlet
```
page management
Tab-based navigation with
```
IonTabs
```
Side menu navigation with
```
IonMenu
```
Programmatic navigation with
```
useIonRouter
```
Route guards and route parameters

Key principles:

Use
IonReactRouter
instead of React Router's
```
BrowserRouter
```
. It is required for Ionic page transitions.
Use
IonRouterOutlet
to contain routes. It manages the page stack and transition animations.

Pass
component
prop to
Route
— do not use

render

children

inside

IonRouterOutlet

Use
useIonRouter
for programmatic navigation — it provides Ionic-aware navigation with transition animations.

Step 5: Ionic Lifecycle Hooks

Read

references/lifecycle.md

for detailed lifecycle hook usage.

Ionic React pages stay mounted in the DOM after navigation. Standard React

useEffect

only fires on initial mount, not on every page visit. Use Ionic lifecycle hooks for per-visit logic:

Hook	Use for
`useIonViewWillEnter`	Refresh data before the page becomes visible
`useIonViewDidEnter`	Start animations or focus inputs after page is visible
`useIonViewWillLeave`	Pause media, save draft state
`useIonViewDidLeave`	Cleanup after page is fully hidden

These hooks only work in components that:

Are rendered as the
```
component
```
of a
```
Route
```
inside
```
IonRouterOutlet
```
.
Render
```
IonPage
```
as their root element.

Step 6: React-Specific Ionic Hooks

Read

references/hooks.md

for all available hooks and usage examples.

Ionic React provides hooks for presenting overlays and controlling navigation without managing state manually:

Hook	Purpose
`useIonAlert`	Present alert dialogs
`useIonToast`	Show toast notifications
`useIonActionSheet`	Present action sheets
`useIonLoading`	Show/dismiss loading indicators
`useIonModal`	Present modals programmatically
`useIonPopover`	Present popovers programmatically
`useIonPicker`	Present picker dialogs
`useIonRouter`	Navigate with Ionic animations

Step 7: React-Specific Component Patterns

Read

references/components.md

for detailed component patterns including:

Page structure with
```
IonPage
```
Inline overlays (modals, popovers) with
```
isOpen
```
binding
Pull-to-refresh with
```
IonRefresher
```
Infinite scroll with
```
IonInfiniteScroll
```
Forms with Ionic input components

Key principles:

Every page must render
IonPage
as root. This is required for transitions and lifecycle hooks.
Use
onIonInput
for text inputs and
```
onIonChange
```
for select, toggle, checkbox, and range components.
Access values via
e.detail.value
(or
```
e.detail.checked
```
for toggles/checkboxes).
Use inline overlays with
isOpen
for simpler state management, or use overlay hooks (
```
useIonModal
```
,
```
useIonAlert
```
, etc.) for imperative usage.

Step 8: State Management

Read

references/state-management.md

for patterns with React Context, Redux Toolkit, Zustand, and TanStack Query.

Key principles:

Page caching affects state. Since Ionic keeps pages mounted, state persists across navigations. Use
```
useIonViewWillEnter
```
to refresh stale data.
Place providers outside
IonReactRouter
. Context providers, Redux
```
Provider
```
, and
```
QueryClientProvider
```
should wrap the router so all pages have access.
Do not add a state library unless needed. For simple apps, React Context and
```
useState
```
/
```
useReducer
```
are sufficient.

Step 9: Build and Run

After implementing changes:

bash

npm run build
npx cap sync
npx cap run android
npx cap run ios

For development with live reload:

bash

ionic serve

For native development with live reload:

bash

ionic cap run android --livereload --external
ionic cap run ios --livereload --external

Error Handling

Ionic lifecycle hooks not firing: Verify that the component renders
```
IonPage
```
as its root element and is the
```
component
```
of a
```
Route
```
inside
```
IonRouterOutlet
```
. Lifecycle hooks do not fire in child components or components rendered via
```
render
```
/
```
children
```
props.
Page transitions not animating: Ensure
```
IonReactRouter
```
is used instead of
```
BrowserRouter
```
. Ensure routes use the
```
component
```
prop, not
```
render
```
or
```
children
```
. Verify
```
IonRouterOutlet
```
is a direct child of
```
IonReactRouter
```
or
```
IonTabs
```
.
Stale data after navigating back: Ionic keeps pages mounted in the DOM. Use
```
useIonViewWillEnter
```
to refresh data on every page visit instead of
```
useEffect
```
with
```
[]
```
.
Tab bar disappears on sub-page: All routes (including detail routes) must be inside the
```
IonRouterOutlet
```
within
```
IonTabs
```
. Do not nest a separate
```
IonRouterOutlet
```
inside a tab page.
setupIonicReact
errors or components not rendering: Ensure
```
setupIonicReact()
```
is called before
```
ReactDOM.createRoot()
```
or
```
ReactDOM.render()
```
in the entry file. Ensure all Ionic CSS files are imported (see Ionic CSS imports in
```
src/App.tsx
```
or
```
src/main.tsx
```
).
IonBackButton
not appearing:
```
IonBackButton
```
only renders when there is navigation history. Set the
```
defaultHref
```
prop to provide a fallback route when the page is accessed directly.

Form input values not updating: Use

onIonInput

for

IonInput

IonTextarea

(not

onChange

). Use

onIonChange

for

IonSelect

IonToggle

IonCheckbox

IonRange

. Access values via

e.detail.value

Modal or popover content not styled: Ensure the overlay content is wrapped in
```
IonContent
```
. For modals, include
```
IonHeader
```
with
```
IonToolbar
```
if a toolbar is needed.
React strict mode double-mounting: In development, React 18 strict mode mounts components twice. This can cause duplicate Ionic event listeners. Ensure cleanup functions properly remove listeners.
useIonRouter
returns undefined: The hook must be used inside a component that is a descendant of
```
IonReactRouter
```
. Verify the component tree includes
```
IonReactRouter
```
as an ancestor.
CSS custom properties not applying: Ensure Ionic CSS files are imported in the correct order in
```
src/App.tsx
```
or
```
src/main.tsx
```
. The theme
```
variables.css
```
file must be imported after the core Ionic CSS.

Related Skills

ionic-app-development
— General Ionic development covering components, theming, and CLI usage.
ionic-app-creation
— Create a new Ionic app from scratch.
capacitor-react
— Capacitor-specific React patterns for accessing native device features (without Ionic Framework).
ionic-app-upgrades
— Upgrade Ionic Framework to a newer version.
capacitor-plugins
— Install, configure, and use Capacitor plugins from official and community sources.

ionic-react

NPX Install

Tags

SKILL.md Content

Ionic React

Prerequisites

Agent Behavior

Procedures

Step 1: Analyze the Project

Step 2: Project Structure

Step 3: App Initialization

Step 4: Routing and Navigation

Step 5: Ionic Lifecycle Hooks

Step 6: React-Specific Ionic Hooks

Step 7: React-Specific Component Patterns

Step 8: State Management

Step 9: Build and Run

Error Handling

Related Skills