Ionic React Quickstart
Welcome! This guide will walk you through the basics of Ionic React development. You'll learn how to set up your development environment, generate a simple project, explore the project structure, and understand how Ionic components work. This is perfect for getting familiar with Ionic React before building your first real app.
If you're looking for a high-level overview of what Ionic React is and how it fits into the React ecosystem, see theIonic React Overview.
Prerequisites
Before you begin, make sure you have Node.js and npm installed on your machine.You can check by running:
node -v
npm -v
If you don't have Node.js and npm,download Node.js here (which includes npm).
Create a Project with the Ionic CLI
First, install the latestIonic CLI:
npm install -g @ionic/cli
Then, run the following commands to create and run a new project:
ionic start myApp blank --type react
cd myApp
ionic serve
After runningionic serve, your project will open in the browser.
Explore the Project Structure
Your new app'ssrc directory will look like this:
├── App.tsx
├── components
│ ├── ExploreContainer.css
│ └── ExploreContainer.tsx
├── main.tsx
└── pages
├── Home.css
└── Home.tsx
All file paths in the examples below are relative to thesrc/ directory.
Let's walk through these files to understand the app's structure.
View the App Component
The root of your app is defined inApp.tsx:
import{Redirect,Route}from'react-router-dom';
import{IonApp,IonRouterOutlet, setupIonicReact}from'@ionic/react';
import{IonReactRouter}from'@ionic/react-router';
importHomefrom'./pages/Home';
// ..CSS imports...
setupIonicReact();
constApp:React.FC=()=>(
<IonApp>
<IonReactRouter>
<IonRouterOutlet>
<Routeexactpath="/home">
<Home/>
</Route>
<Routeexactpath="/">
<Redirectto="/home"/>
</Route>
</IonRouterOutlet>
</IonReactRouter>
</IonApp>
);
exportdefaultApp;
This sets up the root of your application, using Ionic'sIonApp andIonReactRouter components. TheIonRouterOutlet is where your pages will be displayed.
View Routes
Routes are defined within theIonRouterOutlet inApp.tsx:
<IonRouterOutlet>
<Routeexactpath="/home">
<Home/>
</Route>
<Routeexactpath="/">
<Redirectto="/home"/>
</Route>
</IonRouterOutlet>
When you visit the root URL (/), theHome component will be loaded.
View the Home Page
The Home page component, defined inpages/Home.tsx, imports the Ionic components and defines the page template:
import{IonContent,IonHeader,IonPage,IonTitle,IonToolbar}from'@ionic/react';
importExploreContainerfrom'../components/ExploreContainer';
import'./Home.css';
constHome:React.FC=()=>{
return(
<IonPage>
<IonHeader>
<IonToolbar>
<IonTitle>Blank</IonTitle>
</IonToolbar>
</IonHeader>
<IonContentfullscreen>
<IonHeadercollapse="condense">
<IonToolbar>
<IonTitlesize="large">Blank</IonTitle>
</IonToolbar>
</IonHeader>
<ExploreContainer/>
</IonContent>
</IonPage>
);
};
exportdefaultHome;
This creates a page with a header and scrollable content area. TheIonPage component provides the basic page structure and must be used on every page. The second header shows acollapsible large title that displays when at the top of the content, then condenses to show the smaller title in the first header when scrolling down.
Add an Ionic Component
You can enhance your Home page with more Ionic UI components. For example, import and add aButton at the end of theIonContent inpages/Home.tsx:
import{IonButton,IonContent,IonHeader,IonPage,IonTitle,IonToolbar}from'@ionic/react';
// ...existing imports...
constHome:React.FC=()=>{
return(
<IonPage>
<IonHeader>
<IonToolbar>
<IonTitle>Blank</IonTitle>
</IonToolbar>
</IonHeader>
<IonContentfullscreen>
{/* ...existing content... */}
<IonButton>Navigate</IonButton>
</IonContent>
</IonPage>
);
};
exportdefaultHome;
Add a New Page
Create a new page atpages/New.tsx:
import{IonBackButton,IonButtons,IonContent,IonHeader,IonPage,IonTitle,IonToolbar}from'@ionic/react';
constNew:React.FC=()=>{
return(
<IonPage>
<IonHeader>
<IonToolbar>
<IonButtonsslot="start">
<IonBackButtondefaultHref="/"></IonBackButton>
</IonButtons>
<IonTitle>New</IonTitle>
</IonToolbar>
</IonHeader>
<IonContentfullscreen>
<IonHeadercollapse="condense">
<IonToolbar>
<IonTitlesize="large">New</IonTitle>
</IonToolbar>
</IonHeader>
</IonContent>
</IonPage>
);
};
exportdefaultNew;
This creates a page with aBack Button in theToolbar. The back button will automatically handle navigation back to the previous page, or to/ if there is no history.
When creating your own pages, always useIonPage as the root component. This is essential for proper transitions between pages, base CSS styling that Ionic components depend on, and consistent layout behavior across your app.
Navigate to the New Page
To navigate to the new page, create a route for it by first importing it at the top ofApp.tsx after theHome import:
importNewfrom'./pages/New';
Then, add its route inIonRouterOutlet:
<IonRouterOutlet>
<Routeexactpath="/home">
<Home/>
</Route>
<Routeexactpath="/new">
<New/>
</Route>
<Routeexactpath="/">
<Redirectto="/home"/>
</Route>
</IonRouterOutlet>
Once that is done, update the button inpages/Home.tsx:
<IonButtonrouterLink="/new">Navigate</IonButton>
Navigating can also be performed programmatically using React Router'shistory prop. See theReact Navigation documentation for more information.
Add Icons to the New Page
Ionic React comes withIonicons pre-installed. You can use any icon by setting theicon property of theIonIcon component.
Update the imports inpages/New.tsx to importIonIcon and theheart andlogoIonic icons:
import{IonBackButton,IonButtons,IonContent,IonHeader,IonIcon,IonPage,IonTitle,IonToolbar}from'@ionic/react';
import{ heart, logoIonic}from'ionicons/icons';
Then, include them inside of theIonContent:
<IonIconicon={heart}/>
<IonIconicon={logoIonic}/>
Note that we are passing the imported SVG reference,not the icon name as a string.
For more information, see theIcon documentation and theIonicons documentation.
Call Component Methods
Let's add a button that can scroll the content area to the bottom.
Updatepages/New.tsx to add aref onIonContent and a button and some items after the existing icons:
<IonContentref={content}>
<IonIconicon={heart}/>
<IonIconicon={logoIonic}/>
<IonButtononClick={scrollToBottom}>Scroll to Bottom</IonButton>
{/* Add lots of content to make scrolling possible */}
{Array.from({ length:50},(_, i)=>(
<IonItemkey={i}>
<IonLabel>Item{i+1}</IonLabel>
</IonItem>
))}
</IonContent>
Then, add the imports for the additional components and define thescrollToBottom function:
import{ useRef}from'react';
import{IonButton,IonBackButton,IonButtons,IonContent,IonHeader,IonIcon,IonItem,IonLabel,IonPage,IonTitle,IonToolbar}from'@ionic/react';
import{ heart, logoIonic}from'ionicons/icons';
constNew:React.FC=()=>{
const content=useRef<HTMLIonContentElement>(null);
constscrollToBottom=()=>{
content.current?.scrollToBottom(300);
};
return(
// ...existing template...
);
};
exportdefaultNew;
To call methods on Ionic components:
- Create a
reffor the component - Call the method directly on
ref.current
This pattern is necessary because React refs store the component instance in the.current property.
You can find available methods for each component in theMethods section of their API documentation.
Run on a Device
Ionic's components work everywhere: on iOS, Android, and PWAs. To deploy to mobile, useCapacitor:
ionic build
ionic cap add ios
ionic cap add android
Open the native projects in their IDEs:
ionic cap open ios
ionic cap open android
SeeCapacitor's Getting Started guide for more.
Explore More
This guide covered the basics of creating an Ionic React app, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out:
Build a real Photo Gallery app with Ionic React and native device features.
Learn more about React's core concepts, tools, and best practices from the official React documentation.
Discover how to handle routing and navigation in Ionic React apps using the React Router.
Explore Ionic's rich library of UI components for building beautiful apps.
Learn how to customize the look and feel of your app with Ionic's powerful theming system.
Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.