ionic-react

What this skill does

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

```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
});
```

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:

```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

- **