Skip to content

Commit fd7dd8f

Browse files
brandyscarneyferanmiodugbemi
brandyscarney
and
feranmiodugbemi
authored
docs(intro): update packages & CDN to redirect to other guides (#4286)
Resolves #446 --------- Co-authored-by: Brandy Smith <[email protected]> Co-authored-by: feranmiodugbemi <[email protected]>
1 parent 1d663b7 commit fd7dd8f

File tree

15 files changed

+1571
-432
lines changed

15 files changed

+1571
-432
lines changed

‎cspell-wordlist.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ flexbox
3939
frontmatter
4040
fullscreen
4141
geolocation
42+
iconset
4243
interactives
4344
isopen
4445
jank

‎docs/angular/add-to-existing.md‎

Lines changed: 344 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,344 @@
1+
---
2+
title: Add to Existing Angular Project
3+
sidebar_label: Add to Existing
4+
---
5+
6+
import DocsCard from '@components/global/DocsCard';
7+
import DocsCards from '@components/global/DocsCards';
8+
9+
<head>
10+
<title>Add Ionic Angular to Existing Project: Integration Guide</title>
11+
<meta
12+
name="description"
13+
content="Learn how to add Ionic Angular to your existing Angular project. Step-by-step guide for integrating Ionic components and features into an existing Angular application."
14+
/>
15+
</head>
16+
17+
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).
18+
19+
:::tip
20+
21+
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.
22+
23+
:::
24+
25+
## Setup
26+
27+
:::info
28+
29+
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.
30+
31+
:::
32+
33+
You can add Ionic Angular to your existing Angular project using the Angular CLI's `ng add` feature or by installing it manually.
34+
35+
### Using ng add
36+
37+
The easiest way to add Ionic Angular is to use the Angular CLI's `ng add` feature:
38+
39+
```bash
40+
ng add @ionic/angular
41+
```
42+
43+
This will install the `@ionic/angular` package and automatically configure the necessary imports and styles.
44+
45+
### Manual Installation
46+
47+
If you prefer to install Ionic Angular manually, you can follow these steps:
48+
49+
#### 1. Install the Package
50+
51+
```bash
52+
npm install @ionic/angular
53+
```
54+
55+
#### 2. Add Ionic Framework Stylesheets
56+
57+
Replace the existing `styles` array in `angular.json` with the following:
58+
59+
```json title="angular.json"
60+
"styles": [
61+
"src/styles.css",
62+
{
63+
"input": "node_modules/@ionic/angular/css/core.css"
64+
},
65+
{
66+
"input": "node_modules/@ionic/angular/css/normalize.css"
67+
},
68+
{
69+
"input": "node_modules/@ionic/angular/css/structure.css"
70+
},
71+
{
72+
"input": "node_modules/@ionic/angular/css/typography.css"
73+
}
74+
]
75+
```
76+
77+
:::info
78+
79+
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, refer to [Global Stylesheets](/docs/layout/global-stylesheets.md).
80+
81+
:::
82+
83+
#### 3. Configure Ionic Angular
84+
85+
Update `src/app/app.config.ts` to include `provideIonicAngular`:
86+
87+
```typescript title="src/app/app.config.ts"
88+
import { ApplicationConfig, provideBrowserGlobalErrorListeners, provideZoneChangeDetection } from '@angular/core';
89+
import { provideRouter } from '@angular/router';
90+
91+
import { routes } from './app.routes';
92+
import { provideIonicAngular } from '@ionic/angular/standalone';
93+
94+
export const appConfig: ApplicationConfig = {
95+
providers: [
96+
provideBrowserGlobalErrorListeners(),
97+
provideZoneChangeDetection({ eventCoalescing: true }),
98+
provideRouter(routes),
99+
provideIonicAngular({}),
100+
],
101+
};
102+
```
103+
104+
## Using Individual Components
105+
106+
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:
107+
108+
Update `src/app/app.html` to the following:
109+
110+
```html title="src/app/app.html"
111+
<ion-button>Button</ion-button> <ion-datetime></ion-datetime>
112+
```
113+
114+
Then, import the components in `src/app/app.ts`:
115+
116+
```ts title="src/app/app.ts"
117+
import { Component } from '@angular/core';
118+
import { IonButton, IonDatetime } from '@ionic/angular/standalone';
119+
120+
@Component({
121+
selector: 'app-root',
122+
imports: [IonButton, IonDatetime],
123+
templateUrl: './app.html',
124+
styleUrl: './app.css',
125+
})
126+
export class App {}
127+
```
128+
129+
Visit the [components](/docs/components.md) page for all of the available Ionic components.
130+
131+
## Using Ionic Pages
132+
133+
If you want to use Ionic pages with full navigation and page transitions, follow these additional setup steps.
134+
135+
#### 1. Add Additional Ionic Framework Stylesheets
136+
137+
Replace the existing `styles` array in `angular.json` with the following:
138+
139+
```json title="angular.json"
140+
"styles": [
141+
"src/styles.css",
142+
{
143+
"input": "node_modules/@ionic/angular/css/core.css"
144+
},
145+
{
146+
"input": "node_modules/@ionic/angular/css/normalize.css"
147+
},
148+
{
149+
"input": "node_modules/@ionic/angular/css/structure.css"
150+
},
151+
{
152+
"input": "node_modules/@ionic/angular/css/typography.css"
153+
},
154+
{
155+
"input": "node_modules/@ionic/angular/css/display.css"
156+
},
157+
{
158+
"input": "node_modules/@ionic/angular/css/padding.css"
159+
},
160+
{
161+
"input": "node_modules/@ionic/angular/css/float-elements.css"
162+
},
163+
{
164+
"input": "node_modules/@ionic/angular/css/text-alignment.css"
165+
},
166+
{
167+
"input": "node_modules/@ionic/angular/css/text-transformation.css"
168+
},
169+
{
170+
"input": "node_modules/@ionic/angular/css/flex-utils.css"
171+
},
172+
{
173+
"input": "src/theme/variables.css"
174+
}
175+
]
176+
```
177+
178+
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).
179+
180+
#### 2. Set up Theming
181+
182+
Create a `src/theme/variables.css` file with the following content:
183+
184+
```css title="src/theme/variables.css"
185+
/**
186+
* Ionic Dark Theme
187+
* -----------------------------------------------------
188+
* For more info, please refer to:
189+
* https://ionicframework.com/docs/theming/dark-mode
190+
*/
191+
192+
/* @import "@ionic/angular/css/palettes/dark.always.css"; */
193+
/* @import "@ionic/angular/css/palettes/dark.class.css"; */
194+
@import '@ionic/angular/css/palettes/dark.system.css';
195+
```
196+
197+
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.
198+
199+
#### 3. Update the App Component
200+
201+
Update `src/app/app.html` to the following:
202+
203+
```html title="src/app/app.html"
204+
<ion-app>
205+
<ion-router-outlet></ion-router-outlet>
206+
</ion-app>
207+
```
208+
209+
Then, update `src/app/app.ts` to include the component imports:
210+
211+
```ts title="src/app/app.ts"
212+
import { Component } from '@angular/core';
213+
import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
214+
215+
@Component({
216+
selector: 'app-root',
217+
imports: [IonApp, IonRouterOutlet],
218+
templateUrl: './app.html',
219+
styleUrl: './app.css',
220+
})
221+
export class App {}
222+
```
223+
224+
#### 4. Create a Home Page
225+
226+
Start by adding a template at `src/app/home/home.html`:
227+
228+
```html title="src/app/home/home.html"
229+
<ion-header translucent="true">
230+
<ion-toolbar>
231+
<ion-title>Home</ion-title>
232+
</ion-toolbar>
233+
</ion-header>
234+
235+
<ion-content fullscreen="true">
236+
<ion-header collapse="condense">
237+
<ion-toolbar>
238+
<ion-title size="large">Home</ion-title>
239+
</ion-toolbar>
240+
</ion-header>
241+
242+
<div id="container">
243+
<strong>Ready to create an app?</strong>
244+
<p>
245+
Start with Ionic
246+
<a target="_blank" rel="noopener noreferrer" href="https://ionicframework.com/docs/components">UI Components</a>
247+
</p>
248+
</div>
249+
</ion-content>
250+
```
251+
252+
Then, create `src/app/home/home.ts` with the following:
253+
254+
```ts title="src/app/home/home.ts"
255+
import { Component } from '@angular/core';
256+
import { IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';
257+
258+
@Component({
259+
selector: 'app-home',
260+
imports: [IonContent, IonHeader, IonTitle, IonToolbar],
261+
templateUrl: './home.html',
262+
styleUrl: './home.css',
263+
})
264+
export class HomePage {}
265+
```
266+
267+
Finally, add a `src/app/home/home.css` file:
268+
269+
```css title="src/app/home/home.css"
270+
#container {
271+
text-align: center;
272+
273+
position: absolute;
274+
left: 0;
275+
right: 0;
276+
top: 50%;
277+
transform: translateY(-50%);
278+
}
279+
280+
#container strong {
281+
font-size: 20px;
282+
line-height: 26px;
283+
}
284+
285+
#container p {
286+
font-size: 16px;
287+
line-height: 22px;
288+
289+
color: #8c8c8c;
290+
291+
margin: 0;
292+
}
293+
294+
#container a {
295+
text-decoration: none;
296+
}
297+
```
298+
299+
#### 5. Set up Routing
300+
301+
Update `src/app/app.routes.ts` to add a `home` route:
302+
303+
```ts title="src/app/app.routes.ts"
304+
import { Routes } from '@angular/router';
305+
import { HomePage } from './home/home';
306+
307+
export const routes: Routes = [
308+
{
309+
path: '',
310+
redirectTo: 'home',
311+
pathMatch: 'full',
312+
},
313+
{
314+
path: 'home',
315+
component: HomePage,
316+
},
317+
];
318+
```
319+
320+
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.
321+
322+
## Next Steps
323+
324+
Now that you have Ionic Angular integrated into your project, check out:
325+
326+
<DocsCards>
327+
328+
<DocsCard header="Navigation" href="navigation" icon="/icons/component-navigation-icon.png">
329+
<p>Discover how to handle routing and navigation in Ionic Angular apps using the Angular Router.</p>
330+
</DocsCard>
331+
332+
<DocsCard header="Components" href="/docs/components" icon="/icons/guide-components-icon.png">
333+
<p>Explore Ionic's rich library of UI components for building beautiful apps.</p>
334+
</DocsCard>
335+
336+
<DocsCard header="Theming" href="/docs/theming/basics" icon="/icons/guide-theming-icon.png">
337+
<p>Learn how to customize the look and feel of your app with Ionic's powerful theming system.</p>
338+
</DocsCard>
339+
340+
<DocsCard header="Capacitor Documentation" href="https://capacitorjs.com/docs/" icon="/icons/guide-capacitor-icon.png">
341+
<p>Explore how to access native device features and deploy your app to iOS, Android, and the web with Capacitor.</p>
342+
</DocsCard>
343+
344+
</DocsCards>

0 commit comments

Comments
 (0)