Ionic Framework
Comprehensive reference for Ionic Framework development — core concepts, components, theming, lifecycle, navigation, framework-specific patterns (Angular, React, Vue), upgrading, and Capawesome Cloud integration.
Core Concepts
Ionic Framework is a UI toolkit for building cross-platform apps with web technologies. It provides 80+ pre-built UI components as Web Components prefixed with ion- (e.g., <ion-button>, <ion-content>).
- - Platform modes: Components adapt styling to the platform. iOS devices use
ios mode; Android and all other platforms use md (Material Design). The <html> element receives a class (ios or md). - Capacitor integration: Ionic handles the UI; Capacitor handles native device APIs. See the
capacitor-app-development skill for Capacitor guidance. - Framework support: Ionic integrates with Angular (
@ionic/angular), React (@ionic/react), and Vue (@ionic/vue).
Creating a New App
CODEBLOCK0
| INLINECODE12 value | Framework |
|---|
| INLINECODE13 | Angular (NgModules) |
| INLINECODE14 |
Angular (Standalone Components) |
|
react | React |
|
vue | Vue |
| Template | Description |
|---|
| INLINECODE17 | Empty project, single page |
| INLINECODE18 |
Tab-based layout |
|
sidemenu | Side menu layout |
For details, see ionic-app-creation.
Ionic CLI
Run ionic --help for the full and always up-to-date command list.
| Command | Description |
|---|
| INLINECODE21 | Scaffold a new Ionic project. |
| INLINECODE22 |
Start a local dev server with live reload (port 8100). |
|
ionic build | Build the web app for production. |
|
ionic generate | Generate pages, components, services (framework-dependent). |
|
ionic info | Print system/environment info. |
|
ionic repair | Remove and recreate dependencies and platform files. |
Useful ionic serve flags: --external (all network interfaces), --port=<port>, --prod, --no-open.
Components Overview
Ionic provides 80+ UI components organized by category. For full API reference (properties, events, methods, slots, CSS custom properties), see the linked reference files.
Layout
INLINECODE32 (root container), ion-content (scrollable area), ion-header, ion-footer, ion-toolbar, ion-title, ion-buttons, ion-back-button, ion-grid/ion-row/ion-col, ion-split-pane.
Key usage:
CODEBLOCK1
For details, see components-layout.md.
Navigation
INLINECODE44 , ion-tab-bar, ion-tab-button, ion-menu, ion-menu-button, ion-menu-toggle, ion-router-outlet, ion-nav, ion-breadcrumbs.
For details, see components-navigation.md.
Form
INLINECODE53 , ion-textarea, ion-select/ion-select-option, ion-checkbox, ion-toggle, ion-radio/ion-radio-group, ion-range, ion-datetime/ion-datetime-button, ion-searchbar, ion-segment/ion-segment-button, ion-input-otp.
Key properties shared by most form components: label, labelPlacement (floating, stacked, fixed, start), fill (outline, solid), errorText, helperText, disabled, value, placeholder.
Key events:
- -
ionInput — fires on each keystroke (use for ion-input/ion-textarea). - INLINECODE85 — fires when value is committed (use for
ion-select, ion-toggle, ion-checkbox, ion-range).
CODEBLOCK2
For details, see components-form.md.
Overlays
INLINECODE90 , ion-alert, ion-toast, ion-action-sheet, ion-loading, ion-popover.
All overlays share: isOpen prop for declarative control, trigger prop to open from a button ID, backdropDismiss, animated, and lifecycle events (didPresent, didDismiss, willPresent, willDismiss).
Sheet modal (bottom sheet):
CODEBLOCK3
For details, see components-overlay.md.
Data Display
INLINECODE104 , ion-item, ion-item-sliding/ion-item-options/ion-item-option, ion-card/ion-card-header/ion-card-content, ion-accordion/ion-accordion-group, ion-chip, ion-badge, ion-label, ion-note.
For details, see components-data-display.md.
Scroll
INLINECODE118 /ion-refresher-content (pull-to-refresh), ion-infinite-scroll/ion-infinite-scroll-content, ion-reorder-group/ion-reorder.
For details, see components-scroll.md.
Actions & Media
INLINECODE124 , ion-fab/ion-fab-button, ion-icon, ion-avatar, ion-thumbnail, ion-spinner, ion-skeleton-text, ion-progress-bar.
For details, see components-action.md and components-media.md.
Theming
Colors
Nine default colors: primary, secondary, tertiary, success, warning, danger, light, medium, dark. Apply via the color attribute:
CODEBLOCK4
Customize a color by overriding all six CSS variables in :root:
CODEBLOCK5
Global CSS Variables
Key variables: --ion-background-color, --ion-text-color, --ion-font-family, --ion-safe-area-top/right/bottom/left, --ion-margin, --ion-padding.
Dark Mode
Three approaches (import from @ionic/angular/css/, @ionic/react/css/, or @ionic/vue/css/):
- 1. System preference (default): INLINECODE153
- Always dark: INLINECODE154
- CSS class toggle:
@import '@ionic/<framework>/css/palettes/dark.class.css'; then add .ion-palette-dark to <html>.
Platform Styles
Target platform-specific styles in CSS using the mode class on <html>:
CODEBLOCK6
Preview a specific mode in the browser: INLINECODE159
Layout
Grid System
12-column flexbox grid: ion-grid, ion-row, ion-col. Columns expand evenly unless size (1-12) is specified.
| Breakpoint | Min Width | Property Suffix |
|---|
| INLINECODE164 | 0 | INLINECODE165 |
| INLINECODE166 |
576px |
Sm |
|
md | 768px |
Md |
|
lg | 992px |
Lg |
|
xl | 1200px |
Xl |
CSS Utility Classes
- - Padding:
.ion-padding, .ion-padding-top/bottom/start/end, INLINECODE176 - Margin:
.ion-margin, .ion-margin-top/bottom/start/end, INLINECODE179 - Text:
.ion-text-center, .ion-text-start, .ion-text-end, .ion-text-wrap, INLINECODE184 - Display:
.ion-display-none, .ion-display-block, INLINECODE187 - Flex:
.ion-justify-content-center, .ion-align-items-center, .ion-flex-row, INLINECODE191
All utility classes support responsive suffixes: .ion-text-md-center (applies at 768px+).
Page Lifecycle
Ionic provides four lifecycle hooks that fire during page transitions. These exist because ion-router-outlet caches pages in the DOM — framework-native lifecycle hooks (ngOnInit, useEffect, onMounted) only fire once on first creation, not on every page visit.
| Hook | Fires When | Use For |
|---|
| INLINECODE197 | Page about to enter (pre-animation) | Refresh data on every visit |
| INLINECODE198 |
Page fully entered (post-animation) | Start animations, focus inputs |
|
ionViewWillLeave | Page about to leave (pre-animation) | Save state, pause subscriptions |
|
ionViewDidLeave | Page fully left (post-animation) | Clean up off-screen resources |
Critical rules:
- - Only fire on components directly mapped to a route via
ion-router-outlet. - Child components do not receive these events.
- The component must use the framework-specific page wrapper (see framework sections below).
Framework-Specific Patterns
Angular
For full details, see ionic-angular.
Detect architecture: Check src/main.ts for bootstrapApplication (standalone) vs platformBrowserDynamic().bootstrapModule (NgModule).
| Aspect | Standalone | NgModule |
|---|
| Ionic setup | INLINECODE205 in INLINECODE206 | INLINECODE207 in INLINECODE208 |
| Component imports |
Each from
@ionic/angular/standalone |
IonicModule provides all globally |
| Lazy loading |
loadComponent in routes |
loadChildren in routes |
| Icons |
addIcons() from
ionicons required | Automatic |
Navigation: Use NavController from @ionic/angular for animated navigation (navigateForward, navigateBack, navigateRoot, back). Use routerLink with routerDirection in templates.
Lifecycle: Implement interfaces ViewWillEnter, ViewDidEnter, ViewWillLeave, ViewDidLeave from @ionic/angular:
CODEBLOCK7
For navigation details, see angular/navigation.md. For lifecycle details, see angular/lifecycle.md.
React
For full details, see ionic-react.
Key setup differences:
- - Call
setupIonicReact() before rendering in src/main.tsx. - Use
IonReactRouter (from @ionic/react-router) instead of BrowserRouter. - Use
IonRouterOutlet to contain routes with the component prop (not render or children). - Every page must render
IonPage as root — required for transitions and lifecycle hooks.
Navigation: Use useIonRouter hook for programmatic navigation:
CODEBLOCK8
Lifecycle hooks (from @ionic/react):
CODEBLOCK9
Overlay hooks: useIonAlert, useIonToast, useIonActionSheet, useIonLoading, useIonModal, useIonPopover, useIonPicker.
Form events: Use onIonInput for IonInput/IonTextarea, onIonChange for IonSelect/IonToggle/IonCheckbox/IonRange. Access values via e.detail.value.
For routing details, see react/routing.md. For hooks, see react/hooks.md.
Vue
For full details, see ionic-vue.
Key setup differences:
- - Install
IonicVue plugin in src/main.ts: createApp(App).use(IonicVue).use(router). - Import
createRouter from @ionic/vue-router (not from vue-router). - Every page must use
IonPage as root template element — without it, transitions and lifecycle hooks silently fail. - Import all Ionic components from
@ionic/vue. - Use kebab-case for event names in templates (
@ion-change, @ion-input). - Import icons as SVG references from
ionicons/icons — never as strings.
Navigation: Use useIonRouter composable:
CODEBLOCK10
Declarative: INLINECODE268
Lifecycle hooks (from @ionic/vue):
CODEBLOCK11
Composables: useIonRouter(), useBackButton(priority, handler), useKeyboard(), isPlatform(name), getPlatforms().
Access Web Component methods via $el: contentRef.value.$el.scrollToBottom(300).
For navigation details, see vue/navigation.md. For composables, see vue/composables.md.
Navigation Patterns
Tab Navigation
Each framework uses ion-tabs with ion-tab-bar and child routes per tab. Each tab maintains its own navigation stack.
Rules:
- - The
tab attribute on ion-tab-button must match the child route path. - Never navigate between tabs programmatically — only the tab bar buttons should switch tabs.
- For shared views across tabs, use
ion-modal instead of cross-tab routing.
Side Menu
Use ion-menu with contentId matching the id on ion-router-outlet. Wrap menu items in ion-menu-toggle to auto-close after selection. Use routerDirection="root" for top-level menu navigation.
Linear vs. Non-Linear Routing
- - Linear: Sequential forward/back navigation (list -> detail -> edit). Back button returns to the previous page.
- Non-linear: Multiple independent stacks (tabs). Back navigation stays within the current tab's stack.
Use non-linear routing for tabs or split-pane layouts. Use linear routing for simple page flows.
Upgrading
Ionic supports upgrades from version 4 through 8. Each major version jump must be applied sequentially — do not skip intermediate versions.
For full upgrade guides, see ionic-app-upgrades.
Capacitor Integration
Ionic apps use Capacitor for native device features (camera, filesystem, push notifications, etc.). The standard workflow:
CODEBLOCK12
For live reload on a device:
CODEBLOCK13
For Capacitor guidance, see the capacitor-app-development skill.
Capawesome Cloud
Capawesome Cloud provides CI/CD services for Ionic/Capacitor apps:
- - Live Updates — Deploy OTA updates to Ionic/Capacitor apps instantly, without app store review.
- Native Builds — Build iOS and Android binaries in the cloud without local Xcode or Android Studio.
- App Store Publishing — Automate submissions to the Apple App Store and Google Play Store.
Visit capawesome.io for the full Capawesome ecosystem. For setup, see the capawesome-cloud skill.
Common Troubleshooting
- -
ionic: command not found: Run npm install -g @ionic/cli. - Components not rendering: Verify Ionic CSS files are imported in the global stylesheet. For standalone Angular, verify each component is imported from
@ionic/angular/standalone. ionViewWillEnter not firing: The component must be directly routed via ion-router-outlet. Child components do not receive lifecycle events. For React/Vue, verify IonPage is the root element.- Page data not refreshing on back navigation: Use Ionic lifecycle hooks (
ionViewWillEnter) instead of framework-native lifecycle hooks (ngOnInit, useEffect, onMounted). Ionic caches pages in the DOM. - Page transitions not animating: Use the framework's Ionic router integration (
NavController for Angular, IonReactRouter for React, createRouter from @ionic/vue-router for Vue). Standard framework routers do not trigger Ionic animations. - CSS custom properties not applying: Ionic components use Shadow DOM. Use documented CSS custom properties (
--background, --color) instead of targeting internal elements. - Icons not showing (Angular standalone): Call
addIcons() from ionicons with the required icons and import IonIcon from @ionic/angular/standalone. Failed to resolve component: ion-* (Vue): The Ionic component is not imported. Add the import from @ionic/vue.- Tab bar disappears on sub-page (React): All routes (including detail routes) must be inside the
IonRouterOutlet within IonTabs. - Form input values not updating (React): Use
onIonInput for IonInput/IonTextarea, not onChange. Access values via e.detail.value. - Slot attribute deprecation warning (Vue): Ionic uses Web Component slots. Disable the ESLint rule:
'vue/no-deprecated-slot-attribute': 'off'.
Related Skills
- -
ionic-app-creation — Create a new Ionic app from scratch. ionic-app-development — General Ionic development, full component API reference.ionic-angular — Angular-specific patterns (standalone vs NgModule, navigation, forms, testing).ionic-react — React-specific patterns (IonReactRouter, hooks, state management).ionic-vue — Vue-specific patterns (composables, navigation, IonPage requirement).ionic-app-upgrades — Upgrade Ionic to a newer major version.capacitor-app-development — General Capacitor development.capawesome-cloud — Live updates, native builds, and app store publishing.
Ionic Framework
Ionic Framework开发的全面参考——核心概念、组件、主题、生命周期、导航、框架特定模式（Angular、React、Vue）、升级以及Capawesome Cloud集成。
核心概念
Ionic Framework是一个使用Web技术构建跨平台应用的UI工具包。它提供了80多个预构建的UI组件，这些组件以ion-为前缀的Web组件形式存在（例如、）。
- - 平台模式：组件会根据平台调整样式。iOS设备使用ios模式；Android和所有其他平台使用md（Material Design）模式。元素会接收一个类（ios或md）。
- Capacitor集成：Ionic负责UI；Capacitor负责原生设备API。有关Capacitor的指导，请参阅capacitor-app-development技能。
- 框架支持：Ionic与Angular（@ionic/angular）、React（@ionic/react）和Vue（@ionic/vue）集成。
创建新应用
bash
npm install -g @ionic/cli
ionic start <名称> <模板> --type=<框架> --capacitor --package-id=
| --type 值 | 框架 |
|---|
| angular | Angular（NgModules） |
| angular-standalone |
Angular（独立组件） |
| react | React |
| vue | Vue |
基于标签的布局 |
| sidemenu | 侧边菜单布局 |
详情请参阅 ionic-app-creation。
Ionic CLI
运行 ionic --help 获取完整且始终最新的命令列表。
| 命令 | 描述 |
|---|
| ionic start | 搭建一个新的Ionic项目。 |
| ionic serve |
启动带有热重载的本地开发服务器（端口8100）。 |
| ionic build | 构建生产环境的Web应用。 |
| ionic generate | 生成页面、组件、服务（依赖于框架）。 |
| ionic info | 打印系统/环境信息。 |
| ionic repair | 移除并重新创建依赖项和平台文件。 |
有用的 ionic serve 标志：--external（所有网络接口）、--port=<端口>、--prod、--no-open。
组件概览
Ionic提供了80多个按类别组织的UI组件。有关完整的API参考（属性、事件、方法、插槽、CSS自定义属性），请参阅链接的参考文件。
布局
ion-app（根容器）、ion-content（可滚动区域）、ion-header、ion-footer、ion-toolbar、ion-title、ion-buttons、ion-back-button、ion-grid/ion-row/ion-col、ion-split-pane。
关键用法：
html
页面标题
详情请参阅 components-layout.md。
导航
ion-tabs、ion-tab-bar、ion-tab-button、ion-menu、ion-menu-button、ion-menu-toggle、ion-router-outlet、ion-nav、ion-breadcrumbs。
详情请参阅 components-navigation.md。
表单
ion-input、ion-textarea、ion-select/ion-select-option、ion-checkbox、ion-toggle、ion-radio/ion-radio-group、ion-range、ion-datetime/ion-datetime-button、ion-searchbar、ion-segment/ion-segment-button、ion-input-otp。
大多数表单组件共享的关键属性：label、labelPlacement（floating、stacked、fixed、start）、fill（outline、solid）、errorText、helperText、disabled、value、placeholder。
关键事件：
- - ionInput — 每次按键时触发（用于ion-input/ion-textarea）。
- ionChange — 值提交时触发（用于ion-select、ion-toggle、ion-checkbox、ion-range）。
html
type=email placeholder=you@example.com
errorText=无效邮箱 helperText=请输入您的邮箱>
美国
德国
详情请参阅 components-form.md。
覆盖层
ion-modal、ion-alert、ion-toast、ion-action-sheet、ion-loading、ion-popover。
所有覆盖层共享：用于声明式控制的 isOpen 属性、用于从按钮ID打开的 trigger 属性、backdropDismiss、animated 以及生命周期事件（didPresent、didDismiss、willPresent、willDismiss）。
底部表单模态框：
html
底部表单内容
详情请参阅 components-overlay.md。
数据展示
ion-list、ion-item、ion-item-sliding/ion-item-options/ion-item-option、ion-card/ion-card-header/ion-card-content、ion-accordion/ion-accordion-group、ion-chip、ion-badge、ion-label、ion-note。
详情请参阅 components-data-display.md。
滚动
ion-refresher/ion-refresher-content（下拉刷新）、ion-infinite-scroll/ion-infinite-scroll-content、ion-reorder-group/ion-reorder。
详情请参阅 components-scroll.md。
操作与媒体
ion-button、ion-fab/ion-fab-button、ion-icon、ion-avatar、ion-thumbnail、ion-spinner、ion-skeleton-text、ion-progress-bar。
详情请参阅 components-action.md 和 components-media.md。
主题
颜色
九种默认颜色：primary、secondary、tertiary、success、warning、danger、light、medium、dark。通过 color 属性应用：
html
保存
删除
通过覆盖 :root 中的所有六个CSS变量来自定义颜色：
css
:root {
--ion-color
