Adding Ionic React to an existing React project
Tags: ionic, react
Published: 2019-10-16 19:42:32

Earlier this week, we launched Ionic React (read the announcement [here](https://ionicframework.com/blog/announcing-ionic-react/)). To get started with a new Ionic React project is quite easy, but what if you have an existing React project and want to integrate Ionic into it?

Fortunately the process it pretty easy. In this short guide, I'll go through how to start using Ionic React in an existing project. I'll start with how to use individual components, and then touch on how to get the full Ionic app experience.

## Using Individual Ionic Components

Ionic React has around 100 components that you can begin using in your app immediately to help make it more mobile-friendly.

To get started with just using components, add the `@ionic/react` package to your project:

```bash
npm i @ionic/react
```

Next, import the core CSS for Ionic somewhere in your main app file:

```javascript
import '@ionic/react/css/core.css';
```

Now, you can import any of the components and begin to use them right away. Here we are importing the `IonButton` and `IonDatetme` components and using them anywhere in our app:

```javascript
import { IonButton, IonDatetime } from '@ionic/react';
```

```jsx
<IonDatetime displayFormat="MM/DD/YYYY" placeholder="Select Date"></IonDatetime>
<IonButton fill="clear">Start</IonButton>
```

## Using Ionic Pages

If you want to convert part of your app and give it the whole Ionic experience, there are a few additional steps to take to get this setup.

First, import some additional CSS files that help set up the overall structure of the page and some utility helpers:

```javascript
/* 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';
```

If you are using another CSS framework (like Bootstrap), you might want to isolate the Ionic pages away from them. This will help to ensure there aren't any CSS conflicts between the libraries.

Next, install the `@ionic/react-router` library:

```bash
npm i @ionic/react-router
```

The Ionic React Router library is a small wrapper around the popular React Router library and helps provide the functionality we need for native-like page transitions.

The main Ionic page will need a couple of base components. First, use a `IonApp` component (from `@ionic/react`) as the root component, and then use `IonReactRouter` (from `@ionic/react-router`).

`IonApp` sets up our main container, with the necessary styling needed for our structural components. `IonReactRouter` is a small wrapper for React Routers `BrowserRouter` and should be used in its place.

Then, wrap all your routes in an `IonRouterOutlet`, which is what manages our Ionic pages.

```javascript
<IonApp>
  <IonReactRouter>
    <IonRouterOutlet>
      <Route path="/" exact component={Home} />
      <Route path="/about" exact component={About} />
    </IonRouterOutlet>
  </IonReactRouter>
</IonApp>
``` 
Now you can setup Ionic pages like so:

```javascript
<IonPage>
  <IonHeader>
    <IonToolbar>
      <IonTitle>My Page</IonTitle>
    </IonToolbar>
  </IonHeader>
  <IonContent>
    <IonDatetime displayFormat="MM/DD/YYYY" placeholder="Select Date"></IonDatetime>
    <IonButton fill="clear">Start</IonButton>
  </IonContent>
</IonPage>
```

Note that having `IonPage` is important to have as the base component for your "Ionic" pages. `IonPage` is the element we look for to do the page transition on.

For more information on routing and navigation in Ionic React, see [here](https://ionicframework.com/docs/react/navigation).

## Customize the Theme

To customize the look and feel of the components, we have some CSS variables you can override to provide a theme for your components. Set these somewhere in your main CSS file:

```css
:root {
  --ion-color-angular: #ac282b;
  --ion-color-communication: #8e8d93;
  --ion-color-tooling: #fe4c52;
  --ion-color-services: #fd8b2d;
  --ion-color-design: #fed035;
  --ion-color-workshop: #69bb7b;
  --ion-color-food: #3bc7c4;
  --ion-color-documentation: #b16be3;
  --ion-color-navigation: #6600cc;

  --ion-color-primary: #3880ff;
  --ion-color-primary-rgb: 56, 128, 255;
  --ion-color-primary-contrast: #ffffff;
  --ion-color-primary-contrast-rgb: 255, 255, 255;
  --ion-color-primary-shade: #3171e0;
  --ion-color-primary-tint: #4c8dff;

  --ion-color-secondary: #0cd1e8;
  --ion-color-secondary-rgb: 12, 209, 232;
  --ion-color-secondary-contrast: #ffffff;
  --ion-color-secondary-contrast-rgb: 255, 255, 255;
  --ion-color-secondary-shade: #0bb8cc;
  --ion-color-secondary-tint: #24d6ea;

  --ion-color-tertiary: #7044ff;
  --ion-color-tertiary-rgb: 112, 68, 255;
  --ion-color-tertiary-contrast: #ffffff;
  --ion-color-tertiary-contrast-rgb: 255, 255, 255;
  --ion-color-tertiary-shade: #633ce0;
  --ion-color-tertiary-tint: #7e57ff;

  --ion-color-success: #10dc60;
  --ion-color-success-rgb: 16, 220, 96;
  --ion-color-success-contrast: #ffffff;
  --ion-color-success-contrast-rgb: 255, 255, 255;
  --ion-color-success-shade: #0ec254;
  --ion-color-success-tint: #28e070;

  --ion-color-warning: #ffce00;
  --ion-color-warning-rgb: 255, 206, 0;
  --ion-color-warning-contrast: #ffffff;
  --ion-color-warning-contrast-rgb: 255, 255, 255;
  --ion-color-warning-shade: #e0b500;
  --ion-color-warning-tint: #ffd31a;

  --ion-color-danger: #f04141;
  --ion-color-danger-rgb: 245, 61, 61;
  --ion-color-danger-contrast: #ffffff;
  --ion-color-danger-contrast-rgb: 255, 255, 255;
  --ion-color-danger-shade: #d33939;
  --ion-color-danger-tint: #f25454;

  --ion-color-dark: #222428;
  --ion-color-dark-rgb: 34, 34, 34;
  --ion-color-dark-contrast: #ffffff;
  --ion-color-dark-contrast-rgb: 255, 255, 255;
  --ion-color-dark-shade: #1e2023;
  --ion-color-dark-tint: #383a3e;

  --ion-color-medium: #989aa2;
  --ion-color-medium-rgb: 152, 154, 162;
  --ion-color-medium-contrast: #ffffff;
  --ion-color-medium-contrast-rgb: 255, 255, 255;
  --ion-color-medium-shade: #86888f;
  --ion-color-medium-tint: #a2a4ab;

  --ion-color-light: #f4f5f8;
  --ion-color-light-rgb: 244, 244, 244;
  --ion-color-light-contrast: #000000;
  --ion-color-light-contrast-rgb: 0, 0, 0;
  --ion-color-light-shade: #d7d8da;
  --ion-color-light-tint: #f5f6f9;
}
```

For more info on theming your Ionic app, see the guide [here](https://ionicframework.com/docs/theming/themes).

## Wrapping up

Adding Ionic React to an existing React project is fairly simple and can be done in just a few minutes.

The great thing about using individual components from Ionic React is that you only import the component you need. Each component is lazy loaded at runtime so that it won't bloat your bundle size. This makes Ionic React ideal for adding it to existing projects that need to look and work great on mobile devices.