From 22911ec11a747a8792d89c3f3372596c3aa5a2cd Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Thu, 27 Aug 2026 15:35:24 -0700 Subject: [PATCH] chore(docs): pad admonitions with blank lines --- docs/angular/build-options.md | 12 +++++++++ docs/angular/lifecycle.md | 2 ++ docs/angular/navigation.md | 4 +++ docs/angular/performance.md | 2 ++ docs/angular/pwa.md | 8 ++++++ docs/angular/quickstart.md | 6 +++++ docs/angular/slides.md | 12 +++++++++ docs/angular/storage.md | 2 ++ docs/angular/your-first-app.md | 6 +++++ .../angular/your-first-app/2-taking-photos.md | 2 ++ .../your-first-app/4-loading-photos.md | 2 ++ .../your-first-app/6-deploying-mobile.md | 2 ++ docs/angular/your-first-app/7-live-reload.md | 2 ++ docs/angular/zoneless.md | 2 ++ docs/api/accordion.md | 2 ++ docs/api/alert.md | 2 ++ docs/api/badge.md | 2 ++ docs/api/button.md | 2 ++ docs/api/checkbox.md | 4 +++ docs/api/datetime.md | 18 +++++++++++++ docs/api/img.md | 2 ++ docs/api/input-otp.md | 6 ++++- docs/api/input-password-toggle.md | 2 ++ docs/api/input.md | 6 +++++ docs/api/loading.md | 2 ++ docs/api/modal.md | 10 +++++++ docs/api/nav.md | 2 ++ docs/api/picker.md | 2 ++ docs/api/popover.md | 6 +++++ docs/api/radio.md | 4 +++ docs/api/reorder.md | 2 ++ docs/api/route-redirect.md | 2 ++ docs/api/route.md | 2 ++ docs/api/router-link.md | 2 ++ docs/api/router.md | 2 ++ docs/api/segment.md | 2 ++ docs/api/select.md | 6 +++++ docs/api/split-pane.md | 2 ++ docs/api/tab-bar.md | 2 ++ docs/api/tab.md | 2 ++ docs/api/textarea.md | 4 +++ docs/api/toggle.md | 2 ++ docs/cli.md | 2 ++ docs/cli/configuration.md | 4 +++ docs/cli/livereload.md | 4 +++ docs/deployment/app-store.md | 4 +++ docs/deployment/play-store.mdx | 10 +++++++ .../guides/first-app-v4/intro.md | 2 ++ docs/developing/config/per-platform/index.md | 8 ++++++ docs/developing/hardware-back-button.md | 4 +++ docs/developing/keyboard.md | 6 +++++ docs/developing/managing-focus.md | 2 ++ docs/developing/scaffolding.md | 4 +++ docs/developing/tips.md | 4 +++ docs/intro/cli.md | 2 ++ docs/intro/environment.md | 4 +++ docs/javascript/quickstart.md | 8 ++++++ docs/layout/css-utilities.md | 2 ++ docs/layout/dynamic-font-scaling.md | 6 +++++ docs/react/lifecycle.md | 4 +++ docs/react/navigation.md | 2 ++ docs/react/overlays.md | 4 +++ docs/react/pwa.md | 10 +++++++ docs/react/quickstart.md | 8 ++++++ docs/react/slides.md | 16 ++++++++++++ docs/react/storage.md | 2 ++ docs/react/your-first-app.md | 4 +++ docs/react/your-first-app/4-loading-photos.md | 2 ++ .../your-first-app/6-deploying-mobile.md | 2 ++ docs/react/your-first-app/7-live-reload.md | 2 ++ docs/reference/browser-support.md | 2 ++ docs/techniques/security.md | 4 +++ docs/theming/advanced.md | 6 +++++ docs/theming/colors.md | 2 ++ docs/theming/css-shadow-parts.md | 6 +++++ docs/theming/dark-mode.md | 26 +++++++++++++++++++ docs/theming/high-contrast-mode.md | 10 +++++++ docs/troubleshooting/cors.md | 2 ++ docs/troubleshooting/debugging.md | 4 +++ docs/troubleshooting/runtime.md | 10 +++++++ docs/updating/4-0.md | 4 +++ docs/updating/5-0.md | 4 +++ docs/updating/6-0.md | 12 +++++++++ docs/updating/7-0.md | 4 +++ docs/updating/8-0.md | 4 +++ docs/updating/9-0.md | 10 +++++++ docs/vue/lifecycle.md | 2 ++ docs/vue/navigation.md | 2 ++ docs/vue/pwa.md | 8 ++++++ docs/vue/quickstart.md | 8 ++++++ docs/vue/slides.md | 16 ++++++++++++ docs/vue/storage.md | 2 ++ docs/vue/utility-functions.md | 4 +++ docs/vue/virtual-scroll.md | 4 +++ docs/vue/your-first-app.md | 4 +++ docs/vue/your-first-app/4-loading-photos.md | 2 ++ docs/vue/your-first-app/6-deploying-mobile.md | 2 ++ docs/vue/your-first-app/7-live-reload.md | 2 ++ .../version-v8/angular/build-options.md | 8 ++++++ .../version-v8/angular/lifecycle.md | 2 ++ .../version-v8/angular/navigation.md | 4 +++ .../version-v8/angular/performance.md | 2 ++ versioned_docs/version-v8/angular/pwa.md | 8 ++++++ .../version-v8/angular/quickstart.md | 6 +++++ versioned_docs/version-v8/angular/slides.md | 12 +++++++++ versioned_docs/version-v8/angular/storage.md | 2 ++ .../version-v8/angular/your-first-app.md | 6 +++++ .../your-first-app/4-loading-photos.md | 2 ++ .../your-first-app/6-deploying-mobile.md | 2 ++ .../angular/your-first-app/7-live-reload.md | 2 ++ versioned_docs/version-v8/api/accordion.md | 2 ++ versioned_docs/version-v8/api/alert.md | 2 ++ versioned_docs/version-v8/api/badge.md | 2 ++ versioned_docs/version-v8/api/button.md | 2 ++ versioned_docs/version-v8/api/checkbox.md | 4 +++ versioned_docs/version-v8/api/datetime.md | 18 +++++++++++++ versioned_docs/version-v8/api/input-otp.md | 6 ++++- .../version-v8/api/input-password-toggle.md | 2 ++ versioned_docs/version-v8/api/input.md | 6 +++++ versioned_docs/version-v8/api/loading.md | 2 ++ versioned_docs/version-v8/api/modal.md | 10 +++++++ versioned_docs/version-v8/api/nav.md | 2 ++ versioned_docs/version-v8/api/picker.md | 2 ++ versioned_docs/version-v8/api/popover.md | 6 +++++ versioned_docs/version-v8/api/radio.md | 4 +++ versioned_docs/version-v8/api/reorder.md | 2 ++ .../version-v8/api/route-redirect.md | 2 ++ versioned_docs/version-v8/api/route.md | 2 ++ versioned_docs/version-v8/api/router-link.md | 2 ++ versioned_docs/version-v8/api/router.md | 2 ++ versioned_docs/version-v8/api/segment.md | 2 ++ versioned_docs/version-v8/api/select.md | 4 +++ versioned_docs/version-v8/api/split-pane.md | 2 ++ versioned_docs/version-v8/api/tab-bar.md | 2 ++ versioned_docs/version-v8/api/tab.md | 2 ++ versioned_docs/version-v8/api/textarea.md | 4 +++ versioned_docs/version-v8/api/toggle.md | 2 ++ versioned_docs/version-v8/cli.md | 2 ++ .../version-v8/cli/configuration.md | 4 +++ versioned_docs/version-v8/cli/livereload.md | 4 +++ .../version-v8/deployment/app-store.md | 4 +++ .../version-v8/deployment/play-store.mdx | 10 +++++++ .../guides/first-app-v4/intro.md | 2 ++ .../developing/config/per-platform/index.md | 8 ++++++ .../developing/hardware-back-button.md | 4 +++ .../version-v8/developing/keyboard.md | 6 +++++ .../version-v8/developing/managing-focus.md | 2 ++ .../version-v8/developing/scaffolding.md | 4 +++ versioned_docs/version-v8/developing/tips.md | 4 +++ versioned_docs/version-v8/intro/cli.md | 2 ++ .../version-v8/intro/environment.md | 4 +++ .../version-v8/javascript/quickstart.md | 8 ++++++ .../version-v8/layout/css-utilities.md | 2 ++ .../version-v8/layout/dynamic-font-scaling.md | 6 +++++ versioned_docs/version-v8/react/lifecycle.md | 4 +++ versioned_docs/version-v8/react/navigation.md | 4 +++ versioned_docs/version-v8/react/overlays.md | 4 +++ versioned_docs/version-v8/react/pwa.md | 10 +++++++ versioned_docs/version-v8/react/quickstart.md | 8 ++++++ versioned_docs/version-v8/react/slides.md | 16 ++++++++++++ versioned_docs/version-v8/react/storage.md | 2 ++ .../version-v8/react/your-first-app.md | 4 +++ .../react/your-first-app/4-loading-photos.md | 2 ++ .../your-first-app/6-deploying-mobile.md | 2 ++ .../react/your-first-app/7-live-reload.md | 2 ++ .../version-v8/reference/browser-support.md | 2 ++ .../version-v8/techniques/security.md | 4 +++ versioned_docs/version-v8/theming/advanced.md | 6 +++++ versioned_docs/version-v8/theming/colors.md | 2 ++ .../version-v8/theming/css-shadow-parts.md | 6 +++++ .../version-v8/theming/dark-mode.md | 26 +++++++++++++++++++ .../version-v8/theming/high-contrast-mode.md | 10 +++++++ .../version-v8/troubleshooting/cors.md | 2 ++ .../version-v8/troubleshooting/debugging.md | 4 +++ .../version-v8/troubleshooting/runtime.md | 10 +++++++ versioned_docs/version-v8/updating/4-0.md | 4 +++ versioned_docs/version-v8/updating/5-0.md | 4 +++ versioned_docs/version-v8/updating/6-0.md | 12 +++++++++ versioned_docs/version-v8/updating/7-0.md | 4 +++ versioned_docs/version-v8/updating/8-0.md | 4 +++ versioned_docs/version-v8/vue/lifecycle.md | 2 ++ versioned_docs/version-v8/vue/navigation.md | 2 ++ versioned_docs/version-v8/vue/pwa.md | 8 ++++++ versioned_docs/version-v8/vue/quickstart.md | 8 ++++++ versioned_docs/version-v8/vue/slides.md | 16 ++++++++++++ versioned_docs/version-v8/vue/storage.md | 2 ++ .../version-v8/vue/utility-functions.md | 4 +++ .../version-v8/vue/virtual-scroll.md | 4 +++ .../version-v8/vue/your-first-app.md | 4 +++ .../vue/your-first-app/4-loading-photos.md | 2 ++ .../vue/your-first-app/6-deploying-mobile.md | 2 ++ .../vue/your-first-app/7-live-reload.md | 2 ++ 192 files changed, 906 insertions(+), 2 deletions(-) diff --git a/docs/angular/build-options.md b/docs/angular/build-options.md index 3c6bc082c5b..f852e122236 100644 --- a/docs/angular/build-options.md +++ b/docs/angular/build-options.md @@ -10,7 +10,9 @@ The Standalone approach uses modern Angular APIs and is the recommended way to b ## Standalone :::info + Ionic UI components as Angular standalone components is supported starting in Ionic v7.5. + ::: ### Overview @@ -30,13 +32,17 @@ Refer to the [Standalone Migration Guide](#migrating-from-modules-to-standalone) 1. Ionic components need to be imported into every Angular component they are used in which can be time consuming to set up. :::info[Code splitting] + Ionic ships standalone components from a single entry point (`@ionic/angular`). Bundlers such as Webpack and esbuild cannot split code from a single entry point across separate chunks, so the Ionic components you import are included in the main bundle rather than in the chunk for the route or component where they are used. Unused components are still tree-shaken out of the build. + ::: ### Usage with Standalone-based Applications :::warning + 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** @@ -203,7 +209,9 @@ 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` 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** @@ -366,7 +374,9 @@ Ionic Angular's standalone components use ES Modules. As a result, developers us ## Modules :::warning[Deprecation Notice] + The Modules approach, including `IonicModule`, is **deprecated** and will be removed in a future major release. Existing applications will continue to work during the deprecation period but should migrate using the [Standalone migration guide](#migrating-from-modules-to-standalone). New applications should use the [Standalone](#standalone) approach. + ::: ### Overview @@ -405,9 +415,11 @@ export class AppModule {} ## Migrating from Modules to Standalone :::tip + Try our automated utility for migrating to standalone! Refer to the [standalone migration codemods](https://github.com/ionic-team/ionic-angular-standalone-codemods) for instructions on how to get started. All issues related to the migration utility should be filed on the linked repo. + ::: The Standalone option is newer than the Modules option, so developers may wish to switch during the development of their application. This guide details the steps needed to migrate. diff --git a/docs/angular/lifecycle.md b/docs/angular/lifecycle.md index e56f65dbbf0..a26dac31283 100644 --- a/docs/angular/lifecycle.md +++ b/docs/angular/lifecycle.md @@ -27,7 +27,9 @@ Ionic embraces the life cycle events provided by Angular. The two Angular events For more info on the Angular Component Life Cycle events, visit their [component lifecycle docs](https://angular.io/guide/lifecycle-hooks). :::note + Components that use `ion-nav` or `ion-router-outlet` should not use the `OnPush` change detection strategy. Doing so will prevent lifecycle hooks such as `ngOnInit` from firing. Additionally, asynchronous state changes may not render properly. + ::: ## Ionic Page Events diff --git a/docs/angular/navigation.md b/docs/angular/navigation.md index 7cceacf7191..d543120209d 100644 --- a/docs/angular/navigation.md +++ b/docs/angular/navigation.md @@ -168,7 +168,9 @@ import { LoginComponent } from './login.component'; ``` :::note + We're excluding some additional content and only including the necessary parts. + ::: Here, we have a typical Angular Module setup, along with a RouterModule import, but we're now using `forChild` and declaring the component in that setup. With this setup, when we run our build, we will produce separate chunks for both the app component, the login component, and the detail component. @@ -194,7 +196,9 @@ export class AppRoutingModule {} ``` :::tip + If you are using `routerLink`, `routerDirection`, or `routerAction` be sure to also import the `IonRouterLink` directive for Ionic components or the `IonRouterLinkWithHref` directive for `` elements. An example of this is available in the [Ionic Angular Build Options docs](./build-options.md#migrating-from-modules-to-standalone). + ::: To get started with standalone components [visit Angular's official docs](https://angular.io/guide/standalone-components). diff --git a/docs/angular/performance.md b/docs/angular/performance.md index de83b3af578..14ac3db954e 100644 --- a/docs/angular/performance.md +++ b/docs/angular/performance.md @@ -69,5 +69,7 @@ For more information, refer to the [Angular NgForOf change propagation documenta {/* cspell:enable */} :::note + Do you have a guide you'd like to share? Click the _Edit this page_ button below. + ::: diff --git a/docs/angular/pwa.md b/docs/angular/pwa.md index 370fc31962a..8f9a3e0b00e 100644 --- a/docs/angular/pwa.md +++ b/docs/angular/pwa.md @@ -25,11 +25,15 @@ ng add @angular/pwa Once this package has been added run `ionic build --prod` and the `www` directory will be ready to deploy as a PWA. :::note + By default, the `@angular/pwa` package comes with the Angular logo for the app icons. Be sure to update the manifest to use the correct app name and also replace the icons. + ::: :::note + Features like Service Workers and many JavaScript APIs (such as geolocation) require the app be hosted in a secure context. When deploying an app through a hosting service, be aware that HTTPS will be required to take full advantage of Service Workers. + ::: ## Service Worker configuration @@ -77,7 +81,9 @@ npm install -g firebase-tools ``` :::note + If it's the first time you use firebase-tools, login to your Google account with `firebase login` command. + ::: With the Firebase CLI installed, run `firebase init` within your Ionic project. The CLI prompts: @@ -91,7 +97,9 @@ Create a new Firebase project or select an existing one. **"What do you want to use as your public directory?"** Enter "www". :::note + Answering this next question will ensure that routing, hard reload, and deep linking work in the app: + ::: **Configure as a single-page app (rewrite all urls to /index.html)?"** Enter "Yes". diff --git a/docs/angular/quickstart.md b/docs/angular/quickstart.md index e2c74442b9b..a060df0e171 100644 --- a/docs/angular/quickstart.md +++ b/docs/angular/quickstart.md @@ -72,7 +72,9 @@ Your new app's directory will look like this: ``` :::info + All file paths in the examples below are relative to the project root directory. + ::: Let's walk through these files to understand the app's structure. @@ -175,7 +177,9 @@ And the template, in the `home.page.html` file, uses those components: This creates a page with a header and scrollable content area. The second header shows a [collapsible large title](/docs/api/title.md#collapsible-large-titles) that displays on iOS devices when at the top of the content, then condenses to show the smaller title in the first header when scrolling down. :::tip[Learn More] + For detailed information about Ionic layout components, refer to the [Header](/docs/api/header.md), [Toolbar](/docs/api/toolbar.md), [Title](/docs/api/title.md), and [Content](/docs/api/content.md) documentation. + ::: ## Add an Ionic Component @@ -257,7 +261,9 @@ import { RouterLink } from '@angular/router'; ``` :::info + Navigating can also be performed using Angular's Router service. Refer to the [Angular Navigation documentation](/docs/angular/navigation.md#navigating-to-different-routes) for more information. + ::: ## Add Icons to the New Page diff --git a/docs/angular/slides.md b/docs/angular/slides.md index 4754cd2f6b3..bbe68a742f2 100644 --- a/docs/angular/slides.md +++ b/docs/angular/slides.md @@ -14,7 +14,9 @@ import TabItem from '@theme/TabItem'; :::warning[Looking for `ion-slides`?] + `ion-slides` was deprecated in v6.0.0 and removed in v7.0.0. We recommend using the Swiper.js library directly. The migration process is detailed below. + ::: We recommend [Swiper.js](http://swiperjs.com/) if you need a modern touch slider component. Swiper 9 introduced [Swiper Element](https://swiperjs.com/element) as a replacement for its Angular component, so this guide will go over how to get Swiper Element set up in your Ionic Framework application. It will also go over any migration information you may need to move from `ion-slides` to Swiper Element. @@ -191,7 +193,9 @@ export class HomePage { ``` :::note + If you are using the Core version of Swiper and have installed additional modules, ensure that `IonicSlides` is the last module in the array. This will let it automatically customize the settings of modules such as Pagination, Scrollbar, Zoom, and more. + ::: ## Properties @@ -227,7 +231,9 @@ Below is a full list of property changes when going from `ion-slides` to Swiper | pager | Use the `pagination` property instead. | :::note + All properties available in Swiper Element can be found in the [Swiper API parameters documentation](https://swiperjs.com/swiper-api#parameters). + ::: ## Events @@ -276,7 +282,9 @@ Below is a full list of event name changes when going from `ion-slides` to Swipe | `ionSlidesDidLoad` | `swiperinit` | :::note + All events available in Swiper Element can be found in the [Swiper API events documentation](https://swiperjs.com/swiper-api#events) and should be lowercased and prefixed with the word `swiper`. + ::: ## Methods @@ -328,7 +336,9 @@ Below is a full list of method changes when going from `ion-slides` to Swiper El | `stopAutoplay()` | Use the `autoplay` property instead. | :::note + All methods and properties available on the Swiper instance can be found in the [Swiper API methods and properties documentation](https://swiperjs.com/swiper-api#methods-and-properties). + ::: ## Effects @@ -340,7 +350,9 @@ Effects such as Cube or Fade can be used in Swiper Element with no additional im ``` :::note + For more information on effects in Swiper, please refer to the [Swiper API fade effect documentation](https://swiperjs.com/swiper-api#fade-effect). + ::: ## Wrap Up diff --git a/docs/angular/storage.md b/docs/angular/storage.md index b7774589e80..85ff56b9ae8 100644 --- a/docs/angular/storage.md +++ b/docs/angular/storage.md @@ -14,7 +14,9 @@ sidebar_label: Storage There are a variety of options available for storing data within an Ionic application. It is best to choose options that best fit the needs of your application. A single application may have requirements that span multiple options. :::info + Some storage options involve third-party plugins or products. In such cases, we neither endorse nor support those plugins or products. We are mentioning them here for informational purposes only. + ::: Here are some common use cases and solutions: diff --git a/docs/angular/your-first-app.md b/docs/angular/your-first-app.md index e21a9458f36..e59d85e9b69 100644 --- a/docs/angular/your-first-app.md +++ b/docs/angular/your-first-app.md @@ -25,7 +25,9 @@ Here’s the finished app running on all 3 platforms: > :::note + Looking for the previous version of this guide that covered Ionic 4 and Cordova? Refer to the [Ionic 4 and Cordova guide](../developer-resources/guides/first-app-v4/intro.md). + ::: ## What We'll Build @@ -55,7 +57,9 @@ Download and install these right away to ensure an optimal Ionic development exp Run the following in the command line terminal to install the Ionic CLI (`ionic`), `native-run`, used to run native binaries on devices and simulators/emulators, and `cordova-res`, used to generate native app icons and splash screens: :::note + To open a terminal in Visual Studio Code, go to Terminal -> New Terminal. + ::: ```shell @@ -63,9 +67,11 @@ npm install -g @ionic/cli native-run cordova-res ``` :::note + The `-g` option means _install globally_. When packages are installed globally, `EACCES` permission errors can occur. Consider setting up npm to operate globally without elevated permissions. Refer to [Resolving Permission Errors](../developing/tips.md#resolving-permission-errors) for more information. + ::: ## Create an App diff --git a/docs/angular/your-first-app/2-taking-photos.md b/docs/angular/your-first-app/2-taking-photos.md index 92ffeeb2b36..3ce57cbd0b3 100644 --- a/docs/angular/your-first-app/2-taking-photos.md +++ b/docs/angular/your-first-app/2-taking-photos.md @@ -105,7 +105,9 @@ export class Tab2Page { ``` :::note + In a standalone app there is no global icon registry, so each icon you reference by name (like `camera`) must be registered with `addIcons`. Import the specific Ionic components a page uses from `@ionic/angular` and list them in the component's `imports` array. + ::: Then, open `tab2.page.html` and call the `addPhotoToGallery()` method when the FAB is tapped/clicked: diff --git a/docs/angular/your-first-app/4-loading-photos.md b/docs/angular/your-first-app/4-loading-photos.md index ad47f2bbdf1..f5ea15d6ed6 100644 --- a/docs/angular/your-first-app/4-loading-photos.md +++ b/docs/angular/your-first-app/4-loading-photos.md @@ -265,9 +265,11 @@ export class Tab2Page implements OnInit { ``` :::note + If you encounter broken image links or missing photos after following these steps, you may need to open your browser's dev tools and clear both [localStorage](https://developer.chrome.com/docs/devtools/storage/localstorage) and [IndexedDB](https://developer.chrome.com/docs/devtools/storage/indexeddb). In localStorage, look for domain `http://localhost:8100` and key `CapacitorStorage.photos`. In IndexedDB, find a store called "FileStorage". Your photos will have a key like `/DATA/123456789012.jpeg`. + ::: That’s it! We’ve built a complete Photo Gallery feature in our Ionic app that works on the web. Next up, we’ll transform it into a mobile app for iOS and Android! diff --git a/docs/angular/your-first-app/6-deploying-mobile.md b/docs/angular/your-first-app/6-deploying-mobile.md index 11bf04154b0..b7ad08e6920 100644 --- a/docs/angular/your-first-app/6-deploying-mobile.md +++ b/docs/angular/your-first-app/6-deploying-mobile.md @@ -47,7 +47,9 @@ ionic cap sync ## iOS Deployment :::important + To build an iOS app, you’ll need a Mac computer. + ::: Capacitor iOS apps are configured and managed through Xcode (Apple’s iOS/Mac IDE), with dependencies managed by [CocoaPods](https://cocoapods.org/). Before running this app on an iOS device, there's a couple of steps to complete. diff --git a/docs/angular/your-first-app/7-live-reload.md b/docs/angular/your-first-app/7-live-reload.md index 7a697854dcc..2d3a9462cf8 100644 --- a/docs/angular/your-first-app/7-live-reload.md +++ b/docs/angular/your-first-app/7-live-reload.md @@ -217,7 +217,9 @@ button img { Tap on a photo again and choose the “Delete” option. The photo is deleted! Implemented much faster using Live Reload. 💪 :::note + Remember, you can find the [complete source code for this app](https://github.com/ionic-team/tutorial-photo-gallery-angular) on GitHub. + ::: In the final portion of this tutorial, we’ll walk you through the basics of the Appflow product used to build and deploy your application to users' devices. diff --git a/docs/angular/zoneless.md b/docs/angular/zoneless.md index bbcb5031ab5..e29752c4499 100644 --- a/docs/angular/zoneless.md +++ b/docs/angular/zoneless.md @@ -27,7 +27,9 @@ You do not need to change these. Angular schedules change detection for them in - Navigation, route transitions, and tab switching. :::note[Angular 22] + Angular 22 also makes `OnPush` the default change detection strategy. Under `OnPush`, synchronous state set as a plain field (including in the lifecycle hooks above) no longer re-renders on its own, even though Ionic notifies Angular. Signals still update the view. For the migration path, refer to the [OnPush Change Detection section of the Ionic 9 upgrade guide](/docs/updating/9-0.md#onpush-change-detection-on-angular-22). + ::: ## What needs a notification diff --git a/docs/api/accordion.md b/docs/api/accordion.md index 202379e6c81..7fcbc66ac7c 100644 --- a/docs/api/accordion.md +++ b/docs/api/accordion.md @@ -40,9 +40,11 @@ import Toggle from '@site/static/usage/v9/accordion/toggle/index.mdx'; ## Listen for Accordion State Changes :::caution + Most `ionChange` events emitted by other components such as [Input](./input) and [Textarea](./textarea) bubble. As a result, these events will bubble up and cause your `ionChange` listener on the Accordion Group to fire if the associated components are used inside of an Accordion. When using other components that emit `ionChange` inside of Accordion it is recommended to have the `ionChange` callback on Accordion Group check the `target` key on the event passed to the callback to verify that `ionChange` is coming from the Accordion Group and not any descendants. + ::: Developers can listen for the `ionChange` event to be notified when accordions expand or collapse. diff --git a/docs/api/alert.md b/docs/api/alert.md index 68595aeed75..e86a49deb92 100644 --- a/docs/api/alert.md +++ b/docs/api/alert.md @@ -109,7 +109,9 @@ import Customization from '@site/static/usage/v9/alert/customization/index.mdx'; :::note + If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. + ::: ## Accessibility diff --git a/docs/api/badge.md b/docs/api/badge.md index 11ea88e3965..8c2ea9e3d40 100644 --- a/docs/api/badge.md +++ b/docs/api/badge.md @@ -34,7 +34,9 @@ import Basic from '@site/static/usage/v9/badge/basic/index.mdx'; Badges can be added inside a tab button, often used to indicate notifications or highlight additional items associated with the element. :::info + Empty badges are only available for `md` mode. + ::: import InsideTabBar from '@site/static/usage/v9/badge/inside-tab-bar/index.mdx'; diff --git a/docs/api/button.md b/docs/api/button.md index 6ab8a6e171b..4c0bdeb3769 100644 --- a/docs/api/button.md +++ b/docs/api/button.md @@ -92,7 +92,9 @@ There are many cases where a button's text content may overflow the container. I The button text does not automatically wrap to the next line when the text is too long to fit. In order to make the text wrap, the `ion-text-wrap` class can be added, which will set the `white-space` property to `"normal"`. This will become the default in a future major release. :::info + The `max-width` style is set on the button below for demo purposes only. Text wrapping will work with a dynamic button width. + ::: import TextWrapping from '@site/static/usage/v9/button/text-wrapping/index.mdx'; diff --git a/docs/api/checkbox.md b/docs/api/checkbox.md index ccb11a0d5db..db7a5c4e82c 100644 --- a/docs/api/checkbox.md +++ b/docs/api/checkbox.md @@ -42,7 +42,9 @@ import LabelPlacement from '@site/static/usage/v9/checkbox/label-placement/index Developers can use the `alignment` property to control how the label and control are aligned on the cross axis. This property mirrors the flexbox `align-items` property. :::note + Stacked checkboxes can be aligned using the `alignment` property. This can be useful when the label and control need to be centered horizontally. + ::: import Alignment from '@site/static/usage/v9/checkbox/alignment/index.mdx'; @@ -58,7 +60,9 @@ import Justify from '@site/static/usage/v9/checkbox/justify/index.mdx'; :::note + `ion-item` is only used in the demos to emphasize how `justify` works. It is not needed in order for `justify` to function correctly. + ::: ## Indeterminate Checkboxes diff --git a/docs/api/datetime.md b/docs/api/datetime.md index 1257482a0bd..dae9ad974f1 100644 --- a/docs/api/datetime.md +++ b/docs/api/datetime.md @@ -98,7 +98,9 @@ always in the 24-hour format, so `00` is `12am` on a 12-hour clock, `13` means `1pm`, and `23` means `11pm`. :::note + While seconds, milliseconds, and time zone can be specified using the ISO 8601 datetime format, `ion-datetime` does not provide an interface for second, millisecond, and time zone selection. Any second, millisecond, or time zone values provided will be ignored. + ::: ## Basic Usage @@ -153,7 +155,9 @@ The following example shows how to set the locale to Spanish (Spain). :::note + The time label is not automatically localized. Refer to [Time Label](#time-label) for more information. + ::: ### Hour Cycle @@ -170,7 +174,9 @@ There are 4 primary hour cycle types: | `'h24'` | Hour system using 1–24; corresponds to 'k' in pattern. The 24 hour clock, with midnight starting at 24:00. | :::note + Source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/hourCycle + ::: There may be scenarios where you need to have more control over which hour cycle is used. This is where the `hourCycle` property can help. @@ -200,7 +206,9 @@ For example, if you wanted to use a 12 hour cycle with the `en-GB` locale, you c :::note + Be sure to check the [Browser Compatibility Chart](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale#browser_compatibility) for `Intl.Locale` before using it in your app. + ::: ## Presentation @@ -262,7 +270,9 @@ If the `showAdjacentDays` property is set to `true`, days from the previous and The calendar view always displays 6 rows when `showAdjacentDays` is enabled, so days from the previous or next month will be shown as needed to fill the grid. For example, even if a month starts on the first day of the week and ends within the fifth row, days from the next month will appear at the end to complete the sixth row. :::note + This property is only supported when using `presentation="date"` and `preferWheel="false"`. + ::: @@ -272,7 +282,9 @@ This property is only supported when using `presentation="date"` and `preferWhee If the `multiple` property is set to `true`, multiple dates can be selected from the calendar picker. Clicking a selected date will deselect it. :::note + This property is only supported when using `presentation="date"` and `preferWheel="false"`. + ::: @@ -332,7 +344,9 @@ When specifying colors, any valid CSS color format can be used. This includes he To maintain a consistent user experience, the style of selected date(s) will always override custom highlights. :::note + This property is only supported when `preferWheel="false"`, and using a `presentation` of either `"date"`, `"date-time"`, or `"time-date"`. + ::: ### Using Array @@ -362,7 +376,9 @@ The benefit of this approach is that every component, not just `ion-datetime`, c The datetime header manages the content for the `title` slot and the selected date. :::note + The selected date will not render if `preferWheel` is set to `true`. + ::: @@ -380,7 +396,9 @@ The header can be styled using CSS shadow parts. The calendar days in a grid-style `ion-datetime` can be styled using CSS shadow parts. :::note + The example below selects the day 2 days ago, unless that day is in the previous month, then it selects a day 2 days in the future. This is done for demo purposes in order to show how to apply custom styling to all days, the current day, and the selected day. + ::: diff --git a/docs/api/img.md b/docs/api/img.md index 5353ab0166e..aa9adb8daa8 100644 --- a/docs/api/img.md +++ b/docs/api/img.md @@ -22,7 +22,9 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; :::warning[Deprecated] + `ion-img` is deprecated and will be removed in Ionic 10. Use a native `` tag with [loading="lazy"](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#loading) instead. Refer to the [migration guide](../updating/9-0.md#img) for details on replacing events and styling. + ::: Img is a tag that will lazily load an image whenever the tag is in the viewport. This is extremely useful when generating a large list as images are only loaded when they're visible. The component uses [Intersection Observer](https://caniuse.com/#feat=intersectionobserver) internally, which is supported in most modern browsers, but falls back to a `setTimeout` when it is not supported. diff --git a/docs/api/input-otp.md b/docs/api/input-otp.md index 4a41de5e404..75050ef0cf2 100644 --- a/docs/api/input-otp.md +++ b/docs/api/input-otp.md @@ -113,11 +113,13 @@ The `pattern` property enables custom validation using regular expressions. It a The component will prevent users from entering any characters that don't match the specified pattern. Developers can override these defaults by providing their own pattern string to match specific input requirements. :::tip + When using a custom `pattern`, remember that the `type` property controls which keyboard appears on mobile devices: - Use `type="number"` for numeric-only patterns to show the numeric keyboard - Use `type="text"` for patterns that include letters to show the alphanumeric keyboard - ::: + +::: import Pattern from '@site/static/usage/v9/input-otp/pattern/index.mdx'; @@ -130,7 +132,9 @@ import Pattern from '@site/static/usage/v9/input-otp/pattern/index.mdx'; The `color` property changes the color palette for input boxes. For `outline` fills, this property changes the caret color, highlight color and border color. For `solid` fills, this property changes the caret color and highlight color. :::note + The `color` property does _not_ change the text color of the input OTP. For that, use the [`--color` CSS property](#css-custom-properties-1). + ::: import Colors from '@site/static/usage/v9/input-otp/theming/colors/index.mdx'; diff --git a/docs/api/input-password-toggle.md b/docs/api/input-password-toggle.md index e1a13ed6273..b7f918cc635 100644 --- a/docs/api/input-password-toggle.md +++ b/docs/api/input-password-toggle.md @@ -26,9 +26,11 @@ The InputPasswordToggle component is a companion component to [Input](./input). ## Basic Usage :::info + InputPasswordToggle must be used with an [Input](./input) that has its [`type`](./input/#type) property set to either `'text'` or `'password'`. Using any other `type` will cause a warning to be logged. + ::: import Basic from '@site/static/usage/v9/input-password-toggle/basic/index.mdx'; diff --git a/docs/api/input.md b/docs/api/input.md index c20b8c39146..f7a3af962e9 100644 --- a/docs/api/input.md +++ b/docs/api/input.md @@ -86,7 +86,9 @@ Material Design offers filled styles for an input. The `fill` property on the in Filled inputs can be used on iOS by setting the input's `mode` to `md`. :::warning + Inputs that use `fill` should not be used in an `ion-item` due to styling conflicts between the components. + ::: import Fill from '@site/static/usage/v9/input/fill/index.mdx'; @@ -156,9 +158,11 @@ The `start` and `end` slots can be used to place icons, buttons, or prefix/suffi Note that this feature is considered experimental because it relies on a simulated version of [Web Component slots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots). As a result, the simulated behavior may not exactly match the native slot behavior. :::note + In most cases, [Icon](./icon.md) components placed in these slots should have `aria-hidden="true"`. Refer to the [Icon accessibility docs](https://ionicframework.com/docs/api/icon#accessibility) for more information. If slot content is meant to be interacted with, it should be wrapped in an interactive element such as a [Button](./button.md). This ensures that the content can be tabbed to. + ::: import StartEndSlots from '@site/static/usage/v9/input/start-end-slots/index.mdx'; @@ -172,7 +176,9 @@ import StartEndSlots from '@site/static/usage/v9/input/start-end-slots/index.mdx Setting the `color` property changes the color palette for each input. On `ios` mode, this property changes the caret color. On `md` mode, this property changes the caret color and the highlight/underline color. :::note + The `color` property does _not_ change the text color of the input. For that, use the [`--color` CSS property](#css-custom-properties-1). + ::: import Colors from '@site/static/usage/v9/input/theming/colors/index.mdx'; diff --git a/docs/api/loading.md b/docs/api/loading.md index bf37ae00fbe..c8453e4740a 100644 --- a/docs/api/loading.md +++ b/docs/api/loading.md @@ -62,7 +62,9 @@ import Theming from '@site/static/usage/v9/loading/theming/index.mdx'; :::note + `ion-loading` is presented at the root of your application, so we recommend placing any `ion-loading` styles in a global stylesheet. + ::: ## Accessibility diff --git a/docs/api/modal.md b/docs/api/modal.md index 57ca9fdd543..e68e3682909 100644 --- a/docs/api/modal.md +++ b/docs/api/modal.md @@ -58,7 +58,9 @@ When entering data into a modal, it is often desirable to have a way of preventi There are two different ways of using the `canDismiss` property: setting a boolean value or setting a callback function. :::note + Note: When using a sheet modal, `canDismiss` will not be checked on swipe if there is no `0` breakpoint set. However, it will still be checked when pressing `Esc` or the hardware back button. + ::: ### Setting a boolean value @@ -112,7 +114,9 @@ The `presentingElement` property accepts a reference to the element that should The `canDismiss` property can be used to control whether or not the card modal can be swiped to close. :::note + The card display style is only available on iOS. + ::: import CardExample from '@site/static/usage/v9/modal/card/basic/index.mdx'; @@ -122,7 +126,9 @@ import CardExample from '@site/static/usage/v9/modal/card/basic/index.mdx'; ## Sheet Modal :::info + [Content](./content) should be used inside of the sheet modal if you want your modal content to be scrollable. + ::: Developers can create a sheet modal effect similar to the drawer components available in maps applications. To create a sheet modal, developers need to set the `breakpoints` and `initialBreakpoint` properties on `ion-modal`. @@ -174,11 +180,15 @@ import SheetScrollingContentExample from '@site/static/usage/v9/modal/sheet/expa Modals are presented at the root of your application so they overlay your entire app. This behavior applies to both inline modals and modals presented from a controller. As a result, custom modal styles can not be scoped to a particular component as they will not apply to the modal. Instead, styles must be applied globally. For most developers, placing the custom styles in `global.css` is sufficient. :::note + If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information. + ::: :::note + `ion-modal` works under the assumption that stacked modals are the same size. As a result, each subsequent modal will have no box shadow and a backdrop opacity of `0`. This is to avoid the effect of shadows and backdrops getting darker with each added modal. This can be changed by setting the `--box-shadow` and `--backdrop-opacity` CSS variables: + ::: ``` diff --git a/docs/api/nav.md b/docs/api/nav.md index 54a8a4331b1..9d948e1996d 100644 --- a/docs/api/nav.md +++ b/docs/api/nav.md @@ -26,7 +26,9 @@ Nav is a standalone component for loading arbitrary components and pushing new c Unlike Router Outlet, Nav is not tied to a particular router. This means that if we load a Nav component, and push other components to the stack, they will not affect the app's overall router. For example, you should not push a new component to `ion-nav` and expect the URL to update. This fits use cases where you could have a modal, which needs its own sub-navigation, without making it tied to the apps URL. :::note + `ion-nav` is not meant to be used for routing. Instead, refer to the routing guides for [Angular](../angular/navigation), [React](../react/navigation), and [Vue](../vue/navigation), or [`ion-router`](./router) for vanilla JavaScript projects. + ::: ## Using NavLink diff --git a/docs/api/picker.md b/docs/api/picker.md index bec644c08cd..9d68b8d6f69 100644 --- a/docs/api/picker.md +++ b/docs/api/picker.md @@ -65,7 +65,9 @@ Picker supports navigation using a screen reader by implementing the [`slider` r | Double Tap and Slide Up/Down | Adjust the selected option in the Picker Column. Can be used as an alternative to swiping up and down. | :::caution + The Swipe Up and Swipe Down gestures rely on the correct key events being synthesized as noted on the [`slider` documentation](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/slider_role). [Chromium-based browsers do not synthesize keyboard events correctly](https://issues.chromium.org/issues/40816094), but the "Double Tap and Slide Up/Down" gesture can be used as an alternative until this has been implemented in Chromium-based browsers. + ::: ### Keyboard Interactions diff --git a/docs/api/popover.md b/docs/api/popover.md index 0f8515a226f..7e648d732d6 100644 --- a/docs/api/popover.md +++ b/docs/api/popover.md @@ -54,7 +54,9 @@ Since the component you passed in needs to be created when the popover is presen A trigger for an inline `ion-popover` is the element that will open a popover when interacted with. The interaction behavior can be customized by setting the `trigger-action` property. Note that `trigger-action="context-menu"` will prevent your system's default context menu from opening. :::note + Triggers are not applicable when using the `popoverController` because the `ion-popover` is not created ahead of time. + ::: import InlineTrigger from '@site/static/usage/v9/popover/presenting/inline-trigger/index.mdx'; @@ -94,7 +96,9 @@ import ControllerExample from '@site/static/usage/v9/popover/presenting/controll Popovers are presented at the root of your application so they overlay your entire app. This behavior applies to both inline popovers and popovers presented from a controller. As a result, custom popover styles can not be scoped to a particular component as they will not apply to the popover. Instead, styles must be applied globally. For most developers, placing the custom styles in `global.css` is sufficient. :::note + If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. + ::: import Styling from '@site/static/usage/v9/popover/customization/styling/index.mdx'; @@ -142,7 +146,9 @@ When using `ion-popover` inline, you can nested popovers to create nested dropdo You can use the `dismissOnSelect` property to automatically close the popover when the popover content has been clicked. This behavior does not apply when clicking a trigger element for another popover. :::note + Nested popovers cannot be created when using the `popoverController` because the popover is automatically added to the root of your application when the `create` method is called. + ::: import NestedPopover from '@site/static/usage/v9/popover/nested/index.mdx'; diff --git a/docs/api/radio.md b/docs/api/radio.md index 22445b577bc..7807f0333e1 100644 --- a/docs/api/radio.md +++ b/docs/api/radio.md @@ -60,7 +60,9 @@ import UsingComparewith from '@site/static/usage/v9/radio/using-comparewith/inde Developers can use the `alignment` property to control how the label and control are aligned on the cross axis. This property mirrors the flexbox `align-items` property. :::note + Stacked radios can be aligned using the `alignment` property. This can be useful when the label and control need to be centered horizontally. + ::: import Alignment from '@site/static/usage/v9/radio/alignment/index.mdx'; @@ -76,7 +78,9 @@ import Justify from '@site/static/usage/v9/radio/justify/index.mdx'; :::note + `ion-item` is only used in the demos to emphasize how `justify` works. It is not needed in order for `justify` to function correctly. + ::: ## Deselecting Radios diff --git a/docs/api/reorder.md b/docs/api/reorder.md index 0d6d7c2dc1a..8dcc9e42ed1 100644 --- a/docs/api/reorder.md +++ b/docs/api/reorder.md @@ -88,7 +88,9 @@ import ReorderStartEndEvents from '@site/static/usage/v9/reorder/reorder-start-e The `ionReorderMove` event is emitted continuously during the reorder gesture as the user drags an item. The event includes the `from` and `to` indices of the item. Unlike `ionReorderEnd`, the `from` index in this event represents the last known position of the item (which updates as the item moves), while the `to` index represents its current position. If the item has not changed position since the last event, the `from` and `to` indices will be the same. This event is useful for tracking position changes during the drag operation. For example, the ranking or numbering of items can be updated in real-time as they are being dragged to maintain a logical ascending order. :::warning + Do not call the `complete` method during the `ionReorderMove` event as it can break the gesture. + ::: import ReorderMoveEvent from '@site/static/usage/v9/reorder/reorder-move-event/index.mdx'; diff --git a/docs/api/route-redirect.md b/docs/api/route-redirect.md index 3da89eeedd3..2e92267266a 100644 --- a/docs/api/route-redirect.md +++ b/docs/api/route-redirect.md @@ -22,7 +22,9 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; A route redirect can only be used with an `ion-router` as a direct child of it. :::note + Note: this component should only be used with vanilla and Stencil JavaScript projects. For Angular projects, use [`ion-router-outlet`](router-outlet.md) and the Angular router. + ::: The route redirect has two configurable properties: diff --git a/docs/api/route.md b/docs/api/route.md index 6594fce758f..5030e8d6896 100644 --- a/docs/api/route.md +++ b/docs/api/route.md @@ -25,7 +25,9 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; The route component takes a component and renders it when the Browser URL matches the url property. :::note + Note: this component should only be used with vanilla and Stencil JavaScript projects. For Angular projects, use [`ion-router-outlet`](router-outlet.md) and the Angular router. + ::: ## Navigation Hooks diff --git a/docs/api/router-link.md b/docs/api/router-link.md index e9e67014478..d301c854215 100644 --- a/docs/api/router-link.md +++ b/docs/api/router-link.md @@ -24,7 +24,9 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; The router link component is used for navigating to a specified link. Similar to the browser's anchor tag, it can accept a href for the location, and a direction for the transition animation. :::note + Note: this component should only be used with vanilla and Stencil JavaScript projects. For Angular projects, use an `` and `routerLink` with the Angular router. + ::: Refer to the [Router](./router) documentation for more information. diff --git a/docs/api/router.md b/docs/api/router.md index f6f6072335c..72355b4c9e2 100644 --- a/docs/api/router.md +++ b/docs/api/router.md @@ -22,7 +22,9 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; The router is a component for handling routing inside vanilla and Stencil JavaScript projects. :::note + Note: This component should only be used with vanilla and Stencil JavaScript projects. See the routing guides for [Angular](../angular/navigation), [React](../react/navigation), and [Vue](../vue/navigation) for framework-specific routing solutions. + ::: Apps should have a single `ion-router` component in the codebase. diff --git a/docs/api/segment.md b/docs/api/segment.md index 68f0d2f67fe..ca0a177ad10 100644 --- a/docs/api/segment.md +++ b/docs/api/segment.md @@ -55,9 +55,11 @@ when the segment is active. With this approach, each segment's content can be sw to reflect the currently visible content. :::warning + If no initial `value` is assigned to the `ion-segment` when using swipeable segments, the segment will default to the value of the first segment button. Segment buttons cannot be disabled when used with swipeable segments. + ::: import Swipeable from '@site/static/usage/v9/segment/swipeable/index.mdx'; diff --git a/docs/api/select.md b/docs/api/select.md index 1539111137a..891619cc8c7 100644 --- a/docs/api/select.md +++ b/docs/api/select.md @@ -156,7 +156,9 @@ Material Design offers filled styles for a select. The `fill` property on the se Filled selects can be used on iOS by setting the select's `mode` to `md`. :::warning + Selects that use `fill` should not be used in an `ion-item` due to styling conflicts between the components. + ::: import FillExample from '@site/static/usage/v9/select/fill/index.mdx'; @@ -194,9 +196,11 @@ import InterfaceOptionsExample from '@site/static/usage/v9/select/customization/ The `start` and `end` slots can be used to place icons, buttons, or prefix/suffix text on either side of the select. If the slot content is clicked, the select will not open. :::note + In most cases, [Icon](./icon.md) components placed in these slots should have `aria-hidden="true"`. Refer to the [Icon accessibility docs](https://ionicframework.com/docs/api/icon#accessibility) for more information. If slot content is meant to be interacted with, it should be wrapped in an interactive element such as a [Button](./button.md). This ensures that the content can be tabbed to. + ::: import StartEndSlots from '@site/static/usage/v9/select/start-end-slots/index.mdx'; @@ -206,7 +210,9 @@ import StartEndSlots from '@site/static/usage/v9/select/start-end-slots/index.md ## Rich Content Options :::important + Rich content in select options is disabled by default. Set [`innerHTMLTemplatesEnabled`](/docs/developing/config.md#ionicconfig) to `true` in your [global Ionic config](/docs/developing/config.md#global-config). Markup inside options is treated as plain text when it is disabled. Refer to [Security](/docs/techniques/security.md) for sanitization guidance when enabling custom HTML. + ::: In addition to single text labels, [Select Options](./select-option.md) can include HTML rich content in the select interface. Elements added inside of an option without a named slot will go into the default slot. The `start` and `end` slots will place elements on either side of the default slot. The `description` attribute can be used for additional supporting text displayed under the label. diff --git a/docs/api/split-pane.md b/docs/api/split-pane.md index d83846a6e3a..b3255a2fced 100644 --- a/docs/api/split-pane.md +++ b/docs/api/split-pane.md @@ -29,7 +29,9 @@ If the device's screen width is below a certain size, the split pane will collap ## Basic Usage :::note + This demo sets the `when` property to `'xs'` so the split pane always shows up. Your Ionic application does not need this if you want the split pane to collapse on smaller viewports. Refer to [Setting Breakpoints](#setting-breakpoints) for more information. + ::: import Basic from '@site/static/usage/v9/split-pane/basic/index.mdx'; diff --git a/docs/api/tab-bar.md b/docs/api/tab-bar.md index 0b4de33585a..5fef57e2bfd 100644 --- a/docs/api/tab-bar.md +++ b/docs/api/tab-bar.md @@ -141,7 +141,9 @@ export const TabBarExample: React.FC = () => ( Badges can be added inside a tab button, often used to indicate notifications or highlight additional items associated with the element. :::info + Empty badges are only available for `md` mode. + ::: import InsideTabBar from '@site/static/usage/v9/badge/inside-tab-bar/index.mdx'; diff --git a/docs/api/tab.md b/docs/api/tab.md index 745a6334c2d..2ba6e5a86ce 100644 --- a/docs/api/tab.md +++ b/docs/api/tab.md @@ -24,9 +24,11 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; The tab component is a child component of [tabs](tabs.md). Each tab can contain a top level navigation stack for an app or a single view. An app can have many tabs, all with their own independent navigation. :::note + Angular, React, and Vue can only use this component when the `ion-tabs` component is configured for [basic usage](./tabs.md#basic-usage). When setting up tabs with routing, the `ion-tab` component cannot be used. In JavaScript, this component can be used with the `ion-tabs` component configured for either [basic usage](./tabs.md#basic-usage) or [usage with router](./tabs.md#usage-with-router). + ::: Refer to the [tabs documentation](tabs.md) for more details on configuring tabs. diff --git a/docs/api/textarea.md b/docs/api/textarea.md index 889bca5b985..f1c7ee575f5 100644 --- a/docs/api/textarea.md +++ b/docs/api/textarea.md @@ -74,7 +74,9 @@ Material Design offers filled styles for a textarea. The `fill` property on the Filled textareas can be used on iOS by setting the textarea's `mode` to `md`. :::warning + Textareas that use `fill` should not be used in an `ion-item` due to styling conflicts between the components. + ::: import Fill from '@site/static/usage/v9/textarea/fill/index.mdx'; @@ -122,9 +124,11 @@ The `start` and `end` slots can be used to place icons, buttons, or prefix/suffi Note that this feature is considered experimental because it relies on a simulated version of [Web Component slots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots). As a result, the simulated behavior may not exactly match the native slot behavior. :::note + In most cases, [Icon](./icon.md) components placed in these slots should have `aria-hidden="true"`. Refer to the [Icon accessibility docs](https://ionicframework.com/docs/api/icon#accessibility) for more information. If slot content is meant to be interacted with, it should be wrapped in an interactive element such as a [Button](./button.md). This ensures that the content can be tabbed to. + ::: import StartEndSlots from '@site/static/usage/v9/textarea/start-end-slots/index.mdx'; diff --git a/docs/api/toggle.md b/docs/api/toggle.md index 8567f2eae99..0fbd0538492 100644 --- a/docs/api/toggle.md +++ b/docs/api/toggle.md @@ -58,7 +58,9 @@ import LabelPlacement from '@site/static/usage/v9/toggle/label-placement/index.m Developers can use the `alignment` property to control how the label and control are aligned on the cross axis. This property mirrors the flexbox `align-items` property. :::note + Stacked toggles can be aligned using the `alignment` property. This can be useful when the label and control need to be centered horizontally. + ::: import Alignment from '@site/static/usage/v9/toggle/alignment/index.mdx'; diff --git a/docs/cli.md b/docs/cli.md index 2f7fa27d876..879738c919e 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -32,9 +32,11 @@ $ ionic --help ``` :::note + Be sure to run `ionic --help` in your project directory. For some commands, such as `ionic serve`, the help documentation is contextual to the type of your project, e.g. React vs Angular. + ::: ## Architecture diff --git a/docs/cli/configuration.md b/docs/cli/configuration.md index 708c5388f03..cf367d940c4 100644 --- a/docs/cli/configuration.md +++ b/docs/cli/configuration.md @@ -124,9 +124,11 @@ module.exports = function (ctx) { The Ionic CLI supports a multi-app configuration setup, which involves multiple Ionic apps and shared code within a single repository, or [monorepo](../reference/glossary.md#monorepo). :::note + These docs give an overview of the multi-app feature of the Ionic CLI, but don't really go into details for each framework. If you're using Angular, please refer to [the Angular monorepo guide](https://github.com/ionic-team/ionic-cli/wiki/Angular-Monorepo) for examples. + ::: ### Setup Steps @@ -207,7 +209,9 @@ $ ionic start "My New App" --no-deps If an app was created in a way other than `ionic start`, for example by using a prebuilt template, use `ionic init` to register the existing app with the multi-app project. :::note + Make sure the app doesn't have an existing `ionic.config.json`. + ::: ```shell diff --git a/docs/cli/livereload.md b/docs/cli/livereload.md index 43fa4b1da76..fe4d0c37438 100644 --- a/docs/cli/livereload.md +++ b/docs/cli/livereload.md @@ -22,7 +22,9 @@ $ ionic capacitor run android -l --external ``` :::note + Remember, with the `--external` option, others on your Wi-Fi network will be able to access your app. + ::: ### Cordova @@ -50,7 +52,9 @@ ionic cordova run ios -l --external ``` :::note + Remember, with the `--external` option, others on your Wi-Fi network will be able to access your app. + ::: ## Tips diff --git a/docs/deployment/app-store.md b/docs/deployment/app-store.md index b4c3120479e..80417f8d784 100644 --- a/docs/deployment/app-store.md +++ b/docs/deployment/app-store.md @@ -84,7 +84,9 @@ This will generate the minified code for the web portion of an app and copy it o From here, open the `.xcworkspace` file in `./platforms/ios/` to start Xcode. :::tip + You can also have a release build generated automatically by using the `--release` flag. + ::: @@ -119,5 +121,7 @@ An app can be updated by either submitting a new version to Apple, or by using a With Live Updates, app changes can be pushed in realtime directly to users from the Appflow dashboard, without waiting for App Store approvals. :::note + In order for the iOS App Store to accept the updated build, the config.xml file will need to be edited to increment the version value, then rebuild the app for release following the same instructions above. + ::: diff --git a/docs/deployment/play-store.mdx b/docs/deployment/play-store.mdx index e87d0ce29d0..800e8c9a0b7 100644 --- a/docs/deployment/play-store.mdx +++ b/docs/deployment/play-store.mdx @@ -91,7 +91,9 @@ To opt into app signing, you'll need to upload the app signing key used to sign ![The opt-in options for Play App Signing in the Google Play Console.](https://blog.ionicframework.com/wp-content/uploads/2021/12/existingapps-optin.png 'Google Play Console Opt-in to Play App Signing') :::tip + With smaller app sizes, improved performance, and enhanced security, the AAB binary format is a win for app developers and users alike. If you have an existing Android app using the APK format, consider migrating to AAB to take advantage of all the great features it provides. + ::: @@ -106,7 +108,9 @@ keytool -genkey -v -keystore my-release-key.keystore -alias alias_name -keyalg R Once that command has been ran and its prompts have been answered a file called `my-release-key.keystore` will be created in the current directory. :::warning + Save this file and keep it somewhere safe. If it is lost the Google Play Store will not accept updates for this app! + ::: To sign the unsigned APK, run the jarsigner tool which is also included in the Android SDK: @@ -135,7 +139,9 @@ Now that a release AAB/APK has been generated, a Play Store listing can be writt To start, visit the [Google Play Store Developer Console](https://play.google.com/apps/publish) and create a new developer account. :::note + Making a developer account with Google Play costs $25 USD. + ::: Once a developer account has been created, go ahead and click the `Create an Application` @@ -153,14 +159,18 @@ As an app evolves, it will need to be updated with new features and fixes. An ap :::note + In order for the Google Play Store to accept updated AAB/APK, the `android/app/build.gradle` file will need to be edited to increment the `versionCode` value, then rebuild the app for release following the instructions above. + ::: :::note + In order for the Google Play Store to accept updated AAB/APK, the config.xml file will need to be edited to increment the version value, then rebuild the app for release following the instructions above. + ::: diff --git a/docs/developer-resources/guides/first-app-v4/intro.md b/docs/developer-resources/guides/first-app-v4/intro.md index d7e9e1112ba..b8a3577e95f 100644 --- a/docs/developer-resources/guides/first-app-v4/intro.md +++ b/docs/developer-resources/guides/first-app-v4/intro.md @@ -28,9 +28,11 @@ npm install -g @ionic/cli cordova ``` :::note + The `-g` option means _install globally_. When packages are installed globally, `EACCES` permission errors can occur. Consider setting up npm to operate globally without elevated permissions. Refer to [Resolving Permission Errors](../../../developing/tips.md#resolving-permission-errors) for more information. + ::: ## Create an App diff --git a/docs/developing/config/per-platform/index.md b/docs/developing/config/per-platform/index.md index 00f66e27ddf..4b49ceac71d 100644 --- a/docs/developing/config/per-platform/index.md +++ b/docs/developing/config/per-platform/index.md @@ -14,9 +14,11 @@ import TabItem from '@theme/TabItem'; :::note + Since the config is set at runtime, you will not have access to the Platform Dependency Injection. Instead, you can use the underlying functions that the provider uses directly. Refer to the [Angular Platform Documentation](../angular/platform) for the types of platforms you can detect. + ::: ```ts title="app.module.ts" @@ -41,9 +43,11 @@ import { isPlatform, IonicModule } from '@ionic/angular/lazy'; :::note + Since the config is set at runtime, you will not have access to the Platform Dependency Injection. Instead, you can use the underlying functions that the provider uses directly. Refer to the [Angular Platform Documentation](../angular/platform) for the types of platforms you can detect. + ::: ```ts title="main.ts" @@ -63,7 +67,9 @@ bootstrapApplication(AppComponent, { :::note + Refer to the [React Platform Documentation](../react/platform) for the types of platforms you can detect. + ::: ```tsx title="App.tsx" @@ -78,7 +84,9 @@ setupIonicReact({ :::note + Refer to the [Vue Platform Documentation](../vue/platform) for the types of platforms you can detect. + ::: ```ts title="main.ts" diff --git a/docs/developing/hardware-back-button.md b/docs/developing/hardware-back-button.md index ad4801de2c0..1d4a1baabea 100644 --- a/docs/developing/hardware-back-button.md +++ b/docs/developing/hardware-back-button.md @@ -16,7 +16,9 @@ import TabItem from '@theme/TabItem'; The hardware back button is found on most Android devices. In native applications it can be used to close modals, navigate to the previous view, exit an app, and more. By default in Ionic, when the back button is pressed, the current view will be popped off the navigation stack, and the previous view will be displayed. If no previous view exists in the navigation stack, nothing will happen. This guide will show how to customize the behavior of the hardware back button. :::note + The hardware back button refers to the physical back button on an Android device and should not be confused with either the browser back button or `ion-back-button`. The information in this guide only applies to Android devices. + ::: ## Overview @@ -47,7 +49,9 @@ Chrome has support for Close Watcher starting in [Chrome 120](https://developer. For complete hardware back button support, we recommend using Capacitor or Cordova. :::note + The `ionBackButton` event will not be emitted when running an app in a browser or as a PWA if Close Watcher is unsupported or `experimentalCloseWatcher` is `false`. + ::: ## Basic Usage diff --git a/docs/developing/keyboard.md b/docs/developing/keyboard.md index 3c402f41b58..f1c52a28529 100644 --- a/docs/developing/keyboard.md +++ b/docs/developing/keyboard.md @@ -32,7 +32,9 @@ import Inputmode from '@site/static/usage/v9/keyboard/inputmode/index.mdx'; :::note + The `inputmode` attribute is supported on devices running Chrome 66+ and iOS Safari 12.2+: https://caniuse.com/#search=inputmode + ::: ## enterkeyhint @@ -50,7 +52,9 @@ import Enterkeyhint from '@site/static/usage/v9/keyboard/enterkeyhint/index.mdx' :::note + The `enterkeyhint` attribute is supported on devices running Chrome 77+ and iOS Safari 13.4+. + ::: ## Dark Mode @@ -171,5 +175,7 @@ watch(keyboardHeight, () => { ```` :::note + For apps running in a mobile web browser or as a PWA, Keyboard Lifecycle Events are only supported on Chrome 62+ and iOS Safari 13.0+. + ::: diff --git a/docs/developing/managing-focus.md b/docs/developing/managing-focus.md index a249c452472..8f845186886 100644 --- a/docs/developing/managing-focus.md +++ b/docs/developing/managing-focus.md @@ -264,7 +264,9 @@ The following table explains what each content type represents: | `banner` | The header of the view. | [Header](../api/header) | [`header`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header) | [`role="banner"`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Banner_Role) | :::important + Developers should assign `role="heading"` and `aria-level="1"` to the primary [Title](../api/title) on each view. Since multiple [Title](../api/title) components can be used in a single view, Ionic does not automatically assign these attributes. + ::: ### Specifying Priority diff --git a/docs/developing/scaffolding.md b/docs/developing/scaffolding.md index 57a3cb740ba..9098949889b 100644 --- a/docs/developing/scaffolding.md +++ b/docs/developing/scaffolding.md @@ -45,7 +45,9 @@ The `src/app/` directory contains the root app component and module as well as a ## Generating New Features :::note + This command is only supported in Ionic Angular. + ::: The Ionic CLI can generate new app features with the [`ionic generate`](../cli/commands/generate.md) command. By running `ionic generate` in the command line, a selection prompt is displayed which lists the available features that can be generated. @@ -65,7 +67,9 @@ $ ionic generate After a selection is made, the Ionic CLI will prompt for a name. The name can be a path, allowing easy generation of features within an organized project structure. :::note + Any level of nesting is allowed, such as `portfolio/intro`. You can easily scope components to pages by using `ionic g component "portfolio/intro/About Me"`, for example. + ::: ```shell-session diff --git a/docs/developing/tips.md b/docs/developing/tips.md index 1ed040a4ff0..abc78d55cdf 100644 --- a/docs/developing/tips.md +++ b/docs/developing/tips.md @@ -15,7 +15,9 @@ title: Development Tips `EACCES` permission errors can occur when packages are installed globally. If this is the case, npm may need to be set up to operate without elevated permissions. :::note + Using `sudo` with npm is **not recommended** because it can lead to further complications. + ::: This guide offers two options for resolving permission issues. Refer to the [npm docs](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally) for full documentation and additional options. @@ -118,7 +120,9 @@ When an app runs, it will pause at this function. From there, the developer tool By default, when an app is viewed in the browser, Ionic will apply the `md` mode. However, since Ionic components adapt according to their platform, it is helpful to be able to view what the app will look like on iOS. To do this, add `?ionic:mode=ios` to the URL where the app is being served. For example, if the app is served on port `8100`, the url would be: `http://localhost:8100/?ionic:mode=ios`. :::note + This will not change which platform the browser detects. The platform is determined by device detection and inspecting the user-agent. To change the platform, the user-agent must be changed. To do this, open up Chrome DevTools with Ctrl+Shift+I(Cmd+Option+I on Mac), and then toggle device mode on with Ctrl+Shift+M(Cmd+Option+M on Mac). + ::: ![Chrome DevTools showing the device mode with iPhone X selected.](/img/faq/tips/change-device-platform.png 'Chrome DevTools Device Mode') diff --git a/docs/intro/cli.md b/docs/intro/cli.md index 56d93cbf53d..17222376c24 100644 --- a/docs/intro/cli.md +++ b/docs/intro/cli.md @@ -36,8 +36,10 @@ $ npm install -g @ionic/cli ``` :::note + The `-g` option means _install globally_. When packages are installed globally, `EACCES` permission errors can occur. Consider setting up npm to operate globally without elevated permissions. Refer to [Resolving Permission Errors](../developing/tips.md#resolving-permission-errors) for more information. + ::: ## Start an App diff --git a/docs/intro/environment.md b/docs/intro/environment.md index ceac19f6b8d..468228b9d47 100644 --- a/docs/intro/environment.md +++ b/docs/intro/environment.md @@ -17,7 +17,9 @@ Of course, a code editor is also required. [Visual Studio Code](https://code.vis ## Terminal :::note + Much of Ionic development requires familiarity with the command line. If you're new to the command line, refer to the [New to the Command Line](https://ionicframework.com/blog/new-to-the-command-line/) blog post for a quick introduction. + ::: In general, we recommend using the built-in terminals. Many third-party terminals work well with Ionic, but may not be supported. @@ -41,7 +43,9 @@ $ npm --version ``` :::note + Permission errors are common on macOS when installing global packages with `npm`. If you get an `EACCES` error, refer to [Resolving Permission Errors](../developing/tips.md#resolving-permission-errors). + ::: ## Git diff --git a/docs/javascript/quickstart.md b/docs/javascript/quickstart.md index 9afc51a51da..e12dd856c25 100644 --- a/docs/javascript/quickstart.md +++ b/docs/javascript/quickstart.md @@ -68,11 +68,15 @@ Your new app's directory will look like this: ``` :::warning[Delete files] + The `counter.js` and `style.css` files can be deleted. We will not be using them. + ::: :::info + All file paths in the examples below are relative to the project root directory. + ::: Let's configure the project, initialize Ionic, and add components to create our app. @@ -227,7 +231,9 @@ customElements.define('home-page', HomePage); This creates a custom element called `home-page` that contains the layout for your Home page. The page uses Ionic's layout components to create a header with a toolbar and scrollable content area. :::tip[Learn More] + For detailed information about Ionic layout components, refer to the [Header](/docs/api/header.md), [Toolbar](/docs/api/toolbar.md), [Title](/docs/api/title.md), and [Content](/docs/api/content.md) documentation. + ::: Next, add a `