Version: v7

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 the Ionic 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 latest Ionic 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 running ionic serve, your project will open in the browser.

Screenshot of the Ionic React Home page

Explore the Project Structure

Your new app's src directory will look like this:

├── App.tsx
├── components
│   ├── ExploreContainer.css
│   └── ExploreContainer.tsx
├── main.tsx
└──  pages
    ├── Home.css
    └── Home.tsx

info

All file paths in the examples below are relative to the src/ directory.

Let's walk through these files to understand the app's structure.

View the App Component

The root of your app is defined in 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';

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

This sets up the root of your application, using Ionic's IonApp and IonReactRouter components. The IonRouterOutlet is where your pages will be displayed.

View Routes

Routes are defined within the IonRouterOutlet in App.tsx:

<IonRouterOutlet>
  <Route exact path="/home">
    <Home />
  </Route>
  <Route exact path="/">
    <Redirect to="/home" />
  </Route>
</IonRouterOutlet>

When you visit the root URL (/), the Home component will be loaded.

View the Home Page

The Home page component, defined in pages/Home.tsx, imports the Ionic components and defines the page template:

import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/react';
import ExploreContainer from '../components/ExploreContainer';
import './Home.css';

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonTitle>Blank</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent fullscreen>
        <IonHeader collapse="condense">
          <IonToolbar>
            <IonTitle size="large">Blank</IonTitle>
          </IonToolbar>
        </IonHeader>
        <ExploreContainer />
      </IonContent>
    </IonPage>
  );
};

export default Home;

This creates a page with a header and scrollable content area. The IonPage component provides the basic page structure and must be used on every page. The second header shows a collapsible 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.

Learn More

For detailed information about Ionic layout components, see the Header, Toolbar, Title, and Content documentation.

Add an Ionic Component

You can enhance your Home page with more Ionic UI components. For example, import and add a Button at the end of the IonContent in pages/Home.tsx:

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

const Home: React.FC = () => {
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonTitle>Blank</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent fullscreen>
        {/* ...existing content... */}

        <IonButton>Navigate</IonButton>
      </IonContent>
    </IonPage>
  );
};

export default Home;

Add a New Page

Create a new page at pages/New.tsx:

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

const New: React.FC = () => {
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonButtons slot="start">
            <IonBackButton defaultHref="/"></IonBackButton>
          </IonButtons>
          <IonTitle>New</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent fullscreen>
        <IonHeader collapse="condense">
          <IonToolbar>
            <IonTitle size="large">New</IonTitle>
          </IonToolbar>
        </IonHeader>
      </IonContent>
    </IonPage>
  );
};

export default New;

This creates a page with a Back Button in the Toolbar. The back button will automatically handle navigation back to the previous page, or to / if there is no history.

Important

When creating your own pages, always use IonPage 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 of App.tsx after the Home import:

import New from './pages/New';

Then, add its route in IonRouterOutlet:

<IonRouterOutlet>
  <Route exact path="/home">
    <Home />
  </Route>
  <Route exact path="/new">
    <New />
  </Route>
  <Route exact path="/">
    <Redirect to="/home" />
  </Route>
</IonRouterOutlet>

Once that is done, update the button in pages/Home.tsx:

<IonButton routerLink="/new">Navigate</IonButton>

info

Navigating can also be performed programmatically using React Router's history prop. See the React Navigation documentation for more information.

Add Icons to the New Page

Ionic React comes with Ionicons pre-installed. You can use any icon by setting the icon property of the IonIcon component.

Update the imports in pages/New.tsx to import IonIcon and the heart and logoIonic icons:

import { IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonPage, IonTitle, IonToolbar } from '@ionic/react';
import { heart, logoIonic } from 'ionicons/icons';

Then, include them inside of the IonContent:

<IonIcon icon={heart} />
<IonIcon icon={logoIonic} />

Note that we are passing the imported SVG reference, not the icon name as a string.

For more information, see the Icon documentation and the Ionicons documentation.

Call Component Methods

Let's add a button that can scroll the content area to the bottom.

Update pages/New.tsx to add a ref on IonContent and a button and some items after the existing icons:

<IonContent ref={content}>
  <IonIcon icon={heart} />
  <IonIcon icon={logoIonic} />

  <IonButton onClick={scrollToBottom}>Scroll to Bottom</IonButton>

  {/* Add lots of content to make scrolling possible */}
  {Array.from({ length: 50 }, (_, i) => (
    <IonItem key={i}>
      <IonLabel>Item {i + 1}</IonLabel>
    </IonItem>
  ))}
</IonContent>

Then, add the imports for the additional components and define the scrollToBottom 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';

const New: React.FC = () => {
  const content = useRef<HTMLIonContentElement>(null);

  const scrollToBottom = () => {
    content.current?.scrollToBottom(300);
  };

  return (
    // ...existing template...
  );
};

export default New;

To call methods on Ionic components:

Create a ref for 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 the Methods section of their API documentation.

Run on a Device

Ionic's components work everywhere: on iOS, Android, and PWAs. To deploy to mobile, use Capacitor:

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

See Capacitor'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: