Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Ionic Project Structure and Pages

Tour an Ionic project: src folders, ionic.config.json, capacitor.config, theme files and how a page, header, toolbar and content fit together.

A new Ionic project contains dozens of files, but only a few matter on day one. Knowing which ones to open, and which to leave alone, makes the whole framework less intimidating. This lesson maps the folder layout, explains the configuration files, and shows how a page is assembled from Ionic's layout components.

The folder layout

The exact names differ slightly per framework, but the shape is shared:

TEXT
photoNotes/
  src/
    pages/ (or app/)      your screens
    components/           reusable pieces
    theme/variables.css   colours, fonts, global variables
    main.tsx / main.ts    app entry point
  public/ (or assets/)    images, icons, static files
  capacitor.config.ts     native app settings
  ionic.config.json       Ionic CLI settings
  package.json            dependencies and scripts
  vite.config.ts          build tool config (React, Vue)

Angular projects use angular.json instead of Vite, and put the app code under src/app/ with one folder per page.

The files that matter

File Purpose
package.json Lists @ionic/* packages and scripts such as npm run build
ionic.config.json Project name, framework type and integration settings for the CLI
capacitor.config.ts appId (like com.example.photonotes), appName and webDir (the built web folder)
src/theme/variables.css The Ionic colour variables you will edit most
src/global.scss or index.css Imports Ionic's core and utility CSS

The capacitor.config.ts is worth reading once:

TypeScript
import type { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.example.photonotes',
  appName: 'photoNotes',
  webDir: 'dist',
};

export default config;

webDir must match your build output folder (dist for Vite, www for Angular). Mismatching it is the most common reason a native build shows a blank screen.

How the app boots

flowchart LR
  A["index.html"] --> B["main entry file"]
  B --> C["setupIonicReact / provideIonicAngular / IonicVue"]
  C --> D["Root component: ion-app + router outlet"]
  D --> E["First page"]

The root wraps everything in ion-app, then a router outlet shows one page at a time.

The entry point initialises Ionic once. Each framework has its own call, and each one loads Ionic's CSS:

TypeScript
// React: main.tsx
import { setupIonicReact } from '@ionic/react';
import '@ionic/react/css/core.css';
import '@ionic/react/css/normalize.css';
import './theme/variables.css';

setupIonicReact({ mode: undefined }); // undefined = pick ios/md automatically

The core.css import is required. Without it components appear unstyled. Other CSS files (structure.css, typography.css, padding.css, flex-utils.css, display.css) are optional utilities; the starter imports them all, and you can delete the ones you do not use to reduce size.

Anatomy of a page

Every page in Ionic uses the same four layout components:

  • ion-page (or the page host in Angular/Vue) is the full-screen container the router transitions in and out.
  • ion-header holds the top bar and stays fixed while content scrolls.
  • ion-toolbar is a bar inside a header (or footer) that holds the title, buttons and search.
  • ion-content is the scrollable area. It is the only element that scrolls, so Ionic can handle keyboards, pull-to-refresh and the iOS large-title collapse.
HTML
<ion-page>
  <ion-header>
    <ion-toolbar>
      <ion-buttons slot="start">
        <ion-back-button defaultHref="/"></ion-back-button>
      </ion-buttons>
      <ion-title>Details</ion-title>
      <ion-buttons slot="end">
        <ion-button>Edit</ion-button>
      </ion-buttons>
    </ion-toolbar>
  </ion-header>
  <ion-content class="ion-padding">...</ion-content>
  <ion-footer>
    <ion-toolbar><ion-title>Footer</ion-title></ion-toolbar>
  </ion-footer>
</ion-page>

Notice slot="start" and slot="end". A slot places a child inside a named region of its parent. In a toolbar, start is the left side in left-to-right languages and flips for right-to-left ones, so you never hard-code "left".

A stand-in for slots

This stand-in shows the idea of named slots: a toolbar with regions, and children that declare which region they belong to. It is plain JavaScript, not Ionic.

JS Stand-in: toolbar slots

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Creating more pages

In Angular, the CLI wires everything for you:

Terminal
ionic generate page pages/settings

In React and Vue you create a component file, then add a route (see routing basics). Keep each page in its own folder with its styles and tests beside it:

TEXT
pages/
  Settings/
    Settings.tsx
    Settings.css
    Settings.test.tsx

A tiny page model you can run

To feel why one scrolling container matters, this stand-in models a page with a fixed header and a scrolling content region.

JS Stand-in: only content scrolls

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which element is the scrollable area of an Ionic page?

    ion-content scrolls. Header and footer stay fixed so Ionic can manage keyboard, refresh and collapsing titles.
  2. 2. What does webDir in capacitor.config.ts point to?

    Capacitor copies the folder named in webDir into the native projects, so it must match your build output.
  3. 3. Why use slot="start" instead of left?

    start and end follow the reading direction, so layouts work in right-to-left languages without changes.
  4. 4. Which CSS import is mandatory for Ionic components to be styled?

    core.css contains the base styles for every component; the other files are optional utilities.

Summary

  • Pages live under src/pages (or src/app), global theme in src/theme/variables.css.
  • capacitor.config.ts holds appId, appName and webDir; webDir must match the build output.
  • Initialise Ionic once at startup and import core.css.
  • A page is ion-page with ion-header, ion-toolbar, ion-content and optionally ion-footer.
  • Slots such as start and end place children and respect text direction.

Next: Choosing Angular, React or Vue