)}
diff --git a/src/components/global/DocsCard/styles.module.scss b/src/components/global/DocsCard/styles.module.scss
index 8b3955f0fe9..a57e862b16c 100644
--- a/src/components/global/DocsCard/styles.module.scss
+++ b/src/components/global/DocsCard/styles.module.scss
@@ -116,20 +116,19 @@ docs-card[disabled]::after {
.Card-icon-row {
position: relative;
+ display: flex;
+ gap: 8px;
}
- .Card-iconset__container {
- position: relative;
- }
-
- .Card-iconset__container .Card-icon {
- position: absolute;
- opacity: 0;
- transition: 0.8s opacity;
- }
-
- .Card-iconset__container .Card-icon--active {
- opacity: 1;
+ .Card-plus-icon {
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ width: 24px;
+ height: 48px;
+ color: var(--docs-card-border-c);
+ font-size: 22px;
+ font-weight: 600;
}
.Card-ionicon {
diff --git a/src/components/global/DocsCards/cards.css b/src/components/global/DocsCards/cards.css
index eadaa0350b0..b77622963f7 100644
--- a/src/components/global/DocsCards/cards.css
+++ b/src/components/global/DocsCards/cards.css
@@ -2,7 +2,11 @@ docs-cards {
display: grid;
font-size: 12px;
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
- grid-gap: 1.35rem;
+ gap: 1.35rem;
+}
+
+docs-cards:has(docs-card:only-child) {
+ grid-template-columns: 1fr 1fr;
}
docs-cards > docs-card {
From b35e544a898018f4c10cb934acc7585237f785ab Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Fri, 17 Oct 2025 17:41:34 -0400
Subject: [PATCH 02/14] docs(intro): update packages & cdn docs to link
packages to other guides
---
docs/intro/cdn.md | 168 ++++++++++++++--------------------------------
1 file changed, 52 insertions(+), 116 deletions(-)
diff --git a/docs/intro/cdn.md b/docs/intro/cdn.md
index a90c4a6b250..a534663b0e2 100644
--- a/docs/intro/cdn.md
+++ b/docs/intro/cdn.md
@@ -1,156 +1,94 @@
---
-title: Ionic Packages
+title: Ionic Packages & CDN
sidebar_label: Packages & CDN
---
- Ionic Framework Packages: CDN, Angular, Vue, and React
+ Ionic Framework Packages: CDN, Angular, Vue, React, and JavaScript
-Ionic provides different packages that can be used to quickly get started using Ionic Framework or Ionicons in a test environment, Angular, any other framework, or none at all.
+import DocsCard from '@components/global/DocsCard';
+import DocsCards from '@components/global/DocsCards';
-## Ionic Framework CDN
+Ionic Framework offers npm packages for Angular, React, Vue, and JavaScript, plus CDN links for quick prototyping. Choose your framework below to get started, or use the CDN to test Ionic Framework components in the browser.
-Ionic Framework can be included from a CDN for quick testing in a [Plunker](https://plnkr.co/), [Codepen](https://codepen.io), or any other online code editor!
+## Ionic Angular
-It's recommended to use [jsdelivr](https://www.jsdelivr.com/) to access the Framework from a CDN. To get the latest version, add the following inside the `` element in an HTML file, or where external assets are included in the online code editor:
+Start a new Ionic Angular app or add Ionic to your existing Angular project.
-```html
-
-
-
-```
+
-With this it's possible to use all of the Ionic Framework core components without having to install a framework. The CSS bundle will include all of the Ionic [Global Stylesheets](../layout/global-stylesheets).
+
+
Create a new Ionic Angular app using the Ionic CLI.
+
-:::note
-This does not install Angular or any other frameworks. This allows use of the Ionic Framework core components without a framework.
-:::
+
+
Add Ionic Angular to an existing Angular project.
+
-## Ionic + Angular
+
-When using Ionic Framework in an Angular project, install the latest `@ionic/angular` package from [npm](../reference/glossary.md#npm). This comes with all of the Ionic Framework components and Angular specific services and features.
+## Ionic React
-```shell
-npm install @ionic/angular@latest --save
-```
+Start a new Ionic React app or add Ionic to your existing React project.
-Each time there is a new Ionic Framework release, this [version](../reference/versioning.md) will need to be updated to get the latest features and fixes. The version can be [updated using npm](../developing/tips.md#updating-dependencies), as well.
+
-For adding Ionic to an already existing Angular project, use the Angular CLI's `ng add` feature.
+
+
Create a new Ionic React app using the Ionic CLI.
+
-```shell
-ng add @ionic/angular
-```
+
+
Add Ionic React to an existing React project.
+
-This will add the necessary imports to the `@ionic/angular` package as well as add the styles needed.
+
-## Ionic + React
+## Ionic Vue
-To add Ionic Framework to an already existing React project, install the `@ionic/react` and `@ionic/react-router` package.
+Start a new Ionic Vue app or add Ionic to your existing Vue project.
-```shell
-$ npm install @ionic/react
-$ npm install @ionic/react-router
-```
-
-### CSS
+
-To include the necessary CSS in a React project, add the following to the root App component.
+
+
Create a new Ionic Vue app using the Ionic CLI.
+
-```javascript
-/* Core CSS required for Ionic components to work properly */
-import '@ionic/react/css/core.css';
+
+
Add Ionic Vue to an existing Vue project.
+
-/* Basic CSS for apps built with Ionic */
-import '@ionic/react/css/normalize.css';
-import '@ionic/react/css/structure.css';
-import '@ionic/react/css/typography.css';
+
-/* Optional CSS utils that can be commented out */
-import '@ionic/react/css/padding.css';
-import '@ionic/react/css/float-elements.css';
-import '@ionic/react/css/text-alignment.css';
-import '@ionic/react/css/text-transformation.css';
-import '@ionic/react/css/flex-utils.css';
-import '@ionic/react/css/display.css';
-```
+## Ionic JavaScript
-## Ionic + Vue
+Start a new Ionic JavaScript app.
-To add Ionic Framework to an existing Vue project, install the `@ionic/vue` and `@ionic/vue-router` packages.
-
-```shell
-npm install @ionic/vue @ionic/vue-router
-```
+
-After that, you will need to install the `IonicVue` plugin in your Vue app.
+
+
Create a new Ionic JavaScript app using Vite.
+
-**main.js**
+
-```javascript
-import { IonicVue } from '@ionic/vue';
-
-import App from './App.vue';
-import router from './router';
-
-const app = createApp(App).use(IonicVue).use(router);
-
-router.isReady().then(() => {
- app.mount('#app');
-});
-```
-
-Be sure to mount your app once `router.isReady()` has resolved.
-
-### Routing
-
-When setting up routing in your Vue app, you will need to import your dependencies from `@ionic/vue-router` instead of `vue-router`.
-
-**router/index.js**
-
-```javascript
-import { createRouter, createWebHistory } from '@ionic/vue-router';
-
-const routes = [
- // routes go here
-];
-
-const router = createRouter({
- history: createWebHistory(process.env.BASE_URL),
- routes,
-});
-
-export default router;
-```
-
-### CSS
-
-To include the necessary CSS in a Vue project, add the following to your `main.js` file.
+## Ionic Framework CDN
-```javascript
-/* Core CSS required for Ionic components to work properly */
-import '@ionic/vue/css/core.css';
+Ionic Framework can be included from a CDN for quick testing in a [StackBlitz](https://stackblitz.com/), [Plunker](https://plnkr.co/), [Codepen](https://codepen.io), or any other online code editor!
-/* Basic CSS for apps built with Ionic */
-import '@ionic/vue/css/normalize.css';
-import '@ionic/vue/css/structure.css';
-import '@ionic/vue/css/typography.css';
+It's recommended to use [jsdelivr](https://www.jsdelivr.com/) to access the Framework from a CDN. To get the latest version, add the following inside the `` element in an HTML file, or where external assets are included in the online code editor:
-/* Optional CSS utils that can be commented out */
-import '@ionic/vue/css/padding.css';
-import '@ionic/vue/css/float-elements.css';
-import '@ionic/vue/css/text-alignment.css';
-import '@ionic/vue/css/text-transformation.css';
-import '@ionic/vue/css/flex-utils.css';
-import '@ionic/vue/css/display.css';
+```html
+
+
+
```
-From here, you can learn about how to develop with Ionic Framework in our [Ionic Vue Quickstart Guide](https://ionicframework.com/docs/vue/quickstart).
+With this it's possible to use all of the Ionic Framework core components without having to install a framework. The CSS bundle will include all of the Ionic [Global Stylesheets](../layout/global-stylesheets).
## Ionicons CDN
@@ -161,6 +99,4 @@ Ionicons is packaged by default with the Ionic Framework, so no installation is
```
-:::note
-See [Ionicons usage](https://ionic.io/ionicons/usage) for more information on using Ionicons.
-:::
+For more information on using Ionicons, visit the [Ionicons documentation](https://ionic.io/ionicons/usage).
From c030630aa72f64f85026b54dbf07525319e525b3 Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Fri, 17 Oct 2025 17:48:31 -0400
Subject: [PATCH 03/14] docs(react): rename adding to existing app file and add
redirects
---
.../react/add-to-existing.md | 17 ++++++++++++++---
sidebars.js | 2 +-
vercel.json | 10 +++++++++-
.../version-v7/react/add-to-existing.md | 17 ++++++++++++++---
versioned_sidebars/version-v7-sidebars.json | 2 +-
5 files changed, 39 insertions(+), 9 deletions(-)
rename versioned_docs/version-v7/react/adding-ionic-react-to-an-existing-react-project.md => docs/react/add-to-existing.md (90%)
rename docs/react/adding-ionic-react-to-an-existing-react-project.md => versioned_docs/version-v7/react/add-to-existing.md (91%)
diff --git a/versioned_docs/version-v7/react/adding-ionic-react-to-an-existing-react-project.md b/docs/react/add-to-existing.md
similarity index 90%
rename from versioned_docs/version-v7/react/adding-ionic-react-to-an-existing-react-project.md
rename to docs/react/add-to-existing.md
index 20bf7b3fcb7..8f975e5b736 100644
--- a/versioned_docs/version-v7/react/adding-ionic-react-to-an-existing-react-project.md
+++ b/docs/react/add-to-existing.md
@@ -1,6 +1,17 @@
-# Adding To An Existing React App
-
-This post has been forked from [Ely Lucas' blog post](https://dev.to/ionic/adding-ionic-react-to-an-existing-react-project-4kib) and updated to the latest version of Ionic.
+---
+title: Add to Existing React App
+sidebar_label: Add to Existing React App
+---
+
+
+ Add Ionic React to Existing Project: Integration Guide
+
+
+
+This guide covers how to add Ionic React to an existing React project.
### Using Individual Ionic Components
diff --git a/sidebars.js b/sidebars.js
index a04b7796f10..b48905e10e7 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -123,7 +123,7 @@ module.exports = {
'react/your-first-app/distribute',
],
},
- 'react/adding-ionic-react-to-an-existing-react-project',
+ 'react/add-to-existing',
'react/lifecycle',
'react/navigation',
'react/virtual-scroll',
diff --git a/vercel.json b/vercel.json
index 5ab15d8df22..8c7509aaf63 100644
--- a/vercel.json
+++ b/vercel.json
@@ -94,7 +94,15 @@
"destination": "/docs/vue/your-first-app/deploying-mobile"
},
{ "source": "/docs/vue/your-first-app/7-live-reload", "destination": "/docs/vue/your-first-app/live-reload" },
- { "source": "/docs/react/testing", "destination": "/docs/react/testing/introduction" }
+ { "source": "/docs/react/testing", "destination": "/docs/react/testing/introduction" },
+ {
+ "source": "/docs/react/adding-ionic-react-to-an-existing-react-project",
+ "destination": "/docs/react/add-to-existing"
+ },
+ {
+ "source": "/docs/:version(v7)/react/adding-ionic-react-to-an-existing-react-project",
+ "destination": "/docs/:version/react/add-to-existing"
+ }
],
"rewrites": [
{ "source": "/docs", "destination": "/" },
diff --git a/docs/react/adding-ionic-react-to-an-existing-react-project.md b/versioned_docs/version-v7/react/add-to-existing.md
similarity index 91%
rename from docs/react/adding-ionic-react-to-an-existing-react-project.md
rename to versioned_docs/version-v7/react/add-to-existing.md
index 20bf7b3fcb7..e658a410697 100644
--- a/docs/react/adding-ionic-react-to-an-existing-react-project.md
+++ b/versioned_docs/version-v7/react/add-to-existing.md
@@ -1,6 +1,17 @@
-# Adding To An Existing React App
-
-This post has been forked from [Ely Lucas' blog post](https://dev.to/ionic/adding-ionic-react-to-an-existing-react-project-4kib) and updated to the latest version of Ionic.
+---
+title: Add to Existing
+sidebar_label: Add to Existing
+---
+
+
+ Add Ionic React to Existing Project: Integration Guide
+
+
+
+This guide covers how to add Ionic React to an existing React project.
### Using Individual Ionic Components
diff --git a/versioned_sidebars/version-v7-sidebars.json b/versioned_sidebars/version-v7-sidebars.json
index 3495cf3d822..0e3dc75dd63 100644
--- a/versioned_sidebars/version-v7-sidebars.json
+++ b/versioned_sidebars/version-v7-sidebars.json
@@ -127,7 +127,7 @@
"react/your-first-app/distribute"
]
},
- "react/adding-ionic-react-to-an-existing-react-project",
+ "react/add-to-existing",
"react/lifecycle",
"react/navigation",
"react/virtual-scroll",
From 18173008d53e1834926166e9a0ba9d1df996ebe1 Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Fri, 17 Oct 2025 17:55:50 -0400
Subject: [PATCH 04/14] style: lint
---
docs/intro/cdn.md | 42 +++++++++++++++++++++++++++++++++++-------
1 file changed, 35 insertions(+), 7 deletions(-)
diff --git a/docs/intro/cdn.md b/docs/intro/cdn.md
index a534663b0e2..5a230b5c939 100644
--- a/docs/intro/cdn.md
+++ b/docs/intro/cdn.md
@@ -22,11 +22,19 @@ Start a new Ionic Angular app or add Ionic to your existing Angular project.
-
+
Create a new Ionic Angular app using the Ionic CLI.
-
+
Add Ionic Angular to an existing Angular project.
@@ -38,11 +46,19 @@ Start a new Ionic React app or add Ionic to your existing React project.
-
+
Create a new Ionic React app using the Ionic CLI.
-
+
Add Ionic React to an existing React project.
@@ -54,11 +70,19 @@ Start a new Ionic Vue app or add Ionic to your existing Vue project.
-
+
Create a new Ionic Vue app using the Ionic CLI.
-
+
Add Ionic Vue to an existing Vue project.
@@ -70,7 +94,11 @@ Start a new Ionic JavaScript app.
-
+
Create a new Ionic JavaScript app using Vite.
From 456605a2467404ee7cb38506556856b38989d080 Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Fri, 17 Oct 2025 18:04:36 -0400
Subject: [PATCH 05/14] style: ignore iconset in cspell
---
cspell-wordlist.txt | 1 +
1 file changed, 1 insertion(+)
diff --git a/cspell-wordlist.txt b/cspell-wordlist.txt
index 13a8a710581..bf433d7615a 100644
--- a/cspell-wordlist.txt
+++ b/cspell-wordlist.txt
@@ -39,6 +39,7 @@ flexbox
frontmatter
fullscreen
geolocation
+iconset
interactives
isopen
jank
From f95905c1f9fa3a4299e4cf08b2e4b94fae67bbbd Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Wed, 12 Nov 2025 10:39:22 -0500
Subject: [PATCH 06/14] docs(angular): add a guide for adding to existing
projects
---
docs/angular/add-to-existing.md | 334 ++++++++++++++++++++++++++++++++
sidebars.js | 1 +
2 files changed, 335 insertions(+)
create mode 100644 docs/angular/add-to-existing.md
diff --git a/docs/angular/add-to-existing.md b/docs/angular/add-to-existing.md
new file mode 100644
index 00000000000..6d9ae4cba95
--- /dev/null
+++ b/docs/angular/add-to-existing.md
@@ -0,0 +1,334 @@
+---
+title: Add to Existing Angular Project
+sidebar_label: Add to Existing
+---
+
+import DocsCard from '@components/global/DocsCard';
+import DocsCards from '@components/global/DocsCards';
+
+
+ Add Ionic Angular to Existing Project: Integration Guide
+
+
+
+This guide covers how to add Ionic Angular to an existing Angular project. If you're looking to start a new project from scratch, check out the [Ionic Angular Quickstart](/docs/angular/quickstart.md) guide. For an overview of how Ionic Angular works with Angular, including version support and tooling, check out the [Ionic Angular Overview](/docs/angular/overview.md).
+
+:::tip
+
+This guide uses `.css` file extensions for stylesheets. If you created your Angular app with a different stylesheet format (such as `.scss`, `.sass`, or `.less`), use that extension instead.
+
+:::
+
+## Setup
+
+You can add Ionic Angular to your existing Angular project using the Angular CLI's `ng add` feature or by installing it manually.
+
+### Using ng add
+
+The easiest way to add Ionic Angular is to use the Angular CLI's `ng add` feature:
+
+```bash
+ng add @ionic/angular
+```
+
+This will install the `@ionic/angular` package and automatically configure the necessary imports and styles.
+
+### Manual Installation
+
+If you prefer to install Ionic Angular manually, you can follow these steps:
+
+#### 1. Install the Package
+
+```bash
+npm install @ionic/angular
+```
+
+#### 2. Add Ionic Framework Stylesheets
+
+Replace the existing `styles` array in `angular.json` with the following:
+
+```json title="angular.json"
+"styles": [
+ "src/styles.css",
+ {
+ "input": "node_modules/@ionic/angular/css/core.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/normalize.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/structure.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/typography.css"
+ }
+]
+```
+
+These stylesheets are required for Ionic Framework components to render properly.
+
+#### 3. Configure Ionic Angular
+
+Update `src/app/app.config.ts` to include `provideIonicAngular`:
+
+```typescript title="src/app/app.config.ts"
+import { ApplicationConfig, provideBrowserGlobalErrorListeners, provideZoneChangeDetection } from '@angular/core';
+import { provideRouter } from '@angular/router';
+
+import { routes } from './app.routes';
+import { provideIonicAngular } from '@ionic/angular/standalone';
+
+export const appConfig: ApplicationConfig = {
+ providers: [
+ provideBrowserGlobalErrorListeners(),
+ provideZoneChangeDetection({ eventCoalescing: true }),
+ provideRouter(routes),
+ provideIonicAngular({}),
+ ],
+};
+```
+
+## Using Individual Components
+
+After completing the setup above, you can start using Ionic components in your existing Angular app. Here's an example of how to use them:
+
+Update `src/app/app.html` to the following:
+
+```html title="src/app/app.html"
+Button
+```
+
+Then, import the components in `src/app/app.ts`:
+
+```ts title="src/app/app.ts"
+import { Component } from '@angular/core';
+import { IonButton, IonDatetime } from '@ionic/angular/standalone';
+
+@Component({
+ selector: 'app-root',
+ imports: [IonButton, IonDatetime],
+ templateUrl: './app.html',
+ styleUrl: './app.css',
+})
+export class App {}
+```
+
+Visit the [components](/docs/components.md) page for all of the available Ionic components.
+
+## Using Ionic Pages
+
+If you want to use Ionic pages with full navigation and page transitions, follow these additional setup steps.
+
+#### 1. Add Additional Ionic Framework Stylesheets
+
+Replace the existing `styles` array in `angular.json` with the following:
+
+```json title="angular.json"
+"styles": [
+ "src/styles.css",
+ {
+ "input": "node_modules/@ionic/angular/css/core.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/normalize.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/structure.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/typography.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/display.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/padding.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/float-elements.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/text-alignment.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/text-transformation.css"
+ },
+ {
+ "input": "node_modules/@ionic/angular/css/flex-utils.css"
+ },
+ {
+ "input": "src/theme/variables.css"
+ }
+]
+```
+
+These stylesheets set up the overall page structure and provide [CSS utilities](/docs/layout/css-utilities.md) for faster development. Some stylesheets are optional. For details on which stylesheets are required, check out [Global Stylesheets](/docs/layout/global-stylesheets.md).
+
+#### 2. Set up Theming
+
+Create a `src/theme/variables.css` file with the following content:
+
+```css title="src/theme/variables.css"
+/**
+ * Ionic Dark Theme
+ * -----------------------------------------------------
+ * For more info, please refer to:
+ * https://ionicframework.com/docs/theming/dark-mode
+ */
+
+/* @import "@ionic/angular/css/palettes/dark.always.css"; */
+/* @import "@ionic/angular/css/palettes/dark.class.css"; */
+@import '@ionic/angular/css/palettes/dark.system.css';
+```
+
+This file enables [dark mode support](/docs/theming/dark-mode.md) for your Ionic app when the system is set to prefer a dark appearance. You can customize the theming behavior by uncommenting different dark palette imports or adding custom CSS variables.
+
+#### 3. Update the App Component
+
+Update `src/app/app.html` to the following:
+
+```html title="src/app/app.html"
+
+
+
+```
+
+Then, update `src/app/app.ts` to include the component imports:
+
+```ts title="src/app/app.ts"
+import { Component } from '@angular/core';
+import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
+
+@Component({
+ selector: 'app-root',
+ imports: [IonApp, IonRouterOutlet],
+ templateUrl: './app.html',
+ styleUrl: './app.css',
+})
+export class App {}
+```
+
+#### 4. Create a Home Page
+
+Start by adding a template at `src/app/home/home.html`:
+
+```html title="src/app/home/home.html"
+
+
+ Home
+
+
+
+
+
+
+ Home
+
+
+
+
+
+```
+
+Then, create `src/app/home/home.ts` with the following:
+
+```ts title="src/app/home/home.ts"
+import { Component } from '@angular/core';
+import { IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';
+
+@Component({
+ selector: 'app-home',
+ imports: [IonContent, IonHeader, IonTitle, IonToolbar],
+ templateUrl: './home.html',
+ styleUrl: './home.css',
+})
+export class HomePage {}
+```
+
+Finally, add a `src/app/home/home.css` file:
+
+```css title="src/app/home/home.css"
+#container {
+ text-align: center;
+
+ position: absolute;
+ left: 0;
+ right: 0;
+ top: 50%;
+ transform: translateY(-50%);
+}
+
+#container strong {
+ font-size: 20px;
+ line-height: 26px;
+}
+
+#container p {
+ font-size: 16px;
+ line-height: 22px;
+
+ color: #8c8c8c;
+
+ margin: 0;
+}
+
+#container a {
+ text-decoration: none;
+}
+```
+
+#### 5. Set up Routing
+
+Update `src/app/app.routes.ts` to add a `home` route:
+
+```ts title="src/app/app.routes.ts"
+import { Routes } from '@angular/router';
+import { HomePage } from './home/home';
+
+export const routes: Routes = [
+ {
+ path: '',
+ redirectTo: 'home',
+ pathMatch: 'full',
+ },
+ {
+ path: 'home',
+ component: HomePage,
+ },
+];
+```
+
+You're all set! Your Ionic Angular app is now configured with full Ionic page support. Run `ng serve` to start your development server and view your app.
+
+## Next Steps
+
+Now that you have Ionic Angular integrated into your project, check out:
+
+
+
+
+
Discover how to handle routing and navigation in Ionic Angular apps using the Angular Router.
+
+
+
+
Explore Ionic's rich library of UI components for building beautiful apps.
+
+
+
+
Learn how to customize the look and feel of your app with Ionic's powerful theming system.
+
+
+
+
Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.
+
+
+
diff --git a/sidebars.js b/sidebars.js
index b48905e10e7..107aad37965 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -83,6 +83,7 @@ module.exports = {
'angular/your-first-app/distribute',
],
},
+ 'angular/add-to-existing',
'angular/build-options',
'angular/lifecycle',
'angular/navigation',
From 230ec4cf5bbd2b15c0cf9a864fc1fce0a5164d61 Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Wed, 12 Nov 2025 11:03:43 -0500
Subject: [PATCH 07/14] docs(vue): add a guide for adding to existing projects
---
docs/vue/add-to-existing.md | 339 ++++++++++++++++++++++++++++++++++++
sidebars.js | 1 +
2 files changed, 340 insertions(+)
create mode 100644 docs/vue/add-to-existing.md
diff --git a/docs/vue/add-to-existing.md b/docs/vue/add-to-existing.md
new file mode 100644
index 00000000000..73e62f3cfd8
--- /dev/null
+++ b/docs/vue/add-to-existing.md
@@ -0,0 +1,339 @@
+---
+title: Add to Existing Vue Project
+sidebar_label: Add to Existing
+---
+
+import DocsCard from '@components/global/DocsCard';
+import DocsCards from '@components/global/DocsCards';
+
+
+ Add Ionic Vue to Existing Project: Integration Guide
+
+
+
+This guide covers how to add Ionic Vue to an existing Vue project. If you're looking to start a new project from scratch, check out the [Ionic Vue Quickstart](/docs/vue/quickstart.md) guide. For an overview of how Ionic Vue works with Vue, including version support and tooling, check out the [Ionic Vue Overview](/docs/vue/overview.md).
+
+:::tip
+
+This guide uses JavaScript examples. If you're using TypeScript, the setup process is the same, but you'll use `.ts` file extensions instead of `.js`.
+
+:::
+
+## Setup
+
+Follow these steps to add Ionic Vue to your existing Vue project:
+
+#### 1. Install the Packages
+
+```bash
+npm install @ionic/vue @ionic/vue-router vue-router
+```
+
+#### 2. Configure Ionic Vue
+
+Update `src/main.js` to include `IonicVue` and import the required Ionic Framework stylesheets:
+
+```javascript title="src/main.js"
+import { createApp } from 'vue';
+import { IonicVue } from '@ionic/vue';
+
+import App from './App.vue';
+
+/* Core CSS required for Ionic components to work properly */
+import '@ionic/vue/css/core.css';
+
+/* Basic CSS for apps built with Ionic */
+import '@ionic/vue/css/normalize.css';
+import '@ionic/vue/css/structure.css';
+import '@ionic/vue/css/typography.css';
+
+createApp(App).use(IonicVue).mount('#app');
+```
+
+These stylesheets are required for Ionic Framework components to render properly.
+
+## Using Individual Components
+
+After completing the setup above, you can start using Ionic components in your existing Vue app. Here's an example of how to use them:
+
+Update `src/App.vue` to the following:
+
+```vue title="src/App.vue"
+
+ Button
+
+
+
+
+```
+
+Visit the [components](/docs/components.md) page for all of the available Ionic components.
+
+## Using Ionic Pages
+
+If you want to use Ionic pages with full navigation and page transitions, follow these additional setup steps.
+
+#### 1. Add Additional Ionic Framework Stylesheets
+
+Update the imported stylesheets in `src/main.js`:
+
+```javascript title="src/main.js"
+/* Core CSS required for Ionic components to work properly */
+import '@ionic/vue/css/core.css';
+
+/* Basic CSS for apps built with Ionic */
+import '@ionic/vue/css/normalize.css';
+import '@ionic/vue/css/structure.css';
+import '@ionic/vue/css/typography.css';
+
+/* Optional CSS utils that can be commented out */
+import '@ionic/vue/css/padding.css';
+import '@ionic/vue/css/float-elements.css';
+import '@ionic/vue/css/text-alignment.css';
+import '@ionic/vue/css/text-transformation.css';
+import '@ionic/vue/css/flex-utils.css';
+import '@ionic/vue/css/display.css';
+```
+
+These stylesheets set up the overall page structure and provide [CSS utilities](/docs/layout/css-utilities.md) for faster development. Some stylesheets are optional. For details on which stylesheets are required, check out [Global Stylesheets](/docs/layout/global-stylesheets.md).
+
+#### 2. Set up Theming
+
+Create a `src/theme/variables.css` file with the following content:
+
+```css title="src/theme/variables.css"
+/* For information on how to create your own theme, please refer to:
+http://ionicframework.com/docs/theming/ */
+```
+
+Then, import the file and the dark palette stylesheet in `src/main.js`:
+
+```javascript title="src/main.js"
+import { createApp } from 'vue';
+import App from './App.vue';
+
+import { IonicVue } from '@ionic/vue';
+
+/* Core CSS required for Ionic components to work properly */
+import '@ionic/vue/css/core.css';
+
+/* Basic CSS for apps built with Ionic */
+import '@ionic/vue/css/normalize.css';
+import '@ionic/vue/css/structure.css';
+import '@ionic/vue/css/typography.css';
+
+/* Optional CSS utils that can be commented out */
+import '@ionic/vue/css/padding.css';
+import '@ionic/vue/css/float-elements.css';
+import '@ionic/vue/css/text-alignment.css';
+import '@ionic/vue/css/text-transformation.css';
+import '@ionic/vue/css/flex-utils.css';
+import '@ionic/vue/css/display.css';
+
+/**
+ * Ionic Dark Mode
+ * -----------------------------------------------------
+ * For more info, please refer to:
+ * https://ionicframework.com/docs/theming/dark-mode
+ */
+
+/* @import '@ionic/vue/css/palettes/dark.always.css'; */
+/* @import '@ionic/vue/css/palettes/dark.class.css'; */
+import '@ionic/vue/css/palettes/dark.system.css';
+
+/* Theme variables */
+import './theme/variables.css';
+
+createApp(App).use(IonicVue).mount('#app');
+```
+
+The `variables.css` file can be used to create custom Ionic Framework themes. The `dark.system.css` import enables [dark mode support](/docs/theming/dark-mode.md) for your Ionic app when the system is set to prefer a dark appearance. You can customize the theming behavior by uncommenting different dark palette imports or adding custom CSS variables to `theme/variables.css`.
+
+#### 3. Update the App Component
+
+Update `src/App.vue` to the following:
+
+```vue title="src/App.vue"
+
+
+
+
+
+
+
+```
+
+#### 4. Create a Home Page
+
+Create a new file at `src/views/HomePage.vue` with the following:
+
+```vue title="src/views/HomePage.vue"
+
+
+
+
+ Home
+
+
+
+
+
+
+ Home
+
+
+
+
+
+
+
+
+
+
+
+```
+
+#### 5. Set up Routing
+
+Add a file at `src/router/index.js` defining the routes:
+
+```javascript title="src/router/index.js"
+import { createRouter, createWebHistory } from '@ionic/vue-router';
+import HomePage from '../views/HomePage.vue';
+
+const routes = [
+ {
+ path: '/',
+ redirect: '/home',
+ },
+ {
+ path: '/home',
+ name: 'Home',
+ component: HomePage,
+ },
+];
+
+const router = createRouter({
+ history: createWebHistory(import.meta.env.BASE_URL),
+ routes,
+});
+
+export default router;
+```
+
+Update `src/main.js` to include the router:
+
+```javascript title="src/main.js"
+import { createApp } from 'vue';
+import App from './App.vue';
+import router from './router';
+
+import { IonicVue } from '@ionic/vue';
+
+/* Core CSS required for Ionic components to work properly */
+import '@ionic/vue/css/core.css';
+
+/* Basic CSS for apps built with Ionic */
+import '@ionic/vue/css/normalize.css';
+import '@ionic/vue/css/structure.css';
+import '@ionic/vue/css/typography.css';
+
+/* Optional CSS utils that can be commented out */
+import '@ionic/vue/css/padding.css';
+import '@ionic/vue/css/float-elements.css';
+import '@ionic/vue/css/text-alignment.css';
+import '@ionic/vue/css/text-transformation.css';
+import '@ionic/vue/css/flex-utils.css';
+import '@ionic/vue/css/display.css';
+
+/**
+ * Ionic Dark Mode
+ * -----------------------------------------------------
+ * For more info, please refer to:
+ * https://ionicframework.com/docs/theming/dark-mode
+ */
+
+/* @import '@ionic/vue/css/palettes/dark.always.css'; */
+/* @import '@ionic/vue/css/palettes/dark.class.css'; */
+import '@ionic/vue/css/palettes/dark.system.css';
+
+/* Theme variables */
+import './theme/variables.css';
+
+const app = createApp(App).use(IonicVue).use(router);
+
+router.isReady().then(() => {
+ app.mount('#app');
+});
+```
+
+You're all set! Your Ionic Vue app is now configured with full Ionic page support. Run `npm run dev` to start your development server and view your app.
+
+## Next Steps
+
+Now that you have Ionic Vue integrated into your project, check out:
+
+
+
+
+
Discover how to handle routing and navigation in Ionic Vue apps using the Vue Router.
+
+
+
+
Explore Ionic's rich library of UI components for building beautiful apps.
+
+
+
+
Learn how to customize the look and feel of your app with Ionic's powerful theming system.
+
+
+
+
Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.
+
+
+
diff --git a/sidebars.js b/sidebars.js
index 107aad37965..d8cacb17545 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -174,6 +174,7 @@ module.exports = {
'vue/your-first-app/distribute',
],
},
+ 'vue/add-to-existing',
'vue/build-options',
'vue/lifecycle',
'vue/navigation',
From b1b8266e95c9248253ba5514aa6226f632cd6368 Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Wed, 12 Nov 2025 12:23:16 -0500
Subject: [PATCH 08/14] docs(react): update guide for adding to existing
projects
---
docs/react/add-to-existing.md | 357 ++++++++++++++----
.../version-v7/react/add-to-existing.md | 355 +++++++++++++----
2 files changed, 557 insertions(+), 155 deletions(-)
diff --git a/docs/react/add-to-existing.md b/docs/react/add-to-existing.md
index 8f975e5b736..8185765b996 100644
--- a/docs/react/add-to-existing.md
+++ b/docs/react/add-to-existing.md
@@ -1,8 +1,11 @@
---
-title: Add to Existing React App
-sidebar_label: Add to Existing React App
+title: Add to Existing React Project
+sidebar_label: Add to Existing
---
+import DocsCard from '@components/global/DocsCard';
+import DocsCards from '@components/global/DocsCards';
+
Add Ionic React to Existing Project: Integration Guide
-This guide covers how to add Ionic React to an existing React project.
+This guide covers how to add Ionic React to an existing React project. If you're looking to start a new project from scratch, check out the [Ionic React Quickstart](/docs/react/quickstart.md) guide. For an overview of how Ionic React works with React, including version support and tooling, check out the [Ionic React Overview](/docs/react/overview.md).
+
+:::tip
+
+This guide uses TypeScript examples. If you're using JavaScript, the setup process is the same, but you'll use `.jsx` file extensions instead of `.tsx`.
+
+:::
-### Using Individual Ionic Components
+## Setup
-Ionic React has around 100 components that you can begin using in your app immediately to help make it more mobile-friendly.
+Follow these steps to add Ionic React to your existing React project:
-To get started with using components install the `@ionic/react` package:
+#### 1. Install the Package
```bash
-npm i @ionic/react
+npm install @ionic/react
```
-Import the stylesheets from Ionic in your main app file:
+#### 2. Configure Ionic React
+
+Update `src/App.tsx` to include `setupIonicReact` and import the required Ionic Framework stylesheets:
-```tsx title="App.tsx"
+```tsx title="src/App.tsx"
+// ...existing imports...
+
+import { setupIonicReact } from '@ionic/react';
+
+/* Core CSS required for Ionic components to work properly */
import '@ionic/react/css/core.css';
+
+/* Basic CSS for apps built with Ionic */
+import '@ionic/react/css/normalize.css';
+import '@ionic/react/css/structure.css';
+import '@ionic/react/css/typography.css';
+
+setupIonicReact();
+
+// ...existing app function and export...
```
-Add the `setupIonicReact` function to your app:
+These stylesheets are required for Ionic Framework components to render properly. `setupIonicReact` is a function that sets up the Ionic React components to work with your app. It is required to be called before using any of the Ionic React components.
-```tsx title="App.tsx"
-import { setupIonicReact } from '@ionic/react';
+## Using Individual Components
+
+After completing the setup above, you can start using Ionic components in your existing React app. Here's an example of how to use them:
+
+Update `src/App.tsx` to the following:
+
+```tsx title="src/App.tsx"
+import { IonButton, IonDatetime, setupIonicReact } from '@ionic/react';
+import './App.css';
+
+/* Core CSS required for Ionic components to work properly */
+import '@ionic/react/css/core.css';
+
+/* Basic CSS for apps built with Ionic */
+import '@ionic/react/css/normalize.css';
+import '@ionic/react/css/structure.css';
+import '@ionic/react/css/typography.css';
setupIonicReact();
-const App = () => {
- return (
- ...
- );
-}
+const App: React.FC = () => (
+ <>
+ Button
+
+
+);
export default App;
```
-:::note
+Visit the [components](/docs/components.md) page for all of the available Ionic components.
-`setupIonicReact` is a function that will set up the Ionic React components to work with your app. It is required to be called before using any of the Ionic React components.
+:::tip
-:::
+If your existing React app imports a global stylesheet (such as `index.css`) in `src/main.tsx`, you may want to remove it or update any styles that conflict with Ionic Framework components. Ionic Framework includes its own CSS reset and normalization, which may conflict with existing global styles.
-You can import any of the components and begin to use them right away. Here we are importing the `IonButton` and `IonDatetime` components and using them anywhere in our app:
+:::
-```tsx
-import React from 'react';
-import { IonButton, IonDatetime } from '@ionic/react';
+## Using Ionic Pages
-const MyComponent = () => {
- return (
- <>
-
- Start
-
- );
-};
-```
+If you want to use Ionic pages with full navigation and page transitions, follow these additional setup steps.
-### Using Ionic Pages
+#### 1. Add Additional Ionic Framework Stylesheets
-If you want to convert part of your app and give it the whole Ionic experience, there are a few additional steps to take to get this setup.
+Update the imported stylesheets in `src/App.tsx`:
-First, import some additional CSS files that help set up the overall structure of the page and some utility helpers:
+```tsx title="src/App.tsx"
+/* Core CSS required for Ionic components to work properly */
+import '@ionic/react/css/core.css';
-```js
/* Basic CSS for apps built with Ionic */
import '@ionic/react/css/normalize.css';
import '@ionic/react/css/structure.css';
@@ -88,70 +120,239 @@ import '@ionic/react/css/flex-utils.css';
import '@ionic/react/css/display.css';
```
-If you are using another CSS framework (like Bootstrap), you might want to isolate the Ionic pages away from them. This will help to ensure there aren't any CSS conflicts between the libraries.
+These stylesheets set up the overall page structure and provide [CSS utilities](/docs/layout/css-utilities.md) for faster development. Some stylesheets are optional. For details on which stylesheets are required, check out [Global Stylesheets](/docs/layout/global-stylesheets.md).
-Next, install the `@ionic/react-router` library:
+#### 2. Set up Theming
-```bash
-npm i @ionic/react-router
+Create a `src/theme/variables.css` file with the following content:
+
+```css title="src/theme/variables.css"
+/* For information on how to create your own theme, please refer to:
+http://ionicframework.com/docs/theming/ */
```
-The Ionic React Router library is a small wrapper around the popular React Router library and helps provide the functionality we need for native-like page transitions. The Ionic React Router library is compatible with v5 of React Router.
+Then, import the file and the dark palette stylesheet in `src/App.tsx`:
+
+```tsx title="src/App.tsx"
+// ...existing imports...
-The main Ionic page will need a couple of base components. First, use a `IonApp` component (from `@ionic/react`) as the root component, and then use `IonReactRouter` (from `@ionic/react-router`).
+// ...existing stylesheets...
-`IonApp` sets up our main container, with the necessary styling needed for our structural components. `IonReactRouter` is a small wrapper for React Routers `BrowserRouter` and should be used in its place.
+/**
+ * Ionic Dark Mode
+ * -----------------------------------------------------
+ * For more info, please refer to:
+ * https://ionicframework.com/docs/theming/dark-mode
+ */
-Then, wrap all your routes in an `IonRouterOutlet`, which is what manages our Ionic pages.
+/* @import '@ionic/react/css/palettes/dark.always.css'; */
+/* @import '@ionic/react/css/palettes/dark.class.css'; */
+import '@ionic/react/css/palettes/dark.system.css';
-```tsx
-import { IonApp, IonRouterOutlet } from '@ionic/react';
+/* Theme variables */
+import './theme/variables.css';
+
+setupIonicReact();
+
+// ...existing app function and export...
+```
+
+The `variables.css` file can be used to create custom Ionic Framework themes. The `dark.system.css` import enables [dark mode support](/docs/theming/dark-mode.md) for your Ionic app when the system is set to prefer a dark appearance. You can customize the theming behavior by uncommenting different dark palette imports or adding custom CSS variables to `theme/variables.css`.
+
+#### 3. Update the App Component
+
+Update `src/App.tsx` to the following:
+
+```tsx title="src/App.tsx"
+import { IonApp, IonRouterOutlet, setupIonicReact } from '@ionic/react';
import { IonReactRouter } from '@ionic/react-router';
-...
+/* Core CSS required for Ionic components to work properly */
+import '@ionic/react/css/core.css';
+
+/* Basic CSS for apps built with Ionic */
+import '@ionic/react/css/normalize.css';
+import '@ionic/react/css/structure.css';
+import '@ionic/react/css/typography.css';
+
+/* Optional CSS utils that can be commented out */
+import '@ionic/react/css/padding.css';
+import '@ionic/react/css/float-elements.css';
+import '@ionic/react/css/text-alignment.css';
+import '@ionic/react/css/text-transformation.css';
+import '@ionic/react/css/flex-utils.css';
+import '@ionic/react/css/display.css';
-
-
-
-
-
-
-
-
+/**
+ * Ionic Dark Mode
+ * -----------------------------------------------------
+ * For more info, please refer to:
+ * https://ionicframework.com/docs/theming/dark-mode
+ */
+
+/* @import '@ionic/react/css/palettes/dark.always.css'; */
+/* @import '@ionic/react/css/palettes/dark.class.css'; */
+import '@ionic/react/css/palettes/dark.system.css';
+
+/* Theme variables */
+import './theme/variables.css';
+
+setupIonicReact();
+
+const App = () => {
+ return (
+
+
+ {/* Routes will be added here */}
+
+
+ );
+};
+
+export default App;
```
-Now you can setup Ionic pages like so:
+#### 4. Create a Home Page
-```tsx
-
-
-
- My Page
-
-
-
-
- Start
-
-
+Create a new file at `src/pages/Home.tsx` with the following:
+
+```tsx title="src/pages/Home.tsx"
+import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/react';
+
+import './Home.css';
+
+const Home = () => {
+ return (
+
+
+
+ Home
+
+
+
+
+
+
+ Home
+
+
+
+
+
+
+ );
+};
+
+export default Home;
```
-:::note
+Then, create `src/pages/Home.css`:
+
+```css title="src/pages/Home.css"
+#container {
+ text-align: center;
-`IonPage` is important to have as the base component for your "Ionic" pages. `IonPage` is the element Ionic performs page transitions on.
+ position: absolute;
+ left: 0;
+ right: 0;
+ top: 50%;
+ transform: translateY(-50%);
+}
+
+#container strong {
+ font-size: 20px;
+ line-height: 26px;
+}
+
+#container p {
+ font-size: 16px;
+ line-height: 22px;
+
+ color: #8c8c8c;
+
+ margin: 0;
+}
+
+#container a {
+ text-decoration: none;
+}
+```
+
+#### 5. Set up Routing
+
+:::important
+
+Ionic React Router currently only supports React Router v5. You must install the following specific versions of the router packages to set up routing with Ionic React.
:::
-For more information on routing and navigation in Ionic React, see [here](/docs/react/navigation).
+Install the router packages:
+
+```bash
+npm install @ionic/react-router react-router@5 react-router-dom@5
+npm install @types/react-router-dom --save-dev
+```
+
+Then, update `src/App.tsx` to add the routes for the Home page:
+
+```tsx title="src/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';
+
+// ...existing Ionic Framework stylesheet imports...
+
+setupIonicReact();
+
+const App: React.FC = () => (
+
+
+
+
+
+
+
+
+
+
+
+
+);
+
+export default App;
+```
+
+You're all set! Your Ionic React app is now configured with full Ionic page support. Run `npm run dev` to start your development server and view your app.
+
+## Next Steps
+
+Now that you have Ionic React integrated into your project, check out:
-### Customize the Theme
+
-To customize the look and feel of the components, Ionic has CSS variables you can [override](https://ionicframework.com/docs/theming/colors#modifying-colors) to provide a theme for your components. Set these in your main CSS file.
+
+
Discover how to handle routing and navigation in Ionic React apps using the React Router.
+
-For more info on theming your Ionic app, see the guide [here](/docs/theming/themes).
+
+
Explore Ionic's rich library of UI components for building beautiful apps.
+
-### Wrapping up
+
+
Learn how to customize the look and feel of your app with Ionic's powerful theming system.
+
-Adding Ionic React to an existing React project is fairly simple and can be done in just a few minutes.
+
+
Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.
+
-The great thing about using individual components from Ionic React is that you only import the component you need. This makes Ionic React ideal for adding it to existing projects that need to look and work great on mobile devices.
+
diff --git a/versioned_docs/version-v7/react/add-to-existing.md b/versioned_docs/version-v7/react/add-to-existing.md
index e658a410697..8185765b996 100644
--- a/versioned_docs/version-v7/react/add-to-existing.md
+++ b/versioned_docs/version-v7/react/add-to-existing.md
@@ -1,8 +1,11 @@
---
-title: Add to Existing
+title: Add to Existing React Project
sidebar_label: Add to Existing
---
+import DocsCard from '@components/global/DocsCard';
+import DocsCards from '@components/global/DocsCards';
+
Add Ionic React to Existing Project: Integration Guide
-This guide covers how to add Ionic React to an existing React project.
+This guide covers how to add Ionic React to an existing React project. If you're looking to start a new project from scratch, check out the [Ionic React Quickstart](/docs/react/quickstart.md) guide. For an overview of how Ionic React works with React, including version support and tooling, check out the [Ionic React Overview](/docs/react/overview.md).
+
+:::tip
+
+This guide uses TypeScript examples. If you're using JavaScript, the setup process is the same, but you'll use `.jsx` file extensions instead of `.tsx`.
+
+:::
-### Using Individual Ionic Components
+## Setup
-Ionic React has around 100 components that you can begin using in your app immediately to help make it more mobile-friendly.
+Follow these steps to add Ionic React to your existing React project:
-To get started with using components install the `@ionic/react` package:
+#### 1. Install the Package
```bash
-npm i @ionic/react
+npm install @ionic/react
```
-Import the stylesheets from Ionic in your main app file:
+#### 2. Configure Ionic React
+
+Update `src/App.tsx` to include `setupIonicReact` and import the required Ionic Framework stylesheets:
-```tsx title="App.tsx"
+```tsx title="src/App.tsx"
+// ...existing imports...
+
+import { setupIonicReact } from '@ionic/react';
+
+/* Core CSS required for Ionic components to work properly */
import '@ionic/react/css/core.css';
+
+/* Basic CSS for apps built with Ionic */
+import '@ionic/react/css/normalize.css';
+import '@ionic/react/css/structure.css';
+import '@ionic/react/css/typography.css';
+
+setupIonicReact();
+
+// ...existing app function and export...
```
-Add the `setupIonicReact` function to your app:
+These stylesheets are required for Ionic Framework components to render properly. `setupIonicReact` is a function that sets up the Ionic React components to work with your app. It is required to be called before using any of the Ionic React components.
-```tsx title="App.tsx"
-import { setupIonicReact } from '@ionic/react';
+## Using Individual Components
+
+After completing the setup above, you can start using Ionic components in your existing React app. Here's an example of how to use them:
+
+Update `src/App.tsx` to the following:
+
+```tsx title="src/App.tsx"
+import { IonButton, IonDatetime, setupIonicReact } from '@ionic/react';
+import './App.css';
+
+/* Core CSS required for Ionic components to work properly */
+import '@ionic/react/css/core.css';
+
+/* Basic CSS for apps built with Ionic */
+import '@ionic/react/css/normalize.css';
+import '@ionic/react/css/structure.css';
+import '@ionic/react/css/typography.css';
setupIonicReact();
-const App = () => {
- return (
- ...
- );
-}
+const App: React.FC = () => (
+ <>
+ Button
+
+
+);
export default App;
```
-:::note
+Visit the [components](/docs/components.md) page for all of the available Ionic components.
-`setupIonicReact` is a function that will set up the Ionic React components to work with your app. It is required to be called before using any of the Ionic React components.
+:::tip
-:::
+If your existing React app imports a global stylesheet (such as `index.css`) in `src/main.tsx`, you may want to remove it or update any styles that conflict with Ionic Framework components. Ionic Framework includes its own CSS reset and normalization, which may conflict with existing global styles.
-You can import any of the components and begin to use them right away. Here we are importing the `IonButton` and `IonDatetime` components and using them anywhere in our app:
+:::
-```tsx
-import React from 'react';
-import { IonButton, IonDatetime } from '@ionic/react';
+## Using Ionic Pages
-const MyComponent = () => {
- return (
- <>
-
- Start
-
- );
-};
-```
+If you want to use Ionic pages with full navigation and page transitions, follow these additional setup steps.
-### Using Ionic Pages
+#### 1. Add Additional Ionic Framework Stylesheets
-If you want to convert part of your app and give it the whole Ionic experience, there are a few additional steps to take to get this setup.
+Update the imported stylesheets in `src/App.tsx`:
-First, import some additional CSS files that help set up the overall structure of the page and some utility helpers:
+```tsx title="src/App.tsx"
+/* Core CSS required for Ionic components to work properly */
+import '@ionic/react/css/core.css';
-```js
/* Basic CSS for apps built with Ionic */
import '@ionic/react/css/normalize.css';
import '@ionic/react/css/structure.css';
@@ -88,70 +120,239 @@ import '@ionic/react/css/flex-utils.css';
import '@ionic/react/css/display.css';
```
-If you are using another CSS framework (like Bootstrap), you might want to isolate the Ionic pages away from them. This will help to ensure there aren't any CSS conflicts between the libraries.
+These stylesheets set up the overall page structure and provide [CSS utilities](/docs/layout/css-utilities.md) for faster development. Some stylesheets are optional. For details on which stylesheets are required, check out [Global Stylesheets](/docs/layout/global-stylesheets.md).
-Next, install the `@ionic/react-router` library:
+#### 2. Set up Theming
-```bash
-npm i @ionic/react-router
+Create a `src/theme/variables.css` file with the following content:
+
+```css title="src/theme/variables.css"
+/* For information on how to create your own theme, please refer to:
+http://ionicframework.com/docs/theming/ */
```
-The Ionic React Router library is a small wrapper around the popular React Router library and helps provide the functionality we need for native-like page transitions. The Ionic React Router library is compatible with v5 of React Router.
+Then, import the file and the dark palette stylesheet in `src/App.tsx`:
+
+```tsx title="src/App.tsx"
+// ...existing imports...
-The main Ionic page will need a couple of base components. First, use a `IonApp` component (from `@ionic/react`) as the root component, and then use `IonReactRouter` (from `@ionic/react-router`).
+// ...existing stylesheets...
-`IonApp` sets up our main container, with the necessary styling needed for our structural components. `IonReactRouter` is a small wrapper for React Routers `BrowserRouter` and should be used in its place.
+/**
+ * Ionic Dark Mode
+ * -----------------------------------------------------
+ * For more info, please refer to:
+ * https://ionicframework.com/docs/theming/dark-mode
+ */
-Then, wrap all your routes in an `IonRouterOutlet`, which is what manages our Ionic pages.
+/* @import '@ionic/react/css/palettes/dark.always.css'; */
+/* @import '@ionic/react/css/palettes/dark.class.css'; */
+import '@ionic/react/css/palettes/dark.system.css';
-```tsx
-import { IonApp, IonRouterOutlet } from '@ionic/react';
+/* Theme variables */
+import './theme/variables.css';
+
+setupIonicReact();
+
+// ...existing app function and export...
+```
+
+The `variables.css` file can be used to create custom Ionic Framework themes. The `dark.system.css` import enables [dark mode support](/docs/theming/dark-mode.md) for your Ionic app when the system is set to prefer a dark appearance. You can customize the theming behavior by uncommenting different dark palette imports or adding custom CSS variables to `theme/variables.css`.
+
+#### 3. Update the App Component
+
+Update `src/App.tsx` to the following:
+
+```tsx title="src/App.tsx"
+import { IonApp, IonRouterOutlet, setupIonicReact } from '@ionic/react';
import { IonReactRouter } from '@ionic/react-router';
-...
+/* Core CSS required for Ionic components to work properly */
+import '@ionic/react/css/core.css';
+
+/* Basic CSS for apps built with Ionic */
+import '@ionic/react/css/normalize.css';
+import '@ionic/react/css/structure.css';
+import '@ionic/react/css/typography.css';
+
+/* Optional CSS utils that can be commented out */
+import '@ionic/react/css/padding.css';
+import '@ionic/react/css/float-elements.css';
+import '@ionic/react/css/text-alignment.css';
+import '@ionic/react/css/text-transformation.css';
+import '@ionic/react/css/flex-utils.css';
+import '@ionic/react/css/display.css';
-
-
-
-
-
-
-
-
+/**
+ * Ionic Dark Mode
+ * -----------------------------------------------------
+ * For more info, please refer to:
+ * https://ionicframework.com/docs/theming/dark-mode
+ */
+
+/* @import '@ionic/react/css/palettes/dark.always.css'; */
+/* @import '@ionic/react/css/palettes/dark.class.css'; */
+import '@ionic/react/css/palettes/dark.system.css';
+
+/* Theme variables */
+import './theme/variables.css';
+
+setupIonicReact();
+
+const App = () => {
+ return (
+
+
+ {/* Routes will be added here */}
+
+
+ );
+};
+
+export default App;
```
-Now you can setup Ionic pages like so:
+#### 4. Create a Home Page
-```tsx
-
-
-
- My Page
-
-
-
-
- Start
-
-
+Create a new file at `src/pages/Home.tsx` with the following:
+
+```tsx title="src/pages/Home.tsx"
+import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/react';
+
+import './Home.css';
+
+const Home = () => {
+ return (
+
+
+
+ Home
+
+
+
+
+
+
+ Home
+
+
+
+
+
+
+ );
+};
+
+export default Home;
```
-:::note
+Then, create `src/pages/Home.css`:
+
+```css title="src/pages/Home.css"
+#container {
+ text-align: center;
-`IonPage` is important to have as the base component for your "Ionic" pages. `IonPage` is the element Ionic performs page transitions on.
+ position: absolute;
+ left: 0;
+ right: 0;
+ top: 50%;
+ transform: translateY(-50%);
+}
+
+#container strong {
+ font-size: 20px;
+ line-height: 26px;
+}
+
+#container p {
+ font-size: 16px;
+ line-height: 22px;
+
+ color: #8c8c8c;
+
+ margin: 0;
+}
+
+#container a {
+ text-decoration: none;
+}
+```
+
+#### 5. Set up Routing
+
+:::important
+
+Ionic React Router currently only supports React Router v5. You must install the following specific versions of the router packages to set up routing with Ionic React.
:::
-For more information on routing and navigation in Ionic React, see [here](/docs/react/navigation).
+Install the router packages:
+
+```bash
+npm install @ionic/react-router react-router@5 react-router-dom@5
+npm install @types/react-router-dom --save-dev
+```
+
+Then, update `src/App.tsx` to add the routes for the Home page:
+
+```tsx title="src/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';
+
+// ...existing Ionic Framework stylesheet imports...
+
+setupIonicReact();
+
+const App: React.FC = () => (
+
+
+
+
+
+
+
+
+
+
+
+
+);
+
+export default App;
+```
+
+You're all set! Your Ionic React app is now configured with full Ionic page support. Run `npm run dev` to start your development server and view your app.
+
+## Next Steps
+
+Now that you have Ionic React integrated into your project, check out:
-### Customize the Theme
+
-To customize the look and feel of the components, Ionic has CSS variables you can [override](https://ionicframework.com/docs/theming/colors#modifying-colors) to provide a theme for your components. Set these in your main CSS file.
+
+
Discover how to handle routing and navigation in Ionic React apps using the React Router.
+
-For more info on theming your Ionic app, see the guide [here](/docs/theming/themes).
+
+
Explore Ionic's rich library of UI components for building beautiful apps.
+
-### Wrapping up
+
+
Learn how to customize the look and feel of your app with Ionic's powerful theming system.
+
-Adding Ionic React to an existing React project is fairly simple and can be done in just a few minutes.
+
+
Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.
+
-The great thing about using individual components from Ionic React is that you only import the component you need. This makes Ionic React ideal for adding it to existing projects that need to look and work great on mobile devices.
+
From cd0f369015d855489181f9d14482b7b5618294c8 Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Thu, 13 Nov 2025 16:58:31 -0500
Subject: [PATCH 09/14] style: add comment for css usage
---
src/components/global/DocsCards/cards.css | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/src/components/global/DocsCards/cards.css b/src/components/global/DocsCards/cards.css
index b77622963f7..760d7c90465 100644
--- a/src/components/global/DocsCards/cards.css
+++ b/src/components/global/DocsCards/cards.css
@@ -5,6 +5,12 @@ docs-cards {
gap: 1.35rem;
}
+/*
+ * This prevents a single card from stretching the full width by
+ * forcing a 2-column grid layout (a single card will only take up
+ * 1 column instead of stretching across both). This is used on the
+ * Packages & CDN page by the JavaScript section.
+ */
docs-cards:has(docs-card:only-child) {
grid-template-columns: 1fr 1fr;
}
From 161fe5a0f3c67da8539ad304305af978a83ec544 Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Thu, 13 Nov 2025 17:13:57 -0500
Subject: [PATCH 10/14] docs(add-to-existing): note that some stylesheets are
only recommended
---
docs/angular/add-to-existing.md | 6 +++++-
docs/react/add-to-existing.md | 8 +++++++-
docs/vue/add-to-existing.md | 6 +++++-
versioned_docs/version-v7/react/add-to-existing.md | 8 +++++++-
4 files changed, 24 insertions(+), 4 deletions(-)
diff --git a/docs/angular/add-to-existing.md b/docs/angular/add-to-existing.md
index 6d9ae4cba95..58c3250a8fe 100644
--- a/docs/angular/add-to-existing.md
+++ b/docs/angular/add-to-existing.md
@@ -68,7 +68,11 @@ Replace the existing `styles` array in `angular.json` with the following:
]
```
-These stylesheets are required for Ionic Framework components to render properly.
+:::info
+
+While `core.css` is required, `normalize.css`, `structure.css`, and `typography.css` are recommended but not required. They normalize cross-browser differences, ensure proper scrolling behavior, and provide consistent typography and form styling. Without them, you may need to handle these concerns yourself. For more details, see [Global Stylesheets](/docs/layout/global-stylesheets.md).
+
+:::
#### 3. Configure Ionic Angular
diff --git a/docs/react/add-to-existing.md b/docs/react/add-to-existing.md
index 8185765b996..676b26ff286 100644
--- a/docs/react/add-to-existing.md
+++ b/docs/react/add-to-existing.md
@@ -54,7 +54,13 @@ setupIonicReact();
// ...existing app function and export...
```
-These stylesheets are required for Ionic Framework components to render properly. `setupIonicReact` is a function that sets up the Ionic React components to work with your app. It is required to be called before using any of the Ionic React components.
+`setupIonicReact` is a function that sets up the Ionic React components to work with your app. It is required to be called before using any of the Ionic React components.
+
+:::info
+
+While `core.css` is required, `normalize.css`, `structure.css`, and `typography.css` are recommended but not required. They normalize cross-browser differences, ensure proper scrolling behavior, and provide consistent typography and form styling. Without them, you may need to handle these concerns yourself. For more details, see [Global Stylesheets](/docs/layout/global-stylesheets.md).
+
+:::
## Using Individual Components
diff --git a/docs/vue/add-to-existing.md b/docs/vue/add-to-existing.md
index 73e62f3cfd8..6d9084525e5 100644
--- a/docs/vue/add-to-existing.md
+++ b/docs/vue/add-to-existing.md
@@ -53,7 +53,11 @@ import '@ionic/vue/css/typography.css';
createApp(App).use(IonicVue).mount('#app');
```
-These stylesheets are required for Ionic Framework components to render properly.
+:::info
+
+While `core.css` is required, `normalize.css`, `structure.css`, and `typography.css` are recommended but not required. They normalize cross-browser differences, ensure proper scrolling behavior, and provide consistent typography and form styling. Without them, you may need to handle these concerns yourself. For more details, see [Global Stylesheets](/docs/layout/global-stylesheets.md).
+
+:::
## Using Individual Components
diff --git a/versioned_docs/version-v7/react/add-to-existing.md b/versioned_docs/version-v7/react/add-to-existing.md
index 8185765b996..676b26ff286 100644
--- a/versioned_docs/version-v7/react/add-to-existing.md
+++ b/versioned_docs/version-v7/react/add-to-existing.md
@@ -54,7 +54,13 @@ setupIonicReact();
// ...existing app function and export...
```
-These stylesheets are required for Ionic Framework components to render properly. `setupIonicReact` is a function that sets up the Ionic React components to work with your app. It is required to be called before using any of the Ionic React components.
+`setupIonicReact` is a function that sets up the Ionic React components to work with your app. It is required to be called before using any of the Ionic React components.
+
+:::info
+
+While `core.css` is required, `normalize.css`, `structure.css`, and `typography.css` are recommended but not required. They normalize cross-browser differences, ensure proper scrolling behavior, and provide consistent typography and form styling. Without them, you may need to handle these concerns yourself. For more details, see [Global Stylesheets](/docs/layout/global-stylesheets.md).
+
+:::
## Using Individual Components
From 732041beb5bbc998ef2acce2e0d5f94a85cdb259 Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Thu, 13 Nov 2025 17:24:57 -0500
Subject: [PATCH 11/14] docs(add-to-existing): add a note specifying how the
existing apps were started
---
docs/angular/add-to-existing.md | 6 ++++++
docs/react/add-to-existing.md | 6 ++++++
docs/vue/add-to-existing.md | 6 ++++++
versioned_docs/version-v7/react/add-to-existing.md | 6 ++++++
4 files changed, 24 insertions(+)
diff --git a/docs/angular/add-to-existing.md b/docs/angular/add-to-existing.md
index 58c3250a8fe..e574460a89e 100644
--- a/docs/angular/add-to-existing.md
+++ b/docs/angular/add-to-existing.md
@@ -24,6 +24,12 @@ This guide uses `.css` file extensions for stylesheets. If you created your Angu
## Setup
+:::info
+
+This guide follows the structure of an Angular app created with the Angular CLI. If you started your Angular app using a different method, your file structure and setup may differ.
+
+:::
+
You can add Ionic Angular to your existing Angular project using the Angular CLI's `ng add` feature or by installing it manually.
### Using ng add
diff --git a/docs/react/add-to-existing.md b/docs/react/add-to-existing.md
index 676b26ff286..afb94d4fe7c 100644
--- a/docs/react/add-to-existing.md
+++ b/docs/react/add-to-existing.md
@@ -24,6 +24,12 @@ This guide uses TypeScript examples. If you're using JavaScript, the setup proce
## Setup
+:::info
+
+This guide follows the structure of a React app created with Vite. If you started your React app using a different tool (such as Create React App), your file structure and setup may differ.
+
+:::
+
Follow these steps to add Ionic React to your existing React project:
#### 1. Install the Package
diff --git a/docs/vue/add-to-existing.md b/docs/vue/add-to-existing.md
index 6d9084525e5..7eb5a5b0107 100644
--- a/docs/vue/add-to-existing.md
+++ b/docs/vue/add-to-existing.md
@@ -24,6 +24,12 @@ This guide uses JavaScript examples. If you're using TypeScript, the setup proce
## Setup
+:::info
+
+This guide follows the structure of a Vue app created with `create-vue` (which uses Vite). If you started your Vue app using a different tool (such as Vue CLI), your file structure and setup may differ.
+
+:::
+
Follow these steps to add Ionic Vue to your existing Vue project:
#### 1. Install the Packages
diff --git a/versioned_docs/version-v7/react/add-to-existing.md b/versioned_docs/version-v7/react/add-to-existing.md
index 676b26ff286..afb94d4fe7c 100644
--- a/versioned_docs/version-v7/react/add-to-existing.md
+++ b/versioned_docs/version-v7/react/add-to-existing.md
@@ -24,6 +24,12 @@ This guide uses TypeScript examples. If you're using JavaScript, the setup proce
## Setup
+:::info
+
+This guide follows the structure of a React app created with Vite. If you started your React app using a different tool (such as Create React App), your file structure and setup may differ.
+
+:::
+
Follow these steps to add Ionic React to your existing React project:
#### 1. Install the Package
From 8b304dd8ab6b4be2c4423357ec5f2d910809d0a0 Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Thu, 13 Nov 2025 17:28:47 -0500
Subject: [PATCH 12/14] style: https
---
docs/react/add-to-existing.md | 2 +-
docs/vue/add-to-existing.md | 2 +-
versioned_docs/version-v7/react/add-to-existing.md | 2 +-
3 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/docs/react/add-to-existing.md b/docs/react/add-to-existing.md
index afb94d4fe7c..929bed987fb 100644
--- a/docs/react/add-to-existing.md
+++ b/docs/react/add-to-existing.md
@@ -140,7 +140,7 @@ Create a `src/theme/variables.css` file with the following content:
```css title="src/theme/variables.css"
/* For information on how to create your own theme, please refer to:
-http://ionicframework.com/docs/theming/ */
+https://ionicframework.com/docs/theming/ */
```
Then, import the file and the dark palette stylesheet in `src/App.tsx`:
diff --git a/docs/vue/add-to-existing.md b/docs/vue/add-to-existing.md
index 7eb5a5b0107..0277e6a5740 100644
--- a/docs/vue/add-to-existing.md
+++ b/docs/vue/add-to-existing.md
@@ -118,7 +118,7 @@ Create a `src/theme/variables.css` file with the following content:
```css title="src/theme/variables.css"
/* For information on how to create your own theme, please refer to:
-http://ionicframework.com/docs/theming/ */
+https://ionicframework.com/docs/theming/ */
```
Then, import the file and the dark palette stylesheet in `src/main.js`:
diff --git a/versioned_docs/version-v7/react/add-to-existing.md b/versioned_docs/version-v7/react/add-to-existing.md
index afb94d4fe7c..929bed987fb 100644
--- a/versioned_docs/version-v7/react/add-to-existing.md
+++ b/versioned_docs/version-v7/react/add-to-existing.md
@@ -140,7 +140,7 @@ Create a `src/theme/variables.css` file with the following content:
```css title="src/theme/variables.css"
/* For information on how to create your own theme, please refer to:
-http://ionicframework.com/docs/theming/ */
+https://ionicframework.com/docs/theming/ */
```
Then, import the file and the dark palette stylesheet in `src/App.tsx`:
From ec1e56b9f40b285d0f4edba17369161d91deea5a Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Thu, 13 Nov 2025 17:29:25 -0500
Subject: [PATCH 13/14] feat(docusaurus): add json code styling
---
docusaurus.config.js | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/docusaurus.config.js b/docusaurus.config.js
index e7b90b1c434..3288ffc7371 100644
--- a/docusaurus.config.js
+++ b/docusaurus.config.js
@@ -19,7 +19,7 @@ const VERSIONS_JSON = require('./versions.json');
* Note that the urls specified in this file should
* NOT have a trailing slash otherwise users will
* briefly get a 404 Page Not Found error before
- * the docuementation website loads.
+ * the documentation website loads.
*/
const ARCHIVED_VERSIONS_JSON = require('./versionsArchived.json');
@@ -325,7 +325,7 @@ module.exports = {
theme: { plain: {}, styles: [] },
// Prism provides a [default list of languages](https://github.com/FormidableLabs/prism-react-renderer/blob/e1c83a468b05df7f452b3ad7e4ae5ab874574d4e/packages/generate-prism-languages/index.ts#L9-L26).
// A list of [additional languages](https://prismjs.com/#supported-languages) that are supported can be found at their website.
- additionalLanguages: ['shell-session', 'http', 'diff'],
+ additionalLanguages: ['shell-session', 'http', 'diff', 'json'],
},
algolia: {
appId: 'O9QSL985BS',
From 5885b6e0a3d4491d0b1ec105392f56e1a2eb1db1 Mon Sep 17 00:00:00 2001
From: Brandy Smith <6577830+brandyscarney@users.noreply.github.com>
Date: Thu, 13 Nov 2025 17:32:22 -0500
Subject: [PATCH 14/14] docs(cdn): update docs layout link
---
docs/intro/cdn.md | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/docs/intro/cdn.md b/docs/intro/cdn.md
index 5a230b5c939..adf8a7ceda7 100644
--- a/docs/intro/cdn.md
+++ b/docs/intro/cdn.md
@@ -116,7 +116,7 @@ It's recommended to use [jsdelivr](https://www.jsdelivr.com/) to access the Fram
```
-With this it's possible to use all of the Ionic Framework core components without having to install a framework. The CSS bundle will include all of the Ionic [Global Stylesheets](../layout/global-stylesheets).
+With this it's possible to use all of the Ionic Framework core components without having to install a framework. The CSS bundle will include all of the Ionic [Global Stylesheets](/docs/layout/global-stylesheets.md).
## Ionicons CDN
})
+ {index < array.length - 1 && (
+