Ionic App Development
General Ionic Framework development — core concepts, component reference, CLI usage, layout, theming, utilities, development workflow, and troubleshooting.
Prerequisites
- 1. Node.js (latest LTS) installed.
- Ionic CLI installed globally (
npm install -g @ionic/cli). - An existing Ionic project. For creating a new Ionic app, use the
ionic-app-creation skill.
Agent Behavior
- - Auto-detect the framework. Check
package.json for @ionic/angular, @ionic/react, or @ionic/vue to determine the framework in use. Adapt code examples accordingly. - Route to reference files. This skill is an overview that routes agents to specific reference files for detailed component APIs and topic-specific guidance.
- Do not duplicate framework-specific skills. For Angular, React, or Vue specific patterns, refer to the respective framework skill.
Core Concepts
How Ionic Works
Ionic Framework is a UI toolkit for building cross-platform apps using web technologies (HTML, CSS, JavaScript/TypeScript). It provides a library of pre-built UI components that adapt their styling to the platform (ios or md mode).
- - Components are custom HTML elements (Web Components) prefixed with
ion- (e.g., <ion-button>, <ion-content>). - Platform modes: Ionic renders components differently based on the platform. iOS devices use the
ios mode; Android and all other platforms use the md (Material Design) mode. The <html> element receives a class (ios or md) that enables platform-specific styles. - Capacitor integration: Ionic apps use Capacitor to access native device features. Ionic handles the UI; Capacitor handles native APIs. See the
capacitor-app-development skill for Capacitor-specific guidance.
Page Lifecycle
Ionic provides lifecycle events on top of the framework's own lifecycle hooks. These fire when a page is navigated to or from:
| Event | Description |
|---|
| INLINECODE17 | Fires when the page is about to enter and become active. |
| INLINECODE18 |
Fires when the page has fully entered and is now active. |
|
ionViewWillLeave | Fires when the page is about to leave and become inactive. |
|
ionViewDidLeave | Fires when the page has fully left and is now inactive. |
These are in addition to the framework-specific lifecycle hooks (e.g., Angular's ngOnInit, React's useEffect, Vue's onMounted). Use Ionic lifecycle events for tasks that should run each time a page becomes visible (e.g., refreshing data), since some navigation strategies cache pages.
Component Reference
Ionic provides 80+ UI components. Detailed API documentation for each component is organized into reference files by category. Each reference file covers properties, events, methods, slots, CSS shadow parts, and CSS custom properties.
When the user needs help with a specific component, read the corresponding reference file.
| Category | Reference File | Components Covered |
|---|
| Action & Buttons | INLINECODE24 | action-sheet, button, fab, fab-button, fab-list, ripple-effect |
| Data Display |
references/components-data-display.md | accordion, accordion-group, badge, card, card-content, card-header, card-subtitle, card-title, chip, item, item-divider, item-group, item-sliding, item-options, item-option, label, list, list-header, note, text |
| Form |
references/components-form.md | checkbox, datetime, datetime-button, input, input-otp, input-password-toggle, picker, radio, radio-group, range, searchbar, select, select-option, segment, segment-button, segment-content, segment-view, textarea, toggle |
| Layout |
references/components-layout.md | app, content, grid, col, row, header, footer, toolbar, title, buttons, back-button, split-pane |
| Media |
references/components-media.md | avatar, icon, img, thumbnail |
| Navigation |
references/components-navigation.md | breadcrumb, breadcrumbs, menu, menu-button, menu-toggle, nav, nav-link, router, router-link, router-outlet, route, route-redirect, tabs, tab, tab-bar, tab-button |
| Overlay |
references/components-overlay.md | alert, loading, modal, popover, toast, backdrop |
| Scroll & Virtual |
references/components-scroll.md | infinite-scroll, infinite-scroll-content, refresher, refresher-content, reorder, reorder-group |
| Progress |
references/components-progress.md | progress-bar, skeleton-text, spinner |
Ionic CLI
The Ionic CLI is the primary tool for developing Ionic apps. Below are the most commonly used commands. Run ionic --help for the full and always up-to-date command list.
Installation
CODEBLOCK0
If upgrading from the legacy ionic package:
CODEBLOCK1
Key Commands
| Command | Description |
|---|
| INLINECODE35 | Start a local dev server with live reload. |
| INLINECODE36 |
Serve on all network interfaces (for testing on devices). |
|
ionic serve --port=<port> | Serve on a custom port (default: 8100). |
|
ionic serve --prod | Serve with production build configuration. |
|
ionic build | Build the web app for production. |
|
ionic generate | Generate pages, components, services (framework-dependent). |
|
ionic doctor check | Check the project for common issues. |
|
ionic info | Print system/environment info for bug reports. |
|
ionic repair | Remove and recreate dependencies and platform files. |
ionic serve Options
| Option | Description |
|---|
| INLINECODE45 | Enable HTTPS (experimental). |
| INLINECODE46 |
Serve without automatic reloading. |
|
--no-open | Do not open a browser window automatically. |
|
--consolelogs | Print app console output in terminal. |
|
--browser=<browser> | Open in a specific browser (safari, firefox, google chrome). |
|
--browseroption=<path> | Open a specific URL path (e.g.,
/#/tab/dash). |
For framework-specific CLI options, pass them after --:
CODEBLOCK2
Layout
Read references/components-layout.md for the full API reference for layout components.
Grid System
Ionic uses a 12-column flexbox grid system (ion-grid, ion-row, ion-col). Columns expand to fill the row evenly unless a size attribute is specified (1-12).
Responsive breakpoints:
| Breakpoint | Min Width | CSS Class Prefix |
|---|
| INLINECODE58 | 0 | (default) |
| INLINECODE59 |
576px |
sizeSm |
|
md | 768px |
sizeMd |
|
lg | 992px |
sizeLg |
|
xl | 1200px |
sizeXl |
CSS Utility Classes
Ionic provides responsive CSS utility classes for common styling needs:
- - Text:
.ion-text-center, .ion-text-start, .ion-text-end, .ion-text-wrap, .ion-text-nowrap, .ion-text-uppercase, .ion-text-lowercase, INLINECODE74 - Padding:
.ion-padding, .ion-padding-top, .ion-padding-bottom, .ion-padding-start, .ion-padding-end, .ion-padding-vertical, .ion-padding-horizontal, INLINECODE82 - Margin:
.ion-margin, .ion-margin-top, .ion-margin-bottom, .ion-margin-start, .ion-margin-end, .ion-margin-vertical, .ion-margin-horizontal, INLINECODE90 - Display:
.ion-display-none, .ion-display-block, .ion-display-flex, .ion-display-inline, INLINECODE95 - Float:
.ion-float-left, .ion-float-right, .ion-float-start, INLINECODE99 - Flex:
.ion-justify-content-center, .ion-align-items-center, .ion-flex-row, .ion-flex-column, .ion-flex-wrap, INLINECODE105 - Border: INLINECODE106
All utility classes support responsive breakpoint suffixes: ion-text-{breakpoint}-center (e.g., .ion-text-md-center applies at 768px+).
Theming
Colors
Ionic provides nine default colors: primary, secondary, tertiary, success, warning, danger, light, medium, dark. Apply via the color attribute on components:
CODEBLOCK3
Each color has six CSS custom properties:
- -
--ion-color-{name} — Base color value - INLINECODE120 — Base color in RGB format
- INLINECODE121 — Text color for readability
- INLINECODE122 — Contrast color in RGB format
- INLINECODE123 — Darker variant (active/pressed states)
- INLINECODE124 — Lighter variant (hover states)
To customize a color, override all six variables in :root:
CODEBLOCK4
To add a custom color, define the CSS variables and create a class:
CODEBLOCK5
Global CSS Variables
| Variable | Description |
|---|
| INLINECODE126 | Background color of the app |
| INLINECODE127 |
Text color of the app |
|
--ion-font-family | Font family of the app |
|
--ion-statusbar-padding | Statusbar padding top of the app |
|
--ion-safe-area-top | Adjust safe area inset top |
|
--ion-safe-area-right | Adjust safe area inset right |
|
--ion-safe-area-bottom | Adjust safe area inset bottom |
|
--ion-safe-area-left | Adjust safe area inset left |
|
--ion-margin | Default margin for margin utility classes |
|
--ion-padding | Default padding for padding utility classes |
|
--ion-placeholder-opacity | Opacity of placeholder text in inputs |
Dark Mode
Ionic supports three dark mode approaches:
1. System Preference (Default)
Automatically applies dark palette based on the user's OS setting:
CODEBLOCK6
2. Always Dark
Forces dark mode regardless of system settings:
CODEBLOCK7
3. CSS Class Toggle
Enables manual dark mode control via a CSS class:
CODEBLOCK8
Add .ion-palette-dark to the <html> element to activate:
CODEBLOCK9
Add this meta tag to adjust system UI elements (scrollbars, etc.):
CODEBLOCK10
Platform Styles
Ionic uses two modes for platform-specific styling:
| Platform | Default Mode | Style |
|---|
| iOS | INLINECODE139 | Apple iOS design |
| Android |
md | Material Design |
| Other / Web |
md | Material Design |
To preview a specific mode in the browser, add ?ionic:mode=ios or ?ionic:mode=md to the URL:
CODEBLOCK11
Target mode-specific styles in CSS:
CODEBLOCK12
Developing
Previewing in the Browser
The primary development workflow is browser-based:
CODEBLOCK13
This starts a development server at http://localhost:8100 with live reload.
Use browser DevTools to simulate mobile devices:
- - Chrome:
Cmd+Opt+I (Mac) / Ctrl+Shift+I (Windows/Linux), then toggle device toolbar - Safari:
Cmd+Opt+R for Responsive Design Mode - Firefox:
Cmd+Opt+M (Mac) / Ctrl+Shift+M (Windows/Linux)
Testing on Devices
For native functionality that requires a real device:
CODEBLOCK14
For live reload on a device:
CODEBLOCK15
Debugging Tips
- - Use the
debugger keyword to set breakpoints in code. - Add
?ionic:mode=ios to the URL to preview iOS styles in the browser. - Use
ionic info to collect environment info for troubleshooting.
Utilities
Animations
Ionic provides a framework-agnostic animation utility built on the Web Animations API. Import:
- - JavaScript/TypeScript: INLINECODE153
- Angular: Inject
AnimationController from INLINECODE155 - React: Use
CreateAnimation component from INLINECODE157 - Vue: INLINECODE158
Key methods: addElement(), duration(), easing(), fromTo(), keyframes(), play(), pause(), stop(), onFinish().
Animations support grouping (parent-child), chaining (via play() promises), and integration with gestures.
For performance, prefer animating transform and opacity over height and width.
Gestures
Ionic provides a framework-agnostic gesture utility. Import:
- - JavaScript/TypeScript: INLINECODE173
- Angular: Inject
GestureController from INLINECODE175 - React: INLINECODE176
- Vue: INLINECODE177
Configuration options: el, gestureName, threshold, direction (x/y), maxAngle, gesturePriority, disableScroll, passive.
Callbacks: canStart, onWillStart, onStart, onMove, onEnd, notCaptured.
The GestureDetail object provides startX/startY, currentX/currentY, deltaX/deltaY, and velocityX/velocityY.
Hardware Back Button (Android)
Ionic emits an ionBackButton event when the Android hardware back button is pressed. Handlers are priority-based:
| Priority | Handler |
|---|
| 100 | Overlays |
| 99 |
Menu |
| 0 | Navigation |
For Capacitor apps, install @capacitor/app to enable hardware back button support. See the framework-specific skills for implementation patterns.
Error Handling
- -
ionic: command not found: The Ionic CLI is not installed. Run npm install -g @ionic/cli. - Port 8100 in use: Another process is using the default port. Run
ionic serve --port=<other-port>. - Components not rendering: Verify the Ionic CSS files are imported in the global stylesheet. For Angular:
@import '@ionic/angular/css/core.css';. For React/Vue: check the framework-specific import. - Platform styles not applied: Ensure
@ionic/angular, @ionic/react, or @ionic/vue is installed and configured. The <html> element should have an ios or md class. - Dark mode not working: Verify the correct dark palette CSS import is present. For the class method, ensure
.ion-palette-dark is applied to the <html> element. - CSS custom properties not applying: Ionic components use Shadow DOM. Use the component's documented CSS custom properties (e.g.,
--background, --color) rather than targeting internal elements directly. Check the component reference file for available properties. - Live reload not working on device: Ensure the device and development machine are on the same network. Use the
--external flag with npx cap run. ionViewWillEnter not firing: This lifecycle event only fires with Ionic's routing components (ion-router-outlet). It does not fire with standard framework routers unless Ionic's routing integration is used.
Related Skills
- -
ionic-app-creation — Create a new Ionic app. ionic-angular — Ionic with Angular (framework-specific patterns).ionic-react — Ionic with React (framework-specific patterns).ionic-vue — Ionic with Vue (framework-specific patterns).ionic-app-upgrades — Upgrade Ionic to a newer major version.capacitor-app-development — General Capacitor development.capacitor-plugins — Capacitor plugins installation and configuration.
Ionic App Development
通用Ionic框架开发——核心概念、组件参考、CLI使用、布局、主题、工具、开发工作流及故障排除。
前置条件
- 1. 已安装 Node.js（最新LTS版本）。
- 全局安装 Ionic CLI（npm install -g @ionic/cli）。
- 存在一个Ionic项目。如需创建新Ionic应用，请使用 ionic-app-creation 技能。
代理行为
- - 自动检测框架。 检查 package.json 中的 @ionic/angular、@ionic/react 或 @ionic/vue，以确定当前使用的框架，并相应调整代码示例。
- 路由至参考文件。 本技能为概述性内容，将代理引导至特定参考文件，以获取详细的组件API和主题相关指导。
- 不重复框架特定技能。 对于Angular、React或Vue的特定模式，请参考相应的框架技能。
核心概念
Ionic工作原理
Ionic Framework是一个UI工具包，用于使用Web技术（HTML、CSS、JavaScript/TypeScript）构建跨平台应用。它提供了一系列预构建的UI组件，这些组件会根据平台（ios 或 md 模式）自动调整样式。
- - 组件 是以 ion- 为前缀的自定义HTML元素（Web组件），例如 、。
- 平台模式：Ionic根据平台以不同方式渲染组件。iOS设备使用 ios 模式；Android及其他所有平台使用 md（Material Design）模式。 元素会接收一个类名（ios 或 md），用于启用特定平台的样式。
- Capacitor集成：Ionic应用使用Capacitor访问原生设备功能。Ionic负责UI，Capacitor负责原生API。Capacitor相关指导请参见 capacitor-app-development 技能。
页面生命周期
Ionic在框架自身的生命周期钩子之上提供了生命周期事件。这些事件在页面导航进入或离开时触发：
| 事件 | 描述 |
|---|
| ionViewWillEnter | 页面即将进入并变为活跃状态时触发。 |
| ionViewDidEnter |
页面已完全进入并处于活跃状态时触发。 |
| ionViewWillLeave | 页面即将离开并变为非活跃状态时触发。 |
| ionViewDidLeave | 页面已完全离开并处于非活跃状态时触发。 |
这些事件是框架特定生命周期钩子（例如Angular的 ngOnInit、React的 useEffect、Vue的 onMounted）的补充。对于每次页面变为可见时应执行的任务（例如刷新数据），请使用Ionic生命周期事件，因为某些导航策略会缓存页面。
组件参考
Ionic提供了80多个UI组件。每个组件的详细API文档按类别组织在参考文件中。每个参考文件涵盖了属性、事件、方法、插槽、CSS Shadow Parts和CSS自定义属性。
当用户需要特定组件的帮助时，请阅读相应的参考文件。
| 类别 | 参考文件 | 涵盖的组件 |
|---|
| 操作与按钮 | references/components-action.md | action-sheet, button, fab, fab-button, fab-list, ripple-effect |
| 数据展示 |
references/components-data-display.md | accordion, accordion-group, badge, card, card-content, card-header, card-subtitle, card-title, chip, item, item-divider, item-group, item-sliding, item-options, item-option, label, list, list-header, note, text |
| 表单 | references/components-form.md | checkbox, datetime, datetime-button, input, input-otp, input-password-toggle, picker, radio, radio-group, range, searchbar, select, select-option, segment, segment-button, segment-content, segment-view, textarea, toggle |
| 布局 | references/components-layout.md | app, content, grid, col, row, header, footer, toolbar, title, buttons, back-button, split-pane |
| 媒体 | references/components-media.md | avatar, icon, img, thumbnail |
| 导航 | references/components-navigation.md | breadcrumb, breadcrumbs, menu, menu-button, menu-toggle, nav, nav-link, router, router-link, router-outlet, route, route-redirect, tabs, tab, tab-bar, tab-button |
| 覆盖层 | references/components-overlay.md | alert, loading, modal, popover, toast, backdrop |
| 滚动与虚拟 | references/components-scroll.md | infinite-scroll, infinite-scroll-content, refresher, refresher-content, reorder, reorder-group |
| 进度 | references/components-progress.md | progress-bar, skeleton-text, spinner |
Ionic CLI
Ionic CLI是开发Ionic应用的主要工具。以下是常用命令。运行 ionic --help 获取完整且最新的命令列表。
安装
bash
npm install -g @ionic/cli
如果从旧版 ionic 包升级：
bash
npm uninstall -g ionic
npm install -g @ionic/cli
关键命令
| 命令 | 描述 |
|---|
| ionic serve | 启动本地开发服务器，支持热重载。 |
| ionic serve --external |
在所有网络接口上提供服务（用于在设备上测试）。 |
| ionic serve --port=
| 在自定义端口上提供服务（默认：8100）。 |
| ionic serve --prod | 使用生产构建配置提供服务。 |
| ionic build | 构建生产环境的Web应用。 |
| ionic generate | 生成页面、组件、服务（依赖于框架）。 |
| ionic doctor check | 检查项目是否存在常见问题。 |
| ionic info | 打印系统/环境信息，用于错误报告。 |
| ionic repair | 移除并重新创建依赖项和平台文件。 |
ionic serve 选项
| 选项 | 描述 |
|---|
| --ssl | 启用HTTPS（实验性功能）。 |
| --no-livereload |
提供服务但不自动重新加载。 |
| --no-open | 不自动打开浏览器窗口。 |
| --consolelogs | 在终端中打印应用控制台输出。 |
| --browser= | 在特定浏览器中打开（safari, firefox, google chrome）。 |
| --browseroption= | 打开特定的URL路径（例如 /#/tab/dash）。 |
如需传递框架特定的CLI选项，请在 -- 后添加：
bash
ionic serve -- --proxy-config proxy.conf.json
布局
请阅读 references/components-layout.md 获取布局组件的完整API参考。
网格系统
Ionic使用12列flexbox网格系统（ion-grid、ion-row、ion-col）。除非指定了 size 属性（1-12），否则列将均匀扩展以填满行。
响应式断点：
576px | sizeSm |
| md | 768px | sizeMd |
| lg | 992px | sizeLg |
| xl | 1200px | sizeXl |
CSS工具类
Ionic为常见样式需求提供了响应式CSS工具类：
- - 文本：.ion-text-center、.ion-text-start、.ion-text-end、.ion-text-wrap、.ion-text-nowrap、.ion-text-uppercase、.ion-text-lowercase、.ion-text-capitalize
- 内边距：.ion-padding、.ion-padding-top、.ion-padding-bottom、.ion-padding-start、.ion-padding-end、.ion-padding-vertical、.ion-padding-horizontal、.ion-no-padding
- 外边距：.ion-margin、.ion-margin-top、.ion-margin-bottom、.ion-margin-start、.ion-margin-end、.ion-margin-vertical、.ion-margin-horizontal、.ion-no-margin
- 显示：.ion-display-none、.ion-display-block、.ion-display-flex、.
