0
# @ionic/react
1

2
@ionic/react is a React-specific wrapper for @ionic/core that provides React components, hooks, and utilities for building cross-platform mobile applications. It offers a comprehensive set of React components that wrap Ionic's web components, providing native React patterns like JSX props, React events, and TypeScript support while maintaining full compatibility with Ionic's theming system and native mobile capabilities.
3

4
## Package Information
5

6
- **Package Name**: @ionic/react
7
- **Package Type**: npm  
8
- **Language**: TypeScript
9
- **Installation**: `npm install @ionic/react`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  // Core components
16
  IonApp, IonPage, IonContent, IonButton, IonInput,
17
  // Overlay hooks
18
  useIonAlert, useIonModal, useIonToast, useIonActionSheet, 
19
  useIonPopover, useIonLoading, useIonPicker,
20
  // Lifecycle hooks
21
  useIonViewDidEnter, useIonViewWillEnter,
22
  // Setup and utilities
23
  setupIonicReact, isPlatform, createAnimation, createGesture,
24
  // Additional components
25
  IonFab, IonFabButton, IonDatetime, IonInfiniteScroll, IonRefresher
26
} from "@ionic/react";
27
```
28

29
For CommonJS:
30

31
```javascript
32
const { 
33
  // Core components
34
  IonApp, IonPage, IonContent, IonButton, IonInput,
35
  // Overlay hooks
36
  useIonAlert, useIonModal, useIonToast, useIonActionSheet, 
37
  useIonPopover, useIonLoading, useIonPicker,
38
  // Lifecycle hooks
39
  useIonViewDidEnter, useIonViewWillEnter,
40
  // Setup and utilities
41
  setupIonicReact, isPlatform, createAnimation, createGesture,
42
  // Additional components
43
  IonFab, IonFabButton, IonDatetime, IonInfiniteScroll, IonRefresher
44
} = require("@ionic/react");
45
```
46

47
## Basic Usage
48

49
```typescript
50
import React from 'react';
51
import { IonApp, IonPage, IonHeader, IonToolbar, IonTitle, IonContent, IonButton, setupIonicReact } from '@ionic/react';
52

53
// Initialize Ionic React
54
setupIonicReact();
55

56
const MyApp: React.FC = () => (
57
  <IonApp>
58
    <IonPage>
59
      <IonHeader>
60
        <IonToolbar>
61
          <IonTitle>My Ionic App</IonTitle>
62
        </IonToolbar>
63
      </IonHeader>
64
      <IonContent>
65
        <IonButton expand="block">Click Me</IonButton>
66
      </IonContent>
67
    </IonPage>
68
  </IonApp>
69
);
70

71
export default MyApp;
72
```
73

74
## Architecture
75

76
@ionic/react is built around several key architectural patterns:
77

78
- **Component Wrappers**: React components that wrap Ionic web components, providing seamless integration with React's virtual DOM
79
- **Hook-based APIs**: React hooks for managing overlays, lifecycle events, and platform detection
80
- **Router Integration**: Custom routing system that works with React Router while maintaining native-like navigation stacks
81
- **Platform Abstraction**: Utilities for detecting and adapting to different platforms (iOS, Android, web)
82
- **Overlay Management**: Declarative and imperative APIs for managing modals, alerts, toasts, and other overlays
83

84
## Capabilities
85

86
### Core Setup and Application Structure
87

88
Essential components and setup functions for initializing and structuring Ionic React applications.
89

90
```typescript { .api }
91
function setupIonicReact(config?: IonicConfig): void;
92

93
interface IonicConfig {
94
  // Configuration interface is re-exported from @ionic/core
95
  // Contains numerous platform-specific settings for animations,
96
  // gestures, theming, and component behavior
97
  [key: string]: any;
98
}
99
```
100

101
[Core Setup](./core-setup.md)
102

103
### UI Components
104

105
Comprehensive set of UI components for building mobile interfaces, including layout, forms, data display, and feedback components.
106

107
```typescript { .api }
108
// Layout Components
109
const IonApp: React.FC<IonicReactProps>;
110
const IonPage: React.FC<IonicReactProps>;  
111
const IonContent: React.FC<IonicReactProps>;
112
const IonHeader: React.FC<IonicReactProps>;
113
const IonToolbar: React.FC<IonicReactProps>;
114

115
// Form Components
116
const IonInput: React.FC<IonicReactProps>;
117
const IonButton: React.FC<IonicReactProps>;
118
const IonCheckbox: React.FC<IonicReactProps>;
119
const IonToggle: React.FC<IonicReactProps>;
120

121
// Data Display
122
const IonList: React.FC<IonicReactProps>;
123
const IonItem: React.FC<IonicReactProps>;
124
const IonCard: React.FC<IonicReactProps>;
125
```
126

127
[UI Components](./ui-components.md)
128

129
### Navigation and Routing
130

131
Complete routing system with stack management, tabs, and navigation components designed for mobile applications.
132

133
```typescript { .api }
134
const IonRouterOutlet: React.FC<{
135
  basePath?: string;
136
  ionPage?: boolean;
137
}>;
138

139
const IonRoute: React.FC<{
140
  path?: string;
141
  exact?: boolean;
142
  render: (props?: any) => JSX.Element;
143
  disableIonPageManagement?: boolean;
144
}>;
145

146
const IonTabs: React.FC<{
147
  onIonTabsWillChange?: (event: any) => void;
148
  onIonTabsDidChange?: (event: any) => void;
149
}>;
150
```
151

152
[Navigation and Routing](./navigation-routing.md)
153

154
### Overlay Management
155

156
React hooks for managing modal dialogs, alerts, toasts, action sheets, and other overlay components.
157

158
```typescript { .api }
159
function useIonAlert(): [
160
  {
161
    (message: string, buttons?: AlertButton[]): Promise<void>;
162
    (options: AlertOptions): Promise<void>;
163
  },
164
  () => Promise<void>
165
];
166

167
function useIonModal(
168
  component: React.ComponentType<any>,
169
  componentProps?: any
170
): [
171
  (options?: ModalOptions) => Promise<void>,
172
  () => void
173
];
174

175
function useIonToast(): [
176
  (options: ToastOptions) => Promise<void>,
177
  () => void
178
];
179
```
180

181
[Overlay Management](./overlay-management.md)
182

183
### Lifecycle Management
184

185
React hooks for managing page lifecycle events and navigation state in mobile applications.
186

187
```typescript { .api }
188
function useIonViewDidEnter(
189
  callback: LifeCycleCallback,
190
  deps?: any[]
191
): void;
192

193
function useIonViewWillEnter(
194
  callback: LifeCycleCallback,
195
  deps?: any[]
196
): void;
197

198
function useIonViewDidLeave(
199
  callback: LifeCycleCallback,
200
  deps?: any[]
201
): void;
202
```
203

204
[Lifecycle Management](./lifecycle-management.md)
205

206
### Platform Utilities
207

208
Utilities for platform detection, configuration management, and platform-specific adaptations.
209

210
```typescript { .api }
211
function isPlatform(platform: Platforms): boolean;
212
function getPlatforms(): string[];
213
function getConfig(): IonicConfig | null;
214

215
type Platforms = 
216
  | 'ios' 
217
  | 'android' 
218
  | 'pwa' 
219
  | 'mobile' 
220
  | 'mobileweb' 
221
  | 'desktop'
222
  | 'hybrid';
223
```
224

225
[Platform Utilities](./platform-utilities.md)
226

227
## Types
228

229
```typescript { .api }
230
interface IonicReactProps {
231
  className?: string;
232
  style?: { [key: string]: any };
233
}
234

235
interface LifeCycleCallback {
236
  (): void | (() => void | undefined);
237
  id?: number;
238
}
239

240
interface AlertOptions {
241
  header?: string;
242
  subHeader?: string;
243
  message?: string;
244
  buttons?: (string | AlertButton)[];
245
  backdropDismiss?: boolean;
246
}
247

248
interface ModalOptions {
249
  component: React.ComponentType<any>;
250
  componentProps?: any;
251
  showBackdrop?: boolean;
252
  backdropDismiss?: boolean;
253
  cssClass?: string;
254
}
255

256
interface ToastOptions {
257
  message: string;
258
  duration?: number;
259
  position?: 'top' | 'middle' | 'bottom';
260
  color?: string;
261
  buttons?: ToastButton[];
262
}
263

264
interface RouteInfo {
265
  pathname: string;
266
  search: string;
267
  hash: string;
268
  state?: any;
269
}
270

271
interface RouterOptions {
272
  direction?: 'forward' | 'back' | 'root' | 'none';
273
  animated?: boolean;
274
}
275
```