Skip to content

docs(angular): document standalone and lazy import path changes #4576

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
OS-jacobbell wants to merge 5 commits into
base: major-9.0
Choose a base branch
from
Open

docs(angular): document standalone and lazy import path changes #4576

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d076497
docs(angular): document standalone and lazy import path changes
OS-jacobbell Jul 9, 2026
a0f7468
lint and spellcheck
OS-jacobbell Jul 9, 2026
ef0e9cd
apply feedback
OS-jacobbell Jul 10, 2026
5ff66f9
Update docs/developing/managing-focus.md
OS-jacobbell Jul 13, 2026
474bb8e
update imports in playground
OS-jacobbell Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/angular/add-to-existing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/
import { provideRouter } from '@angular/router';

import { routes } from './app.routes';
import { provideIonicAngular } from '@ionic/angular/standalone';
import { provideIonicAngular } from '@ionic/angular';

export const appConfig: ApplicationConfig = {
providers: [provideBrowserGlobalErrorListeners(), provideRouter(routes), provideIonicAngular({})],
Expand All @@ -112,7 +112,7 @@ 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';
import { IonButton, IonDatetime } from '@ionic/angular';

@Component({
selector: 'app-root',
Expand Down Expand Up @@ -207,7 +207,7 @@ 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';
import { IonApp, IonRouterOutlet } from '@ionic/angular';

@Component({
selector: 'app-root',
Expand Down Expand Up @@ -250,7 +250,7 @@ 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';
import { IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular';

@Component({
selector: 'app-home',
Expand Down
74 changes: 37 additions & 37 deletions docs/angular/build-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ See the [Standalone Migration Guide](#migrating-from-modules-to-standalone) for
### Usage with Standalone-based Applications

:::warning
All Ionic imports should be imported from the `@ionic/angular/standalone` submodule. This includes imports such as components, directives, providers, and types. Importing from `@ionic/angular` may pull in lazy loaded Ionic code which can interfere with treeshaking.
All Ionic imports should be imported from the `@ionic/angular` submodule. This includes imports such as components, directives, providers, and types. Importing from `@ionic/angular/lazy` may pull in lazy loaded Ionic code which can interfere with treeshaking.
:::

**Bootstrapping and Configuration**
Expand All @@ -43,7 +43,7 @@ Ionic Angular needs to be configured when the Angular application calls `bootstr
import { enableProdMode, importProvidersFrom } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { RouteReuseStrategy, provideRouter } from '@angular/router';
import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular/standalone';
import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular';

import { routes } from './app/app.routes';
import { AppComponent } from './app/app.component';
Expand All @@ -59,11 +59,11 @@ bootstrapApplication(AppComponent, {

**Components**

In the example below, we are importing `IonContent` and `IonButton` from `@ionic/angular/standalone` and passing them to `imports` for use in the component template. We would get a compiler error if these components were not imported and provided to the `imports` array.
In the example below, we are importing `IonContent` and `IonButton` from `@ionic/angular` and passing them to `imports` for use in the component template. We would get a compiler error if these components were not imported and provided to the `imports` array.

```typescript title="home.page.ts"
import { Component } from '@angular/core';
import { IonButton, IonContent } from '@ionic/angular/standalone';
import { IonButton, IonContent } from '@ionic/angular';

@Component({
selector: 'app-home',
Expand All @@ -87,7 +87,7 @@ For developers using Ionicons 7.2 or newer, passing only the SVG data will cause

```typescript title="home.page.ts"
import { Component } from '@angular/core';
import { IonIcon } from '@ionic/angular/standalone';
import { IonIcon } from '@ionic/angular';
import { addIcons } from 'ionicons';
import { logoIonic } from 'ionicons/icons';

Expand Down Expand Up @@ -153,7 +153,7 @@ Developers who wish to use `routerLink`, `routerAction`, or `routerDirection` on
```typescript title="home.page.ts"
import { Component } from '@angular/core';
import { RouterLink } from '@angular/router';
import { IonButton, IonRouterLink } from '@ionic/angular/standalone';
import { IonButton, IonRouterLink } from '@ionic/angular';

@Component({
selector: 'app-home',
Expand Down Expand Up @@ -199,7 +199,7 @@ Ionic Angular's standalone components use ES Modules. As a result, developers us
### Usage with NgModule-based Applications

:::warning
All Ionic imports should be imported from the `@ionic/angular/standalone` submodule. This includes imports such as components, directives, providers, and types. Importing from `@ionic/angular` may pull in lazy loaded Ionic code which can interfere with treeshaking.
All Ionic imports should be imported from the `@ionic/angular` submodule. This includes imports such as components, directives, providers, and types. Importing from `@ionic/angular/lazy` may pull in lazy loaded Ionic code which can interfere with treeshaking.
:::

**Bootstrapping and Configuration**
Expand All @@ -211,7 +211,7 @@ import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { RouteReuseStrategy } from '@angular/router';

import { IonicRouteStrategy, provideIonicAngular } from '@ionic/angular/standalone';
import { IonicRouteStrategy, provideIonicAngular } from '@ionic/angular';

import { AppComponent } from './app.component';
import { AppRoutingModule } from './app-routing.module';
Expand All @@ -227,11 +227,11 @@ export class AppModule {}

**Components**

In the example below, we are importing `IonContent` and `IonButton` from `@ionic/angular/standalone` and passing them to `imports` array in the Angular component's NgModule for use in the component template. We would get a compiler error if these components were not imported and provided to the `imports` array.
In the example below, we are importing `IonContent` and `IonButton` from `@ionic/angular` and passing them to `imports` array in the Angular component's NgModule for use in the component template. We would get a compiler error if these components were not imported and provided to the `imports` array.

```typescript title="home.module.ts"
import { NgModule } from '@angular/core';
import { IonButton, IonContent } from '@ionic/angular/standalone';
import { IonButton, IonContent } from '@ionic/angular';
import { HomePage } from './home.page';

import { HomePageRoutingModule } from './home-routing.module';
Expand Down Expand Up @@ -315,7 +315,7 @@ Developers who wish to use `routerLink`, `routerAction`, or `routerDirection` on
```typescript title="home.module.ts"
import { NgModule } from '@angular/core';
import { RouterLink } from '@angular/router';
import { IonButton, IonRouterLink } from '@ionic/angular/standalone';
import { IonButton, IonRouterLink } from '@ionic/angular';
import { HomePage } from './home.page';

import { HomePageRoutingModule } from './home-routing.module';
Expand Down Expand Up @@ -416,14 +416,14 @@ Follow these steps if your Angular application is already using the standalone a

2. Run `npm install ionicons@latest` to ensure you are running the latest version of Ionicons. Ionicons v7.2 brings usability improvements that reduce the code boilerplate needed to use icons with standalone components.

3. Remove the `IonicModule` call in `main.ts` in favor of `provideIonicAngular` imported from `@ionic/angular/standalone`. Any config passed to `IonicModule.forRoot` can be passed as an object to this new function.
3. Remove the `IonicModule` call in `main.ts` in favor of `provideIonicAngular` imported from `@ionic/angular`. Any config passed to `IonicModule.forRoot` can be passed as an object to this new function.

```diff title="main.ts"
import { enableProdMode, importProvidersFrom } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { RouteReuseStrategy, provideRouter } from '@angular/router';
- import { IonicModule, IonicRouteStrategy } from '@ionic/angular';
+ import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular/standalone';
- import { IonicModule, IonicRouteStrategy } from '@ionic/angular/lazy';
+ import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular';

import { routes } from './app/app.routes';
import { AppComponent } from './app/app.component';
Expand All @@ -446,18 +446,18 @@ bootstrapApplication(AppComponent, {

4. Remove any references to `IonicModule` found elsewhere in your application.

5. Update any existing imports from `@ionic/angular` to import from `@ionic/angular/standalone` instead.
5. Update any existing imports from `@ionic/angular/lazy` to import from `@ionic/angular` instead.

```diff
- import { Platform } from '@ionic/angular';
+ import { Platform } from '@ionic/angular/standalone';
- import { Platform } from '@ionic/angular/lazy';
+ import { Platform } from '@ionic/angular';
```

6. Add imports for each Ionic component in the Angular component where they are used. Be sure to pass the imports to the `imports` array on your Angular component.

```diff title="app.component.ts"
import { Component } from '@angular/core';
+ import { IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
+ import { IonApp, IonRouterOutlet } from '@ionic/angular';

@Component({
selector: 'app-root',
Expand All @@ -475,7 +475,7 @@ export class AppComponent {

```diff title="test.component.ts"
import { Component } from '@angular/core';
+ import { IonIcon } from '@ionic/angular/standalone';
+ import { IonIcon } from '@ionic/angular';
+ import { addIcons } from 'ionicons';
+ import { alarm, logoIonic } from 'ionicons/icons';

Expand Down Expand Up @@ -507,8 +507,8 @@ export class TestComponent {

```diff title="test.component.ts"
import { Component } from '@angular/core';
- import { IonButton } from '@ionic/angular/standalone';
+ import { IonButton, IonRouterLink } from '@ionic/angular/standalone';
- import { IonButton } from '@ionic/angular';
+ import { IonButton, IonRouterLink } from '@ionic/angular';

@Component({
selector: 'app-root',
Expand All @@ -523,11 +523,11 @@ import { Component } from '@angular/core';
export class TestComponent {}
```

10. If you are using VSCode it is recommended to ignore the `@ionic/angular/common` and `@ionic/angular` module specifiers for import recommendations.
10. If you are using VSCode it is recommended to ignore the `@ionic/angular/common` and `@ionic/angular/lazy` module specifiers for import recommendations.

```json title=".vscode/settings.json"
{
"typescript.preferences.autoImportFileExcludePatterns": ["@ionic/angular/common", "@ionic/angular"]
"typescript.preferences.autoImportFileExcludePatterns": ["@ionic/angular/common", "@ionic/angular/lazy"]
}
```

Expand All @@ -539,14 +539,14 @@ Follow these steps if your Angular application is still using the NgModule archi

2. Run `npm install ionicons@latest` to ensure you are running the latest version of Ionicons. Ionicons v7.2 brings usability improvements that reduce the code boilerplate needed to use icons with standalone components.

3. Remove the `IonicModule` call in `app.module.ts` in favor of `provideIonicAngular` imported from `@ionic/angular/standalone`. Any config passed to `IonicModule.forRoot` can be passed as an object to this new function.
3. Remove the `IonicModule` call in `app.module.ts` in favor of `provideIonicAngular` imported from `@ionic/angular`. Any config passed to `IonicModule.forRoot` can be passed as an object to this new function.

```diff title="app.module.ts"
import { enableProdMode, importProvidersFrom } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { RouteReuseStrategy, provideRouter } from '@angular/router';
- import { IonicModule, IonicRouteStrategy } from '@ionic/angular';
+ import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular/standalone';
- import { IonicModule, IonicRouteStrategy } from '@ionic/angular/lazy';
+ import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular';

import { routes } from './app/app.routes';
import { AppComponent } from './app/app.component';
Expand All @@ -572,11 +572,11 @@ export class AppModule {}

4. Remove any references to `IonicModule` found elsewhere in your application.

5. Update any existing imports from `@ionic/angular` to import from `@ionic/angular/standalone` instead.
5. Update any existing imports from `@ionic/angular/lazy` to import from `@ionic/angular` instead.

```diff
- import { Platform } from '@ionic/angular';
+ import { Platform } from '@ionic/angular/standalone';
- import { Platform } from '@ionic/angular/lazy';
+ import { Platform } from '@ionic/angular';
```

6. Add imports for each Ionic component in the NgModule for the Angular component where they are used. Be sure to pass the components to the `imports` array on the module.
Expand All @@ -585,8 +585,8 @@ export class AppModule {}
import { enableProdMode, importProvidersFrom } from '@angular/core';
import { bootstrapApplication } from '@angular/platform-browser';
import { RouteReuseStrategy, provideRouter } from '@angular/router';
- import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular/standalone';
+ import { provideIonicAngular, IonicRouteStrategy, IonApp, IonRouterOutlet } from '@ionic/angular/standalone';
- import { provideIonicAngular, IonicRouteStrategy } from '@ionic/angular';
+ import { provideIonicAngular, IonicRouteStrategy, IonApp, IonRouterOutlet } from '@ionic/angular';

import { routes } from './app/app.routes';
import { AppComponent } from './app/app.component';
Expand Down Expand Up @@ -614,7 +614,7 @@ import { HomePage } from './home.page';

import { HomePageRoutingModule } from './home-routing.module';

+ import { IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular/standalone';
+ import { IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/angular';

@NgModule({
imports: [
Expand Down Expand Up @@ -653,7 +653,7 @@ export class TestComponent {
```diff title="test.module.ts"
import { NgModule } from '@angular/core';
import { TestComponent } from './test.component';
+ import { IonIcon } from '@ionic/angular/standalone';
+ import { IonIcon } from '@ionic/angular';

@NgModule({
imports: [
Expand All @@ -679,8 +679,8 @@ export class TestComponentModule {}
```diff title="test.module.ts"
import { NgModule } from '@angular/core';
import { TestComponent } from './test.component';
- import { IonButton } from '@ionic/angular/standalone';
+ import { IonButton, IonRouterLink } from '@ionic/angular/standalone';
- import { IonButton } from '@ionic/angular';
+ import { IonButton, IonRouterLink } from '@ionic/angular';

@NgModule({
imports: [
Expand All @@ -691,10 +691,10 @@ import { TestComponent } from './test.component';
})
```

10. If you are using VSCode it is recommended to ignore the `@ionic/angular/common` and `@ionic/angular` module specifiers for import recommendations.
10. If you are using VSCode it is recommended to ignore the `@ionic/angular/common` and `@ionic/angular/lazy` module specifiers for import recommendations.

```json title=".vscode/settings.json"
{
"typescript.preferences.autoImportFileExcludePatterns": ["@ionic/angular/common", "@ionic/angular"]
"typescript.preferences.autoImportFileExcludePatterns": ["@ionic/angular/common", "@ionic/angular/lazy"]
}
```
8 changes: 4 additions & 4 deletions docs/angular/injection-tokens.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ To use the `IonModalToken`, inject it into your component's constructor:

```tsx
import { Component, inject } from '@angular/core';
import { IonButton, IonContent, IonHeader, IonModalToken, IonTitle, IonToolbar } from '@ionic/angular/standalone';
import { IonButton, IonContent, IonHeader, IonModalToken, IonTitle, IonToolbar } from '@ionic/angular';

@Component({
selector: 'app-modal',
Expand Down Expand Up @@ -66,7 +66,7 @@ You can use the injected modal reference to listen to modal lifecycle events:

```tsx
import { Component, inject, OnInit } from '@angular/core';
import { IonButton, IonContent, IonHeader, IonModalToken, IonTitle, IonToolbar } from '@ionic/angular/standalone';
import { IonButton, IonContent, IonHeader, IonModalToken, IonTitle, IonToolbar } from '@ionic/angular';

@Component({
selector: 'app-modal',
Expand Down Expand Up @@ -108,7 +108,7 @@ The injected modal reference provides access to all modal properties and methods

```tsx
import { Component, inject, OnInit } from '@angular/core';
import { IonButton, IonContent, IonHeader, IonModalToken, IonTitle, IonToolbar } from '@ionic/angular/standalone';
import { IonButton, IonContent, IonHeader, IonModalToken, IonTitle, IonToolbar } from '@ionic/angular';

@Component({
selector: 'app-modal',
Expand Down Expand Up @@ -149,7 +149,7 @@ When opening a modal that uses the injection token, you can pass the component d

```tsx
import { Component, inject } from '@angular/core';
import { IonContent, IonButton, ModalController } from '@ionic/angular/standalone';
import { IonContent, IonButton, ModalController } from '@ionic/angular';
import { ModalComponent } from './modal.component';

@Component({
Expand Down
6 changes: 3 additions & 3 deletions docs/angular/platform.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ The Platform service can be used to get information about your current device. Y
<TabItem value="angular">

```tsx
import { Platform } from '@ionic/angular';
import { Platform } from '@ionic/angular/lazy';

@Component({...})
export class MyPage {
Expand All @@ -42,7 +42,7 @@ export class MyPage {
<TabItem value="angular-standalone">

```tsx
import { Platform } from '@ionic/angular/standalone';
import { Platform } from '@ionic/angular';

@Component({...})
export class MyPage {
Expand Down Expand Up @@ -96,7 +96,7 @@ Below is a table listing all the possible platform values along with correspondi
The function used to detect a specific platform can be overridden by providing an alternative function in the global [Ionic config](../developing/config). Each function takes `window` as a parameter and returns a boolean.

```tsx
import { IonicModule } from '@ionic/angular';
import { IonicModule } from '@ionic/angular/lazy';

@NgModule({
...
Expand Down
Loading
Loading