Version: v8

Ionic Angular Quickstart

Welcome! This guide will walk you through creating your first Ionic Angular app, step by step. You'll learn how to set up your development environment, generate a new project, explore the project structure, and add your first UI components and navigation.

If you're looking for a high-level overview of what Ionic Angular is and how it fits into the Angular ecosystem, see the Ionic Angular Overview.

Prerequisites

Before you begin, make sure you have Node.js (which includes npm) installed on your machine. You can check by running:

node -v
npm -v

If you don't have Node.js, download it here.

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 angular

cd myApp
ionic serve

At the first prompt, choose Standalone.

After running ionic serve, your project will open in the browser.

Screenshot of the Ionic Angular Home page

Explore the Project Structure

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

├── app.component.html
├── app.component.scss
├── app.component.ts
├── app.routes.ts
└── home/
    ├── home.page.html
    ├── home.page.scss
    ├── home.page.spec.ts
    └── home.page.ts

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.component.ts:

import { Component } from '@angular/core';
import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';

@Component({
  selector: 'app-root',
  templateUrl: 'app.component.html',
  imports: [IonApp, IonRouterOutlet],
})
export class AppComponent {
  constructor() {}
}

And its template in app.component.html:

<ion-app>
  <ion-router-outlet></ion-router-outlet>
</ion-app>

This sets up the root of your application, using Ionic's ion-app and ion-router-outlet components. The router outlet is where your pages will be displayed.

View Routes

Routes are defined in app.routes.ts:

import { Routes } from '@angular/router';

export const routes: Routes = [
  {
    path: 'home',
    loadComponent: () => import('./home/home.page').then((m) => m.HomePage),
  },
  {
    path: '',
    redirectTo: 'home',
    pathMatch: 'full',
  },
];

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

View the Home Page

The Home page component, defined in home.page.ts, imports the Ionic components it uses:

import { Component } from '@angular/core';
import { IonHeader, IonToolbar, IonTitle, IonContent } from '@ionic/angular/standalone';

@Component({
  selector: 'app-home',
  templateUrl: 'home.page.html',
  styleUrls: ['home.page.scss'],
  imports: [IonHeader, IonToolbar, IonTitle, IonContent],
})
export class HomePage {
  constructor() {}
}

And the template, in the home.page.html file, uses those components:

<ion-header [translucent]="true">
  <ion-toolbar>
    <ion-title> Blank </ion-title>
  </ion-toolbar>
</ion-header>

<ion-content [fullscreen]="true">
  <ion-header collapse="condense">
    <ion-toolbar>
      <ion-title size="large">Blank</ion-title>
    </ion-toolbar>
  </ion-header>

  <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>
</ion-content>

This creates a page with a header and scrollable content area. 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, add a Button at the end of the ion-content:

<ion-content>
  <!-- existing content -->

  <ion-button>Navigate</ion-button>
</ion-content>

Then, import the IonButton component in home.page.ts:

import { IonButton, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';

@Component({
  // ...existing config...
  imports: [IonButton, IonContent, IonHeader, IonTitle, IonToolbar],
})

Add a New Page

To add a new page, generate it with the CLI:

ionic generate page new

A route will be automatically added to app.routes.ts.

In your new.page.html, you can add a Back Button to the Toolbar:

<ion-header [translucent]="true">
  <ion-toolbar>
    <ion-buttons slot="start">
      <ion-back-button defaultHref="/"></ion-back-button>
    </ion-buttons>
    <ion-title>new</ion-title>
  </ion-toolbar>
</ion-header>

And import IonBackButton and IonButtons in new.page.ts:

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

@Component({
  // ...existing config...
  imports: [IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar],
})

The ion-back-button will automatically handle navigation back to the previous page, or to / if there is no history.

Navigate to the New Page

To navigate to the new page, update the button in home.page.html:

<ion-button [routerLink]="['/new']">Navigate</ion-button>

Then, import RouterLink in home.page.ts:

import { RouterLink } from '@angular/router';

@Component({
  // ...existing config...
  imports: [IonButton, IonContent, IonHeader, IonTitle, IonToolbar, RouterLink],
})

info

Navigating can also be performed using Angular's Router service. See the Angular Navigation documentation for more information.

Add Icons to the New Page

Ionic Angular comes with Ionicons pre-installed. You can use any icon by setting the name property on the ion-icon component. Add the following icons to new.page.html:

<ion-content>
  <!-- existing content -->

  <ion-icon name="heart"></ion-icon>
  <ion-icon name="logo-ionic"></ion-icon>
</ion-content>

You'll also need to import and register these icons in new.page.ts:

// ...existing imports...
import { IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonTitle, IonToolbar } from '@ionic/angular/standalone';
import { addIcons } from 'ionicons';
import { heart, logoIonic } from 'ionicons/icons';

@Component({
  // ...existing config...
  imports: [IonBackButton, IonButtons, IonContent, IonHeader, IonIcon, IonTitle, IonToolbar],
})

Then, update the constructor of the page to use addIcons:

export class NewPage implements OnInit {
  constructor() {
    addIcons({ heart, logoIonic });
  }
}

Alternatively, you can register icons in app.component.ts to use them throughout your app.

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

Run on a Device

Ionic's components work everywhere: 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 Angular app, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out: