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 the Ionic React Quickstart guide. For an overview of how Ionic React works with React, including version support and tooling, check out the Ionic 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

Update src/App.tsx to include setupIonicReact and import the required Ionic Framework stylesheets:

src/App.tsx

// ...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.

備考

While core.css is required, normalize.css, structure.css, and typography.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 to Global 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:

Update src/App.tsx to the following:

src/App.tsx

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();

const App: React.FC = () => (
  <>
    <IonButton>Button</IonButton>
    <IonDatetime></IonDatetime>
  </>
);

export default App;

Visit the components page for all of the available Ionic components.

ヒント

If your existing React app imports a global stylesheet (such as index.css) in src/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 in src/App.tsx:

src/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 provide CSS utilities for faster development. Some stylesheets are optional. For details on which stylesheets are required, check out Global Stylesheets.

2. Set up Theming

Create a src/theme/variables.css file with the following content:

src/theme/variables.css

/* 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 in src/App.tsx:

src/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...

The variables.css file can be used to create custom Ionic Framework themes. The dark.system.css import enables dark 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 to theme/variables.css.

3. Update the App Component

Update src/App.tsx to the following:

src/App.tsx

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();

const App = () => {
  return (
    <IonApp>
      <IonReactRouter>
        <IonRouterOutlet>{/* Routes will be added here */}</IonRouterOutlet>
      </IonReactRouter>
    </IonApp>
  );
};

export default App;

4. Create a Home Page

Create a new file at src/pages/Home.tsx with the following:

src/pages/Home.tsx

import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/react';

import './Home.css';

const Home = () => {
  return (
    <IonPage>
      <IonHeader translucent={true}>
        <IonToolbar>
          <IonTitle>Home</IonTitle>
        </IonToolbar>
      </IonHeader>

      <IonContent fullscreen={true}>
        <IonHeader collapse="condense">
          <IonToolbar>
            <IonTitle size="large">Home</IonTitle>
          </IonToolbar>
        </IonHeader>

        <div id="container">
          <strong>Ready to create an app?</strong>
          <p>
            Start with Ionic{' '}
            <a target="_blank" rel="noopener noreferrer" href="https://ionicframework.com/docs/components">
              UI Components
            </a>
          </p>
        </div>
      </IonContent>
    </IonPage>
  );
};

export default Home;

Then, create src/pages/Home.css:

src/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

important

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, update src/App.tsx to add the routes for the Home page:

src/App.tsx

import { Redirect, Route } from 'react-router-dom';
import { IonApp, IonRouterOutlet, setupIonicReact } from '@ionic/react';
import { IonReactRouter } from '@ionic/react-router';
import Home from './pages/Home';

// ...existing Ionic Framework stylesheet imports...

setupIonicReact();

const App: React.FC = () => (
  <IonApp>
    <IonReactRouter>
      <IonRouterOutlet>
        <Route exact path="/home">
          <Home />
        </Route>
        <Route exact path="/">
          <Redirect to="/home" />
        </Route>
      </IonRouterOutlet>
    </IonReactRouter>
  </IonApp>
);

export default App;

You're all set! Your Ionic React app is now configured with full Ionic page support. Run npm 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:

Navigation

Discover how to handle routing and navigation in Ionic React apps using the React Router.

Components

Explore Ionic's rich library of UI components for building beautiful apps.

Theming

Learn how to customize the look and feel of your app with Ionic's powerful theming system.

Capacitor Documentation

Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.