capawesome-team/ionic-react

Ionic React

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

Prerequisites

1. Ionic Framework 7 or 8 with @ionic/react.
2. React 18 or later.
3. Node.js and npm installed.
4. For iOS: Xcode installed.
5. 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:

1. Ionic version: Read @ionic/react version from package.json.
2. React version: Read react version from package.json.
3. Capacitor version: Read @capacitor/core version from package.json (if present).
4. TypeScript: Check if tsconfig.json exists and if .tsx files are used.
5. Router: Check if @ionic/react-router and react-router-dom are in package.json.
6. State management: Check package.json for redux, @reduxjs/toolkit, zustand, jotai, @tanstack/react-query, or similar.
7. Platforms: Check which directories exist (android/, ios/).
8. 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:

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

setupIonicReact();

setupIonicReact() accepts an optional configuration object for global settings:

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

If 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:

1. Use IonReactRouter instead of React Router's BrowserRouter. It is required for Ionic page transitions.
2. Use IonRouterOutlet to contain routes. It manages the page stack and transition animations.
3. Pass component prop to Route — do not use render or children inside IonRouterOutlet.
4. 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:

1. Every page must render IonPage as root. This is required for transitions and lifecycle hooks.
2. Use onIonInput for text inputs and onIonChange for select, toggle, checkbox, and range components.
3. Access values via e.detail.value (or e.detail.checked for toggles/checkboxes).
4. 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:

1. Page caching affects state. Since Ionic keeps pages mounted, state persists across navigations. Use useIonViewWillEnter to refresh stale data.
2. Place providers outside IonReactRouter. Context providers, Redux Provider, and QueryClientProvider should wrap the router so all pages have access.
3. 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:

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

For development with live reload:

ionic serve

For native development with live reload:

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.