Add to Existing React Project
This guide covers how to add Ionic React to an existing React project. If you're looking to start a new project from scratch, check out theIonic React Quickstart guide. For an overview of how Ionic React works with React, including version support and tooling, check out theIonic React Overview.
This guide uses TypeScript examples. If you're using JavaScript, the setup process is the same, but you'll use.jsx file extensions instead of.tsx.
Setup
This guide follows the structure of a React app created with Vite. If you started your React app using a different tool (such as Create React App), your file structure and setup may differ.
Follow these steps to add Ionic React to your existing React project:
1. Install the Package
npm install @ionic/react
2. Configure Ionic React
Updatesrc/App.tsx to includesetupIonicReact and import the required Ionic Framework stylesheets:
// ...existing imports...
import{ setupIonicReact}from'@ionic/react';
/* Core CSS required for Ionic components to work properly */
import'@ionic/react/css/core.css';
/* Basic CSS for apps built with Ionic */
import'@ionic/react/css/normalize.css';
import'@ionic/react/css/structure.css';
import'@ionic/react/css/typography.css';
setupIonicReact();
// ...existing app function and export...
setupIonicReact is a function that sets up the Ionic React components to work with your app. It is required to be called before using any of the Ionic React components.
Whilecore.css is required,normalize.css,structure.css, andtypography.css are recommended but not required. They normalize cross-browser differences, ensure proper scrolling behavior, and provide consistent typography and form styling. Without them, you may need to handle these concerns yourself. For more details, refer toGlobal Stylesheets.
Using Individual Components
After completing the setup above, you can start using Ionic components in your existing React app. Here's an example of how to use them:
Updatesrc/App.tsx to the following:
import{IonButton,IonDatetime, setupIonicReact}from'@ionic/react';
import'./App.css';
/* Core CSS required for Ionic components to work properly */
import'@ionic/react/css/core.css';
/* Basic CSS for apps built with Ionic */
import'@ionic/react/css/normalize.css';
import'@ionic/react/css/structure.css';
import'@ionic/react/css/typography.css';
setupIonicReact();
constApp:React.FC=()=>(
<>
<IonButton>Button</IonButton>
<IonDatetime></IonDatetime>
</>
);
exportdefaultApp;
Visit thecomponents page for all of the available Ionic components.
If your existing React app imports a global stylesheet (such asindex.css) insrc/main.tsx, you may want to remove it or update any styles that conflict with Ionic Framework components. Ionic Framework includes its own CSS reset and normalization, which may conflict with existing global styles.
Using Ionic Pages
If you want to use Ionic pages with full navigation and page transitions, follow these additional setup steps.
1. Add Additional Ionic Framework Stylesheets
Update the imported stylesheets insrc/App.tsx:
/* Core CSS required for Ionic components to work properly */
import'@ionic/react/css/core.css';
/* Basic CSS for apps built with Ionic */
import'@ionic/react/css/normalize.css';
import'@ionic/react/css/structure.css';
import'@ionic/react/css/typography.css';
/* Optional CSS utils that can be commented out */
import'@ionic/react/css/padding.css';
import'@ionic/react/css/float-elements.css';
import'@ionic/react/css/text-alignment.css';
import'@ionic/react/css/text-transformation.css';
import'@ionic/react/css/flex-utils.css';
import'@ionic/react/css/display.css';
These stylesheets set up the overall page structure and provideCSS utilities for faster development. Some stylesheets are optional. For details on which stylesheets are required, check outGlobal Stylesheets.
2. Set up Theming
Create asrc/theme/variables.css file with the following content:
/* For information on how to create your own theme, please refer to:
https://ionicframework.com/docs/theming/ */
Then, import the file and the dark palette stylesheet insrc/App.tsx:
// ...existing imports...
// ...existing stylesheets...
/**
* Ionic Dark Mode
* -----------------------------------------------------
* For more info, please refer to:
* https://ionicframework.com/docs/theming/dark-mode
*/
/* @import '@ionic/react/css/palettes/dark.always.css'; */
/* @import '@ionic/react/css/palettes/dark.class.css'; */
import'@ionic/react/css/palettes/dark.system.css';
/* Theme variables */
import'./theme/variables.css';
setupIonicReact();
// ...existing app function and export...
Thevariables.css file can be used to create custom Ionic Framework themes. Thedark.system.css import enablesdark mode support for your Ionic app when the system is set to prefer a dark appearance. You can customize the theming behavior by uncommenting different dark palette imports or adding custom CSS variables totheme/variables.css.
3. Update the App Component
Updatesrc/App.tsx to the following:
import{IonApp,IonRouterOutlet, setupIonicReact}from'@ionic/react';
import{IonReactRouter}from'@ionic/react-router';
/* Core CSS required for Ionic components to work properly */
import'@ionic/react/css/core.css';
/* Basic CSS for apps built with Ionic */
import'@ionic/react/css/normalize.css';
import'@ionic/react/css/structure.css';
import'@ionic/react/css/typography.css';
/* Optional CSS utils that can be commented out */
import'@ionic/react/css/padding.css';
import'@ionic/react/css/float-elements.css';
import'@ionic/react/css/text-alignment.css';
import'@ionic/react/css/text-transformation.css';
import'@ionic/react/css/flex-utils.css';
import'@ionic/react/css/display.css';
/**
* Ionic Dark Mode
* -----------------------------------------------------
* For more info, please refer to:
* https://ionicframework.com/docs/theming/dark-mode
*/
/* @import '@ionic/react/css/palettes/dark.always.css'; */
/* @import '@ionic/react/css/palettes/dark.class.css'; */
import'@ionic/react/css/palettes/dark.system.css';
/* Theme variables */
import'./theme/variables.css';
setupIonicReact();
constApp=()=>{
return(
<IonApp>
<IonReactRouter>
<IonRouterOutlet>{/* Routes will be added here */}</IonRouterOutlet>
</IonReactRouter>
</IonApp>
);
};
exportdefaultApp;
4. Create a Home Page
Create a new file atsrc/pages/Home.tsx with the following:
import{IonContent,IonHeader,IonPage,IonTitle,IonToolbar}from'@ionic/react';
import'./Home.css';
constHome=()=>{
return(
<IonPage>
<IonHeadertranslucent={true}>
<IonToolbar>
<IonTitle>Home</IonTitle>
</IonToolbar>
</IonHeader>
<IonContentfullscreen={true}>
<IonHeadercollapse="condense">
<IonToolbar>
<IonTitlesize="large">Home</IonTitle>
</IonToolbar>
</IonHeader>
<divid="container">
<strong>Ready to create an app?</strong>
<p>
Start with Ionic{' '}
<atarget="_blank"rel="noopener noreferrer"href="https://ionicframework.com/docs/components">
UI Components
</a>
</p>
</div>
</IonContent>
</IonPage>
);
};
exportdefaultHome;
Then, createsrc/pages/Home.css:
#container{
text-align: center;
position: absolute;
left:0;
right:0;
top:50%;
transform:translateY(-50%);
}
#container strong{
font-size:20px;
line-height:26px;
}
#container p{
font-size:16px;
line-height:22px;
color:#8c8c8c;
margin:0;
}
#container a{
text-decoration: none;
}
5. Set up Routing
Ionic React Router currently only supports React Router v5. You must install the following specific versions of the router packages to set up routing with Ionic React.
Install the router packages:
npm install @ionic/react-router react-router@5 react-router-dom@5
npm install @types/react-router-dom --save-dev
Then, updatesrc/App.tsx to add the routes for the Home page:
import{Redirect,Route}from'react-router-dom';
import{IonApp,IonRouterOutlet, setupIonicReact}from'@ionic/react';
import{IonReactRouter}from'@ionic/react-router';
importHomefrom'./pages/Home';
// ...existing Ionic Framework stylesheet imports...
setupIonicReact();
constApp:React.FC=()=>(
<IonApp>
<IonReactRouter>
<IonRouterOutlet>
<Routeexactpath="/home">
<Home/>
</Route>
<Routeexactpath="/">
<Redirectto="/home"/>
</Route>
</IonRouterOutlet>
</IonReactRouter>
</IonApp>
);
exportdefaultApp;
You're all set! Your Ionic React app is now configured with full Ionic page support. Runnpm run dev to start your development server and view your app.
Next Steps
Now that you have Ionic React integrated into your project, check out:
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.