diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml index c247a0a6a92..69ef7cea290 100644 --- a/.github/workflows/CI.yml +++ b/.github/workflows/CI.yml @@ -48,6 +48,22 @@ jobs: run: npm run typecheck - name: 🔤 Spell Check run: npm run spellcheck + # Docusaurus derives a heading's anchor from its text, so renaming a + # heading moves the anchor and breaks every inbound link. An explicit id + # survives the rename, and lets a translation keep the English anchor + # after the heading text is translated. + # + # Nothing in Docusaurus enforces this: a page whose headings are all + # unpinned builds clean. So run its own generator and fail if it had + # anything to add. + - name: 🔗 Heading IDs + run: | + npm run heading-ids + if ! git diff --quiet -- docs; then + echo "::error::Headings are missing explicit ids. Run \`npm run heading-ids\` and commit the result." + git diff -- docs + exit 1 + fi - uses: ./.github/workflows/actions/check-translations cross-platform: diff --git a/.prettierignore b/.prettierignore index 24b5b1740a6..90a6a6c2be7 100644 --- a/.prettierignore +++ b/.prettierignore @@ -11,8 +11,6 @@ src/theme/Layout/index.tsx src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx src/theme/prism-include-languages.ts -legacy-stencil-components -scripts/bak # Auto-generated files docs/native diff --git a/cspell-wordlist.txt b/cspell-wordlist.txt index 13b3252d864..a66d66fb1eb 100644 --- a/cspell-wordlist.txt +++ b/cspell-wordlist.txt @@ -43,6 +43,7 @@ fortawesome frontmatter fullscreen geolocation +headerless iconset interactives isopen @@ -53,6 +54,8 @@ jsdelivr keyframes keytool lifecycles +llms +llmstxt localstorage mobileweb phablet diff --git a/cspell.json b/cspell.json index 66681e60f72..057dc5efc77 100644 --- a/cspell.json +++ b/cspell.json @@ -10,7 +10,9 @@ "ignoreRegExpList": [ "/(```+)[\\s\\S]+?\\1/g", "`([^`]*)`", - "/:[a-zA-Z0-9-_\\+]+:/g" + "/:[a-zA-Z0-9-_\\+]+:/g", + // Pinned heading ids, as in `## Using isOpen {/* #using-isopen */}`. + "/\\{\\/\\*\\s*#[a-z0-9-]+\\s*\\*\\/\\}/g" ], "ignorePaths": [ "docs/cli", diff --git a/docs/angular/add-to-existing.mdx b/docs/angular/add-to-existing.mdx index 4b958cf5c34..2ef3d723578 100644 --- a/docs/angular/add-to-existing.mdx +++ b/docs/angular/add-to-existing.mdx @@ -22,7 +22,7 @@ This guide uses `.css` file extensions for stylesheets. If you created your Angu ::: -## Setup +## Setup {/* #setup */} :::info @@ -32,7 +32,7 @@ This guide follows the structure of an Angular app created with the Angular CLI. You can add Ionic Angular to your existing Angular project using the Angular CLI's `ng add` feature or by installing it manually. -### Using ng add +### Using ng add {/* #using-ng-add */} The easiest way to add Ionic Angular is to use the Angular CLI's `ng add` feature: @@ -42,17 +42,17 @@ ng add @ionic/angular This will install the `@ionic/angular` package and automatically configure the necessary imports and styles. -### Manual Installation +### Manual Installation {/* #manual-installation */} If you prefer to install Ionic Angular manually, you can follow these steps: -#### 1. Install the Package +#### 1. Install the Package {/* #1-install-the-package */} ```bash npm install @ionic/angular ``` -#### 2. Add Ionic Framework Stylesheets +#### 2. Add Ionic Framework Stylesheets {/* #2-add-ionic-framework-stylesheets */} Replace the existing `styles` array in `angular.json` with the following: @@ -80,7 +80,7 @@ While `core.css` is required, `normalize.css`, `structure.css`, and `typography. ::: -#### 3. Configure Ionic Angular +#### 3. Configure Ionic Angular {/* #3-configure-ionic-angular */} Update `src/app/app.config.ts` to include `provideIonicAngular`: @@ -98,7 +98,7 @@ export const appConfig: ApplicationConfig = { This reflects the Angular 21 and 22 scaffold, which is zoneless by default. If your existing app is on Angular 18 through 20, it still has `provideZoneChangeDetection({ eventCoalescing: true })`; keep that provider and add `provideIonicAngular({})` alongside it. Refer to [Zoneless Change Detection](/angular/zoneless.mdx) for details. -## Using Individual Components +## Using Individual Components {/* #using-individual-components */} After completing the setup above, you can start using Ionic components in your existing Angular app. Here's an example of how to use them: @@ -125,11 +125,11 @@ export class App {} Visit the [components](/components.mdx) page for all of the available Ionic components. -## Using Ionic Pages +## Using Ionic Pages {/* #using-ionic-pages */} If you want to use Ionic pages with full navigation and page transitions, follow these additional setup steps. -#### 1. Add Additional Ionic Framework Stylesheets +#### 1. Add Additional Ionic Framework Stylesheets {/* #1-add-additional-ionic-framework-stylesheets */} Replace the existing `styles` array in `angular.json` with the following: @@ -174,7 +174,7 @@ Replace the existing `styles` array in `angular.json` with the following: These stylesheets set up the overall page structure and provide [CSS utilities](/layout/css-utilities.mdx) for faster development. Some stylesheets are optional. For details on which stylesheets are required, check out [Global Stylesheets](/layout/global-stylesheets.mdx). -#### 2. Set up Theming +#### 2. Set up Theming {/* #2-set-up-theming */} Create a `src/theme/variables.css` file with the following content: @@ -193,7 +193,7 @@ Create a `src/theme/variables.css` file with the following content: This file enables [dark mode support](/theming/dark-mode.mdx) for your Ionic app when the system is set to prefer a dark appearance. You can customize the theming behavior by uncommenting different dark palette imports or adding custom CSS variables. -#### 3. Update the App Component +#### 3. Update the App Component {/* #3-update-the-app-component */} Update `src/app/app.html` to the following: @@ -218,7 +218,7 @@ import { IonApp, IonRouterOutlet } from '@ionic/angular'; export class App {} ``` -#### 4. Create a Home Page +#### 4. Create a Home Page {/* #4-create-a-home-page */} Start by adding a template at `src/app/home/home.html`: @@ -293,7 +293,7 @@ Finally, add a `src/app/home/home.css` file: } ``` -#### 5. Set up Routing +#### 5. Set up Routing {/* #5-set-up-routing */} Update `src/app/app.routes.ts` to add a `home` route: @@ -316,7 +316,7 @@ export const routes: Routes = [ You're all set! Your Ionic Angular app is now configured with full Ionic page support. Run `ng serve` to start your development server and view your app. -## Next Steps +## Next Steps {/* #next-steps */} Now that you have Ionic Angular integrated into your project, check out: diff --git a/docs/angular/build-options.mdx b/docs/angular/build-options.mdx index f852e122236..f9dc9e3323a 100644 --- a/docs/angular/build-options.mdx +++ b/docs/angular/build-options.mdx @@ -7,7 +7,7 @@ Developers have two options for using Ionic components: Standalone or Modules. T The Standalone approach uses modern Angular APIs and is the recommended way to build Ionic applications. The Modules approach, including `IonicModule`, is **deprecated** and will be removed in a future major release. New projects should use the Standalone approach. Existing apps will continue to work but should plan to migrate. Refer to [Migrating from Modules to Standalone](#migrating-from-modules-to-standalone) for migration guidance. -## Standalone +## Standalone {/* #standalone */} :::info @@ -15,7 +15,7 @@ Ionic UI components as Angular standalone components is supported starting in Io ::: -### Overview +### Overview {/* #overview */} Developers can use Ionic components as standalone components to take advantage of treeshaking and newer Angular features. This option involves importing specific Ionic components in the Angular components you want to use them in. Developers can use Ionic standalone components even if their Angular application is NgModule-based. @@ -37,7 +37,7 @@ Ionic ships standalone components from a single entry point (`@ionic/angular`). ::: -### Usage with Standalone-based Applications +### Usage with Standalone-based Applications {/* #usage-with-standalone-based-applications */} :::warning @@ -206,7 +206,7 @@ Ionic Angular's standalone components use ES Modules. As a result, developers us -### Usage with NgModule-based Applications +### Usage with NgModule-based Applications {/* #usage-with-ngmodule-based-applications */} :::warning @@ -371,7 +371,7 @@ Ionic Angular's standalone components use ES Modules. As a result, developers us -## Modules +## Modules {/* #modules */} :::warning[Deprecation Notice] @@ -379,7 +379,7 @@ The Modules approach, including `IonicModule`, is **deprecated** and will be rem ::: -### Overview +### Overview {/* #overview-1 */} Developers can also use the Modules approach by importing `IonicModule` and calling `IonicModule.forRoot()` in the `imports` array in `app.module.ts`. This registers a version of Ionic where Ionic components will be lazily loaded at runtime. @@ -392,7 +392,7 @@ Developers can also use the Modules approach by importing `IonicModule` and call 1. Lazily loading Ionic components means that the compiler does not know which components are needed at build time. This means your final application bundle may be much larger than it needs to be. 2. Developers are unable to use newer Angular features such as [ESBuild](https://angular.io/guide/esbuild). -### Usage +### Usage {/* #usage */} In the example below, we are using `IonicModule` to create a lazily loaded version of Ionic. We can then reference any Ionic component without needing to explicitly import it. @@ -412,7 +412,7 @@ import { AppComponent } from './app.component'; export class AppModule {} ``` -## Migrating from Modules to Standalone +## Migrating from Modules to Standalone {/* #migrating-from-modules-to-standalone */} :::tip @@ -428,7 +428,7 @@ Migrating to Ionic standalone components must be done all at the same time and c Developers are encouraged to try the [automated migration utility](https://github.com/ionic-team/ionic-angular-standalone-codemods), though they can also follow the steps below if they would like to manually migrate their applications. -### Standalone-based Applications +### Standalone-based Applications {/* #standalone-based-applications */} Follow these steps if your Angular application is already using the standalone architecture, and you want to use Ionic UI components as standalone components too. @@ -551,7 +551,7 @@ export class TestComponent {} } ``` -### NgModule-based Applications +### NgModule-based Applications {/* #ngmodule-based-applications */} Follow these steps if your Angular application is still using the NgModule architecture, but you want to adopt Ionic UI components as standalone components now. diff --git a/docs/angular/injection-tokens.mdx b/docs/angular/injection-tokens.mdx index 2367036ab74..653f5bcadf7 100644 --- a/docs/angular/injection-tokens.mdx +++ b/docs/angular/injection-tokens.mdx @@ -13,7 +13,7 @@ sidebar_label: Injection Tokens Ionic provides Angular injection tokens that allow you to access Ionic elements through Angular's dependency injection system. This provides a more Angular-idiomatic way to interact with Ionic components programmatically. -## Benefits +## Benefits {/* #benefits */} Using injection tokens provides several advantages: @@ -22,13 +22,13 @@ Using injection tokens provides several advantages: - **Simplified Code**: Eliminates the need for `ViewChild` queries or manual element references - **Better Testing**: Easier to mock and test components that use injection tokens -## IonModalToken +## IonModalToken {/* #ionmodaltoken */} The `IonModalToken` injection token allows you to inject a reference to the current modal element directly into your Angular components. This is particularly useful when you need to programmatically control modal behavior, listen to modal events, or access modal properties. Starting in `@ionic/angular` v8.7.0, you can use this injection token to streamline modal interactions in your Angular applications. -### Basic Usage +### Basic Usage {/* #basic-usage */} To use the `IonModalToken`, inject it into your component's constructor: @@ -60,7 +60,7 @@ export class ModalComponent { } ``` -### Listening to Modal Events +### Listening to Modal Events {/* #listening-to-modal-events */} You can use the injected modal reference to listen to modal lifecycle events: @@ -102,7 +102,7 @@ export class ModalComponent implements OnInit { } ``` -### Accessing Modal Properties +### Accessing Modal Properties {/* #accessing-modal-properties */} The injected modal reference provides access to all modal properties and methods: @@ -143,7 +143,7 @@ export class ModalComponent implements OnInit { } ``` -### Opening a Modal with Injection Token Content +### Opening a Modal with Injection Token Content {/* #opening-a-modal-with-injection-token-content */} When opening a modal that uses the injection token, you can pass the component directly to the modal controller: diff --git a/docs/angular/lifecycle.mdx b/docs/angular/lifecycle.mdx index c6a7a79aab4..4032209defe 100644 --- a/docs/angular/lifecycle.mdx +++ b/docs/angular/lifecycle.mdx @@ -15,7 +15,7 @@ This guide covers how the page life cycle works in an app built with Ionic and A ![Flowchart illustrating the Ionic page life cycle events and their sequence.](/img/guides/lifecycle/ioniclifecycle.png 'Ionic Lifecycle Diagram') -## Angular Life Cycle Events +## Angular Life Cycle Events {/* #angular-life-cycle-events */} Ionic embraces the life cycle events provided by Angular. The two Angular events you will find using the most are: @@ -36,7 +36,7 @@ On **Angular 18 through 21** this only affects you if you set `OnPush` on those ::: -## Ionic Page Events +## Ionic Page Events {/* #ionic-page-events */} In addition to the Angular life cycle events, Ionic Angular provides a few additional events that you can use: @@ -55,7 +55,7 @@ For `ionViewWillLeave` and `ionViewDidLeave`, `ionViewWillLeave` gets called dir ![Animated GIF showing Ionic page life cycle events in a console log as a page transition occurs.](/img/guides/lifecycle/ioniclifecycle.gif 'Ionic Lifecycle Animation') -## How Ionic Handles the Life of a Page +## How Ionic Handles the Life of a Page {/* #how-ionic-handles-the-life-of-a-page */} Ionic has its router outlet, called ``. This outlet extends Angular's `` with some additional functionality to enable better experiences for mobile devices. @@ -70,7 +70,7 @@ Because of this special handling, the `ngOnInit` and `ngOnDestroy` methods might `ngOnInit` will only fire each time the page is freshly created, but not when navigated back to the page. For instance, navigating between each page in a tabs interface will only call each page's `ngOnInit` method once, but not on subsequent visits. `ngOnDestroy` will only fire when a page "popped". -## Route Guards +## Route Guards {/* #route-guards */} In Ionic 3, there were a couple of additional life cycle methods that were useful to control when a page could be entered (`ionViewCanEnter`) and left (`ionViewCanLeave`). These could be used to protect pages from unauthorized users and to keep a user on a page when you don't want them to leave (like during a form fill). @@ -97,7 +97,7 @@ To use this guard, add it to the appropriate param in the route definition: For more info on how to use route guards, go to Angular's [router documentation](https://angular.io/guide/router). -## Guidance for Each Life Cycle Method +## Guidance for Each Life Cycle Method {/* #guidance-for-each-life-cycle-method */} Below are some tips on use cases for each of the life cycle events. diff --git a/docs/angular/navigation.mdx b/docs/angular/navigation.mdx index 05582edf5a1..8d51e642855 100644 --- a/docs/angular/navigation.mdx +++ b/docs/angular/navigation.mdx @@ -17,7 +17,7 @@ This guide covers how routing works in an app built with Ionic and Angular. The Angular Router is one of the most important libraries in an Angular application. Without it, apps would be single view/single context apps or would not be able to maintain their navigation state on browser reloads. With Angular Router, we can create rich apps that are linkable and have rich animations (when paired with Ionic of course). Let's walk through the basics of the Angular Router and how we can configure it for Ionic apps. -## A simple Route +## A simple Route {/* #a-simple-route */} For most apps, having some sort of route is often required. The most basic configuration looks a bit like this: @@ -38,7 +38,7 @@ import { RouterModule } from '@angular/router'; The simplest breakdown for what we have here is a path/component lookup. When our app loads, the router kicks things off by reading the URL the user is trying to load. In our sample, our route looks for `''`, which is essentially our index route. So for this, we load the `LoginComponent`. Fairly straight forward. This pattern of matching paths with a component continues for every entry we have in the router config. But what if we wanted to load a different path on our initial load? -## Handling Redirects +## Handling Redirects {/* #handling-redirects */} For this we can use router redirects. Redirects work the same way that a typical route object does, but just includes a few different keys. @@ -70,7 +70,7 @@ Alternatively, if we used: Then load both `/route1/route2/route3` and `/route1/route2/route4`, we'll be redirected for both routes. This is because `pathMatch: 'prefix'` will match only part of the path. -## Navigating to different routes +## Navigating to different routes {/* #navigating-to-different-routes */} Talking about routes is good and all, but how does one actually navigate to said routes? For this, we can use the `routerLink` directive. Let's go back and take our simple router setup from earlier: @@ -118,7 +118,7 @@ export class LoginComponent { Both options provide the same navigation mechanism, just fitting different use cases. -### Navigating using LocationStrategy.historyGo +### Navigating using LocationStrategy.historyGo {/* #navigating-using-locationstrategyhistorygo */} Angular Router has a [LocationStrategy.historyGo](https://angular.io/api/common/LocationStrategy#historyGo) method that allows developers to move forward or backward through the application history. Let's walk through an example. @@ -130,7 +130,7 @@ If you were to call `LocationStrategy.historyGo(-2)` on `/pageC`, you would be b An key characteristic of `LocationStrategy.historyGo()` is that it expects your application history to be linear. This means that `LocationStrategy.historyGo()` should not be used in applications that make use of non-linear routing. Refer to [Linear Routing versus Non-Linear Routing](#linear-routing-versus-non-linear-routing) for more information. -## Lazy loading routes +## Lazy loading routes {/* #lazy-loading-routes */} Now the current way our routes are setup makes it so they are included in the same chunk as the root app.module, which is not ideal. Instead, the router has a setup that allows the components to be isolated to their own chunks. @@ -175,7 +175,7 @@ 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. -## Standalone Components +## Standalone Components {/* #standalone-components */} Standalone components allow developers to lazy load a component on a route without having to declare the component to an Angular module. @@ -203,15 +203,15 @@ If you are using `routerLink`, `routerDirection`, or `routerAction` be sure to a To get started with standalone components [visit Angular's official docs](https://angular.io/guide/standalone-components). -## Live Example +## Live Example {/* #live-example */} import NavigationPlayground from '@site/static/usage/v10/navigation/index.mdx'; -## Linear Routing versus Non-Linear Routing +## Linear Routing versus Non-Linear Routing {/* #linear-routing-versus-non-linear-routing */} -### Linear Routing +### Linear Routing {/* #linear-routing */} If you have built a web app that uses routing, you likely have used linear routing before. Linear routing means that you can move forward or backward through the application history by pushing and popping pages. @@ -235,7 +235,7 @@ When we press the back button, we follow that same routing path except in revers The downside of linear routing is that it does not allow for complex user experiences such as tab views. This is where non-linear routing comes into play. -### Non-Linear Routing +### Non-Linear Routing {/* #non-linear-routing */} Non-linear routing is a concept that may be new to many web developers learning to build mobile apps with Ionic. @@ -263,7 +263,7 @@ If tapping the back button simply called `LocationStrategy.historyGo(-1)` from t Non-linear routing allows for sophisticated user flows that linear routing cannot handle. However, certain linear routing APIs such as `LocationStrategy.historyGo()` cannot be used in this non-linear environment. This means that `LocationStrategy.historyGo()` should not be used when using tabs or nested outlets. -### Which one should I choose? +### Which one should I choose? {/* #which-one-should-i-choose */} We recommend keeping your application as simple as possible until you need to add non-linear routing. Non-linear routing is very powerful, but it also adds a considerable amount of complexity to mobile applications. @@ -273,11 +273,11 @@ For more on tabs, please refer to [Working with Tabs](#working-with-tabs). For more on nested router outlets, please refer to [Nested Routes](#nested-routes). -## Shared URLs versus Nested Routes +## Shared URLs versus Nested Routes {/* #shared-urls-versus-nested-routes */} A common point of confusion when setting up routing is deciding between shared URLs or nested routes. This part of the guide will explain both and help you decide which one to use. -### Shared URLs +### Shared URLs {/* #shared-urls */} Shared URLs is a route configuration where routes have pieces of the URL in common. The following is an example of a shared URL configuration: @@ -296,7 +296,7 @@ const routes: Routes = [ The above routes are considered "shared" because they reuse the `dashboard` piece of the URL. -### Nested Routes +### Nested Routes {/* #nested-routes */} Nested Routes is a route configuration where routes are listed as children of other routes. The following is an example of a nested route configuration: @@ -321,7 +321,7 @@ const routes: Routes = [ The above routes are nested because they are in the `children` array of the parent route. Notice that the parent route renders the `DashboardRouterOutlet` component. When you nest routes, you need to render another instance of `ion-router-outlet`. -### Which one should I choose? +### Which one should I choose? {/* #which-one-should-i-choose-1 */} Shared URLs are great when you want to transition from page A to page B while preserving the relationship between the two pages in the URL. In our previous example, a button on the `/dashboard` page could transition to the `/dashboard/stats` page. The relationship between the two pages is preserved because of a) the page transition and b) the url. @@ -329,7 +329,7 @@ Nested routes should be used when you want to render content in outlet A while a There are very few use cases in which nested routes make sense in mobile applications. When in doubt, use the shared URL route configuration. We strongly caution against using nested routing in contexts other than tabs as it can quickly make navigating your app confusing. -## Working with Tabs +## Working with Tabs {/* #working-with-tabs */} With Tabs, the Angular Router provides Ionic the mechanism to know what components should be loaded, but the heavy lifting is actually done by the tabs component. Let's walk through a simple example. @@ -378,7 +378,7 @@ Here we have a "tabs" path that we load. In this example we call the path "tabs" If you've built apps with Ionic before, this should feel familiar. We create a `ion-tabs` component, and provide a `ion-tab-bar`. The `ion-tab-bar` provides a `ion-tab-button` with a `tab` property that is associated with the tab "outlet" in the router config. Note that the latest version of `@ionic/angular` no longer requires ``, but instead allows developers to fully customize the tab bar, and the single source of truth lives within the router configuration. -### How Tabs in Ionic Work +### How Tabs in Ionic Work {/* #how-tabs-in-ionic-work */} Each tab in Ionic is treated as an individual navigation stack. This means if you have three tabs in your application, each tab has its own navigation stack. Within each stack you can navigate forwards (push a view) and backwards (pop a view). @@ -386,7 +386,7 @@ This behavior is important to note as it is different than most tab implementati Since Ionic is focused on helping developers build mobile apps, the tabs in Ionic are designed to match native mobile tabs as closely as possible. As a result, there may be certain behaviors in Ionic's tabs that differ from tabs implementations in other UI libraries. Read on to learn more about some of these differences. -### Child Routes within Tabs +### Child Routes within Tabs {/* #child-routes-within-tabs */} When adding additional routes to tabs you should write them as sibling routes with the parent tab as the path prefix. The example below defines the `/tabs/tab1/view` route as a sibling of the `/tabs/tab1` route. Since this new route has the `tab1` prefix, it will be rendered inside of the `Tabs` component, and Tab 1 will still be selected in the `ion-tab-bar`. @@ -442,7 +442,7 @@ const routes: Routes = [ ]; ``` -### Switching Between Tabs +### Switching Between Tabs {/* #switching-between-tabs */} Since each tab is its own navigation stack, it is important to note that these navigation stacks should never interact. This means that there should never be a button in Tab 1 that routes a user to Tab 2. In other words, tabs should only be changed by the user tapping a tab button in the tab bar. diff --git a/docs/angular/overlays.mdx b/docs/angular/overlays.mdx index 423a91e02ac..cbe6a85dbbc 100644 --- a/docs/angular/overlays.mdx +++ b/docs/angular/overlays.mdx @@ -13,7 +13,7 @@ sidebar_label: Overlays Ionic provides overlay components such as modals and popovers that display content on top of your application. In Angular, these overlays can be created using controllers like `ModalController` and `PopoverController`. -## Creating Overlays +## Creating Overlays {/* #creating-overlays */} Overlays can be created programmatically using their respective controllers: @@ -41,13 +41,13 @@ export class HomeComponent { } ``` -## Custom Injectors +## Custom Injectors {/* #custom-injectors */} By default, overlay components use the root injector for dependency injection. This means that services or tokens provided at the route level or within a specific component tree are not accessible inside the overlay. The `injector` option allows you to pass a custom Angular `Injector` when creating a modal or popover. This enables overlay components to access services and tokens that are not available in the root injector. -### Use Cases +### Use Cases {/* #use-cases */} Custom injectors are useful when you need to: @@ -55,7 +55,7 @@ Custom injectors are useful when you need to: - Use Angular CDK's `Dir` directive for bidirectional text support - Access any providers that are not registered at the root level -### Usage +### Usage {/* #usage */} To use a custom injector, pass it to the `create()` method: @@ -101,7 +101,7 @@ export class MyModalComponent { } ``` -### Creating a Custom Injector +### Creating a Custom Injector {/* #creating-a-custom-injector */} You can also create a custom injector with specific providers: @@ -139,7 +139,7 @@ export class FeatureComponent { } ``` -### Using with Angular CDK Directionality +### Using with Angular CDK Directionality {/* #using-with-angular-cdk-directionality */} A common use case is providing the Angular CDK `Dir` directive to overlays for bidirectional text support: @@ -169,7 +169,7 @@ export class FeatureComponent { } ``` -### Popover Controller +### Popover Controller {/* #popover-controller */} The `PopoverController` supports the same `injector` option: @@ -199,7 +199,7 @@ export class FeatureComponent { } ``` -## Angular Options Types +## Angular Options Types {/* #angular-options-types */} Ionic Angular exports its own `ModalOptions` and `PopoverOptions` types that extend the core options with Angular-specific properties like `injector`: @@ -212,7 +212,7 @@ These types are exported from `@ionic/angular` and `@ionic/angular/lazy`: import type { ModalOptions, PopoverOptions } from '@ionic/angular'; ``` -## Docs for Overlays in Ionic +## Docs for Overlays in Ionic {/* #docs-for-overlays-in-ionic */} For full docs and usage examples, visit the docs page for each of the overlays in Ionic: diff --git a/docs/angular/overview.mdx b/docs/angular/overview.mdx index 923c4b5410e..1fb4aa3982c 100644 --- a/docs/angular/overview.mdx +++ b/docs/angular/overview.mdx @@ -16,19 +16,19 @@ import DocsCards from '@components/global/DocsCards'; `@ionic/angular` brings the full power of the Ionic Framework to Angular developers. It offers seamless integration with the Angular ecosystem, so you can build high-quality cross-platform apps using familiar Angular tools, components, and best practices. You also get access to Ionic's extensive UI library and native capabilities. -## Angular Version Support +## Angular Version Support {/* #angular-version-support */} Ionic Angular v9 supports Angular versions 18 through 22. For detailed information on supported versions and our support policy, refer to the [Ionic Angular Support Policy](/reference/support.mdx#ionic-angular). -## Angular Tooling +## Angular Tooling {/* #angular-tooling */} Ionic uses the official Angular stack for building apps and routing, so your app can fall in line with the rest of the Angular ecosystem. In cases where more opinionated features are needed, Ionic provides `@ionic/angular-toolkit`, which builds and integrates with the [official Angular CLI](https://angular.io/cli) and provides features that are specific to `@ionic/angular` apps. -## Native Tooling +## Native Tooling {/* #native-tooling */} [Capacitor](https://capacitorjs.com) is the official cross-platform runtime for Ionic Angular, enabling your apps to run natively on iOS, Android, and the web with a single codebase. -## Installation +## Installation {/* #installation */} Before you begin, make sure you have [Node.js](https://nodejs.org/) (which includes npm) installed on your machine. @@ -40,7 +40,7 @@ $ cd myApp $ ionic serve █ ``` -## Resources +## Resources {/* #resources */} diff --git a/docs/angular/performance.mdx b/docs/angular/performance.mdx index 14ac3db954e..0faa660c24d 100644 --- a/docs/angular/performance.mdx +++ b/docs/angular/performance.mdx @@ -11,7 +11,7 @@ sidebar_label: Performance /> -## \*ngFor with Ionic Components +## \*ngFor with Ionic Components {/* #ngfor-with-ionic-components */} When using `*ngFor` with Ionic components, we recommend using Angular's `trackBy` option. This allows Angular to manage change propagation in a much more efficient way and only update the content inside of the component rather than re-create the component altogether. @@ -44,17 +44,17 @@ In this example, we have an array of objects called `items`. Each object contain For more information, refer to the [Angular NgForOf change propagation documentation](https://angular.io/api/common/NgForOf#change-propagation). -## From the Ionic Team +## From the Ionic Team {/* #from-the-ionic-team */} [How to Lazy Load in Ionic Angular](https://ionicframework.com/blog/how-to-lazy-load-in-ionic-angular/) [Improved Perceived Performance with Skeleton Screens](https://ionicframework.com/blog/improved-perceived-performance-with-skeleton-screens/) -## From the Angular Team +## From the Angular Team {/* #from-the-angular-team */} [Build performant and progressive Angular apps](https://web.dev/angular) - web.dev -## From the Community +## From the Community {/* #from-the-community */} {/* cspell:disable */} diff --git a/docs/angular/platform.mdx b/docs/angular/platform.mdx index 7aa72bba712..ad013cff64e 100644 --- a/docs/angular/platform.mdx +++ b/docs/angular/platform.mdx @@ -15,7 +15,7 @@ import TabItem from '@theme/TabItem'; The Platform service can be used to get information about your current device. You can get all of the platforms associated with the device using the `platforms` method, including whether the app is being viewed from a tablet, if it's on a mobile device or browser, and the exact platform (iOS, Android, etc). You can also get the orientation of the device, if it uses right-to-left language direction, and much much more. With this information you can completely customize your app to fit any device. -## Usage +## Usage {/* #usage */} -## Methods +## Methods {/* #methods */} -### `is` +### `is` {/* #is */} | | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Description** | Depending on the platform the user is on, `is(platformName)` will return true or false. Note that the same app can return true for more than one platform name. For example, an app running from an iPad would return true for the platform names: `mobile`, `ios`, `ipad`, and `tablet`. Additionally, if the app was running from Cordova then `cordova` would be true. | | **Signature** | `is(platformName: Platforms) => boolean` | -#### Parameters +#### Parameters {/* #parameters */} | Name | Type | Description | | -------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `platformName` | `Platforms` | Name of the platform. Available options are android, capacitor, cordova, desktop, electron, hybrid, ios, ipad, iphone, mobile, phablet, pwa, tablet | -#### Platforms +#### Platforms {/* #platforms */} Below is a table listing all the possible platform values along with corresponding descriptions. @@ -91,7 +91,7 @@ Below is a table listing all the possible platform values along with correspondi | pwa | a PWA app | | tablet | a tablet device | -#### Customizing Platform Detection Functions +#### Customizing Platform Detection Functions {/* #customizing-platform-detection-functions */} 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. @@ -179,82 +179,82 @@ type PlatformConfig = { }; ``` -### `platforms` +### `platforms` {/* #platforms-1 */} | | | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Description** | Depending on what device you are on, `platforms` can return multiple values. Each possible value is a hierarchy of platforms. For example, on an iPhone, it would return `mobile`, `ios`, and `iphone`. | | **Signature** | `platforms() => string[]` | -### `ready` +### `ready` {/* #ready */} | | | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Description** | Returns a promise when the platform is ready and native functionality can be called. If the app is running from within a web browser, then the promise will resolve when the DOM is ready. When the app is running from an application engine such as Cordova, then the promise will resolve when Cordova triggers the `deviceready` event. The resolved value is the `readySource`, which states the platform that was used.

For example, when Cordova is ready, the resolved ready source is `cordova`. The default ready source value will be `dom`. The `readySource` is useful if different logic should run depending on the platform the app is running from. For example, only Capacitor and Cordova can execute the status bar plugin, so the web should not run status bar plugin logic. | | **Signature** | `ready() => Promise` | -### `isRTL` +### `isRTL` {/* #isrtl */} | | | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Description** | Returns if this app is using right-to-left language direction or not. We recommend the app's `index.html` file already has the correct `dir` attribute value set, such as `` or ``. [W3C: Structural markup and right-to-left text in HTML](http://www.w3.org/International/questions/qa-html-dir) | | **Signature** | `isRTL() => boolean` | -### `isLandscape` +### `isLandscape` {/* #islandscape */} | | | | --------------- | ----------------------------------------------- | | **Description** | Returns `true` if the app is in landscape mode. | | **Signature** | `isLandscape() => boolean` | -### `isPortrait` +### `isPortrait` {/* #isportrait */} | | | | --------------- | ---------------------------------------------- | | **Description** | Returns `true` if the app is in portrait mode. | | **Signature** | `isPortrait() => boolean` | -### `width` +### `width` {/* #width */} | | | | --------------- | -------------------------------------------------------------------- | | **Description** | Gets the width of the platform's viewport using `window.innerWidth`. | | **Signature** | `width() => number` | -### `height` +### `height` {/* #height */} | | | | --------------- | ---------------------------------------------------------------------- | | **Description** | Gets the height of the platform's viewport using `window.innerHeight`. | | **Signature** | `height() => number` | -### `url` +### `url` {/* #url */} | | | | --------------- | -------------------- | | **Description** | Get the current url. | | **Signature** | `url() => string` | -### `testUserAgent` +### `testUserAgent` {/* #testuseragent */} | | | | --------------- | ---------------------------------------------------------------------- | | **Description** | Returns `true` if the expression is included in the user agent string. | | **Signature** | `testUserAgent(expression: string) => boolean` | -#### Parameters +#### Parameters {/* #parameters-1 */} | Name | Type | Description | | ---------- | ------ | ------------------------------------- | | expression | string | The string to check in the user agent | -## Events +## Events {/* #events */} -### `pause` +### `pause` {/* #pause */} The `pause` event emits when the native platform puts the application into the background, typically when the user switches to a different application. This event emits when a Cordova/Capacitor app is put into the background but doesn't fire in a standard web browser. -#### Examples +#### Examples {/* #examples */} ```tsx this.platform.pause.subscribe(async () => { @@ -262,11 +262,11 @@ this.platform.pause.subscribe(async () => { }); ``` -### `resize` +### `resize` {/* #resize */} The `resize` event emits when the browser window has changed dimensions. This could be from a browser window being physically resized, or from a device changing orientation. -#### Examples +#### Examples {/* #examples-1 */} ```tsx this.platform.resize.subscribe(async () => { @@ -274,11 +274,11 @@ this.platform.resize.subscribe(async () => { }); ``` -### `resume` +### `resume` {/* #resume */} The `resume` event fires when the native platform pulls the application out from the background. This event emits when a Cordova/Capacitor app comes out from the background but doesn't fire in a standard web browser. -#### Examples +#### Examples {/* #examples-2 */} ```tsx this.platform.resume.subscribe(async () => { diff --git a/docs/angular/pwa.mdx b/docs/angular/pwa.mdx index 8f9a3e0b00e..94e8293a772 100644 --- a/docs/angular/pwa.mdx +++ b/docs/angular/pwa.mdx @@ -11,7 +11,7 @@ sidebar_label: Progressive Web Apps /> -## Making your Angular app a PWA +## Making your Angular app a PWA {/* #making-your-angular-app-a-pwa */} The two main requirements of a PWA are a [Service Worker](https://developers.google.com/web/fundamentals/primers/service-workers/) and a [Web Manifest](https://developers.google.com/web/fundamentals/web-app-manifest/). While it's possible to add both of these to an app manually, the Angular team has an `@angular/pwa` package that can be used to automate this. @@ -36,7 +36,7 @@ Features like Service Workers and many JavaScript APIs (such as geolocation) req ::: -## Service Worker configuration +## Service Worker configuration {/* #service-worker-configuration */} After `@angular/pwa` has been added, a new `ngsw-config.json` file will be created at the root of the project. This file is responsible for configuring how Angular's service worker mechanism will handle caching assets. By default, the following will be provided: @@ -66,9 +66,9 @@ After `@angular/pwa` has been added, a new `ngsw-config.json` file will be creat There are two sections in here, one for app specific resources (JS, CSS, HTML) and assets the app will load on demand. Depending on your app, these options can be customized. For a more detailed guide, read [the official guide from the Angular Team](https://angular.io/guide/service-worker-config). -## Deploying +## Deploying {/* #deploying */} -### Firebase +### Firebase {/* #firebase */} Firebase hosting provides many benefits for Progressive Web Apps, including fast response times thanks to CDNs, HTTPS enabled by default, and support for [HTTP2 push](https://firebase.googleblog.com/2016/09/http2-comes-to-firebase-hosting.html). diff --git a/docs/angular/quickstart.mdx b/docs/angular/quickstart.mdx index 121ab4048a8..e043b556dda 100644 --- a/docs/angular/quickstart.mdx +++ b/docs/angular/quickstart.mdx @@ -18,7 +18,7 @@ Welcome! This guide will walk you through the basics of Ionic Angular developmen If you're looking for a high-level overview of what Ionic Angular is and how it fits into the Angular ecosystem, refer to the [Ionic Angular Overview](overview). -## Prerequisites +## Prerequisites {/* #prerequisites */} Before you begin, make sure you have Node.js and npm installed on your machine. You can check by running: @@ -30,7 +30,7 @@ npm -v If you don't have Node.js and npm, [download Node.js](https://nodejs.org/en/download) (which includes npm). -## Create a Project with the Ionic CLI +## Create a Project with the Ionic CLI {/* #create-a-project-with-the-ionic-cli */} First, install the latest [Ionic CLI](../cli): @@ -53,7 +53,7 @@ After running `ionic serve`, your project will open in the browser. ![Screenshot of the Ionic Angular Home page](/img/guides/quickstart/home-page.png 'Ionic Angular Home Component') -## Explore the Project Structure +## Explore the Project Structure {/* #explore-the-project-structure */} Your new app's directory will look like this: @@ -79,7 +79,7 @@ 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. -## View the App Component +## View the App Component {/* #view-the-app-component */} The root of your app is defined in `app.component.ts`: @@ -107,7 +107,7 @@ And its template in `app.component.html`: This sets up the root of your application, using Ionic's `ion-app` and `ion-router-outlet` components. The router outlet is where your pages will be displayed. -## View Routes +## View Routes {/* #view-routes */} Routes are defined in `app.routes.ts`: @@ -129,7 +129,7 @@ export const routes: Routes = [ When you visit the root URL (`/`), the `HomePage` component will be loaded. -## View the Home Page +## View the Home Page {/* #view-the-home-page */} The Home page component, defined in `home.page.ts`, imports the Ionic components it uses: @@ -182,7 +182,7 @@ For detailed information about Ionic layout components, refer to the [Header](/a ::: -## Add an Ionic Component +## Add an Ionic Component {/* #add-an-ionic-component */} You can enhance your Home page with more Ionic UI components. For example, add a [Button](/api/button.mdx) at the end of the `ion-content`: @@ -205,7 +205,7 @@ import { IonButton, IonContent, IonHeader, IonTitle, IonToolbar } from '@ionic/a }) ``` -## Add a New Page +## Add a New Page {/* #add-a-new-page */} To add a new page, generate it with the CLI: @@ -241,7 +241,7 @@ import { IonBackButton, IonButtons, IonContent, IonHeader, IonTitle, IonToolbar The `ion-back-button` will automatically handle navigation back to the previous page, or to `/` if there is no history. -## Navigate to the New Page +## Navigate to the New Page {/* #navigate-to-the-new-page */} To navigate to the new page, update the button in `home.page.html`: @@ -266,7 +266,7 @@ Navigating can also be performed using Angular's Router service. Refer to the [A ::: -## Add Icons to the New Page +## Add Icons to the New Page {/* #add-icons-to-the-new-page */} Ionic Angular comes with [Ionicons](https://ionic.io/ionicons/) pre-installed. You can use any icon by setting the `name` property on the `ion-icon` component. Add the following icons to `new.page.html`: @@ -309,7 +309,7 @@ Alternatively, you can register icons in `app.component.ts` to use them througho For more information, refer to the [Icon documentation](/api/icon.mdx) and the [Ionicons documentation](https://ionic.io/ionicons/). -## Call Component Methods +## Call Component Methods {/* #call-component-methods */} Let's add a button that can scroll the content area to the bottom. @@ -395,7 +395,7 @@ To call methods on Ionic components: You can find available methods for each component in the [Methods](/api/content.mdx#methods) section of their API documentation. -## Run on a Device +## Run on a Device {/* #run-on-a-device */} Ionic's components work everywhere: on iOS, Android, and PWAs. To deploy to mobile, use [Capacitor](https://capacitorjs.com): @@ -414,7 +414,7 @@ ionic cap open android Refer to [Capacitor's Getting Started guide](https://capacitorjs.com/docs/getting-started/with-ionic) for more. -## Explore More +## Explore More {/* #explore-more */} This guide covered the basics of creating an Ionic Angular app, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out: diff --git a/docs/angular/slides.mdx b/docs/angular/slides.mdx index bbe68a742f2..92cdb76ed1b 100644 --- a/docs/angular/slides.mdx +++ b/docs/angular/slides.mdx @@ -21,7 +21,7 @@ import TabItem from '@theme/TabItem'; 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. -## Getting Started +## Getting Started {/* #getting-started */} First, update to the latest version of Ionic: @@ -69,13 +69,13 @@ From there, we just have to replace `ion-slides` elements with `swiper-container ``` -## Bundled vs. Core Versions +## Bundled vs. Core Versions {/* #bundled-vs-core-versions */} By default, make sure you import the `register` function from `swiper/element/bundle`. This uses the bundled version of Swiper, which automatically includes all modules and stylesheets needed to run Swiper's various features. If you would like to use the Core version instead, which does not include additional modules automatically, refer to [Swiper's core version and modules documentation](https://swiperjs.com/element#core-version-and-modules). The rest of this migration guide will assume you are using the bundled version. -## Swiping with Style +## Swiping with Style {/* #swiping-with-style */} To migrate over your CSS, first update your selectors to target the new custom elements instead: @@ -97,7 +97,7 @@ If you were using the CSS custom properties found on `ion-slides`, below is a li For additional custom CSS, because Swiper Element uses Shadow DOM encapsulation, styles will need to be injected into the Shadow DOM scope. Refer to [Swiper's guide on injecting styles](https://swiperjs.com/element#injecting-styles) for instructions. -### Additional `ion-slides` Styles +### Additional `ion-slides` Styles {/* #additional-ion-slides-styles */} The `ion-slides` component had additional styling that helped create a native look and feel. These styles are **not** required to use Swiper.js with Ionic, but if you would like to maintain the look of `ion-slides` as closely as possible, add the following CSS to your `global.scss`: @@ -136,7 +136,7 @@ swiper-slide img { } ``` -## The IonicSlides Module +## The IonicSlides Module {/* #the-ionicslides-module */} With `ion-slides`, Ionic automatically customized dozens of Swiper properties. This resulted in an experience that felt smooth when swiping on mobile devices. We recommend using the `IonicSlides` module to ensure that these properties are also set when using Swiper directly. However, using this module is **not** required to use Swiper.js in Ionic. @@ -198,7 +198,7 @@ If you are using the Core version of Swiper and have installed additional module ::: -## Properties +## Properties {/* #properties */} Swiper options should be provided as individual properties directly on the `` component. @@ -236,7 +236,7 @@ All properties available in Swiper Element can be found in the [Swiper API param ::: -## Events +## Events {/* #events */} Since the `swiper-container` component is not provided by Ionic Framework, event names will not have an `ionSlide` prefix to them. Additionally, all event names should be lowercase instead of camelCase. @@ -287,7 +287,7 @@ All events available in Swiper Element can be found in the [Swiper API events do ::: -## Methods +## Methods {/* #methods */} Most methods have been removed in favor of directly accessing the properties of the Swiper instance. To access the Swiper instance, first get a reference to the `` element (such as through `ViewChild`), then access its `swiper` prop: @@ -341,7 +341,7 @@ All methods and properties available on the Swiper instance can be found in the ::: -## Effects +## Effects {/* #effects */} Effects such as Cube or Fade can be used in Swiper Element with no additional imports, as long as you are using the bundled version of Swiper. For example, the below code will cause the slides to have a flip transition effect: @@ -355,21 +355,21 @@ For more information on effects in Swiper, please refer to the [Swiper API fade ::: -## Wrap Up +## Wrap Up {/* #wrap-up */} Now that you have Swiper installed, there is a whole set of new Swiper features for you to enjoy. We recommend starting with the [Swiper Element documentation](https://swiperjs.com/element) and then referencing [the Swiper API docs](https://swiperjs.com/swiper-api). -## FAQ +## FAQ {/* #faq */} -### Where can I find an example of this migration? +### Where can I find an example of this migration? {/* #where-can-i-find-an-example-of-this-migration */} You can find a sample app with `ion-slides` and the equivalent Swiper usage at https://github.com/ionic-team/slides-migration-samples. -### Where can I get help with this migration? +### Where can I get help with this migration? {/* #where-can-i-get-help-with-this-migration */} If you are running into issues with the migration, please create a post on the [Ionic Forum](https://forum.ionicframework.com/). -### Where do I file bug reports? +### Where do I file bug reports? {/* #where-do-i-file-bug-reports */} Before opening an issue, please consider creating a post on the [Swiper Discussion Board](https://github.com/nolimits4web/swiper/discussions) or the [Ionic Forum](https://forum.ionicframework.com) to check if your issue can be resolved by the community. diff --git a/docs/angular/storage.mdx b/docs/angular/storage.mdx index 85ff56b9ae8..f5d1950e58f 100644 --- a/docs/angular/storage.mdx +++ b/docs/angular/storage.mdx @@ -21,18 +21,18 @@ Some storage options involve third-party plugins or products. In such cases, we Here are some common use cases and solutions: -## Local Application Settings and Data +## Local Application Settings and Data {/* #local-application-settings-and-data */} Many applications need to locally store settings as well as other lightweight key/value data. The [Capacitor Preferences](https://capacitorjs.com/docs/apis/preferences) plugin is specifically designed to handle these scenarios. -## Relational Data Storage (Mobile Only) +## Relational Data Storage (Mobile Only) {/* #relational-data-storage-mobile-only */} Some applications, especially those following an offline-first methodology, may require locally storing high volumes of complex relational data. For such scenarios, a SQLite plugin may be used. The most common SQLite plugin offerings are: - [Cordova SQLite Storage](https://github.com/storesafe/cordova-sqlite-storage) (a [convenience wrapper](https://danielsogl.gitbook.io/awesome-cordova-plugins/sqlite) also exists for this plugin to aid in implementation) - [Capacitor Community SQLite Plugin](https://github.com/capacitor-community/sqlite) -## Non-Relational High Volume Data Storage (Mobile and Web) +## Non-Relational High Volume Data Storage (Mobile and Web) {/* #non-relational-high-volume-data-storage-mobile-and-web */} For applications that need to store a high volume of data as well as operate on both web and mobile, a potential solution is to create a key/value pair data storage service that uses [indexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API) on the web and one of the previously mentioned SQLite plugins on mobile. @@ -42,7 +42,7 @@ Here a sample of how this can be accomplished: - [Mobile Service](https://github.com/ionic-enterprise/tutorials-and-demos-ng/blob/main/demos/sqlcipher-kv-pair/src/app/core/mobile-kv-store.ts) - [Web Service](https://github.com/ionic-enterprise/tutorials-and-demos-ng/blob/main/demos/sqlcipher-kv-pair/src/app/core/web-kv-store.ts) -## Other Options +## Other Options {/* #other-options */} Other storage options that provide local as well as cloud-based storage that work well within Capacitor applications also exist and may integrate well with your application. diff --git a/docs/angular/testing.mdx b/docs/angular/testing.mdx index 7fd3668a467..fcae14de461 100644 --- a/docs/angular/testing.mdx +++ b/docs/angular/testing.mdx @@ -12,7 +12,7 @@ title: Testing When an `@ionic/angular` application is generated using the Ionic CLI, it is automatically set up for unit testing and end-to-end testing of the application. This is the same setup that is used by the Angular CLI. Refer to the [Angular Testing Guide](https://angular.io/guide/testing) for detailed information on testing Angular applications. -## Testing Principles +## Testing Principles {/* #testing-principles */} When testing an application, it is best to keep in mind that testing can show if defects are present in a system. However, it is impossible to prove that any non-trivial system is completely free of defects. For this reason, the goal of testing is not to verify that the code is correct but to find problems within the code. This is a subtle but important distinction. @@ -20,7 +20,7 @@ If we set out to prove that the code is correct, we are more likely to stick to It is also best to begin testing an application from the very start. This allows defects to be found early in the process when they are easier to fix. This also allows code to be refactored with confidence as new features are added to the system. -## Unit Testing +## Unit Testing {/* #unit-testing */} Unit tests exercise a single unit of code (component, page, service, pipe, etc) in isolation from the rest of the system. Isolation is achieved through the injection of mock objects in place of the code's dependencies. The mock objects allow the test to have fine-grained control of the outputs of the dependencies. The mocks also allow the test to determine which dependencies have been called and what has been passed to them. @@ -28,7 +28,7 @@ Well-written unit tests are structured such that the unit of code and the featur Since unit tests exercise the code in isolation, they are fast, robust, and allow for a high degree of code coverage. -### Using Mocks +### Using Mocks {/* #using-mocks */} Unit tests exercise a code module in isolation. To facilitate this, we recommend using Jasmine (https://jasmine.github.io/). Jasmine creates mock objects (which Jasmine calls "spies") to take the place of dependencies while testing. When a mock object is used, the test can control the values returned by calls to that dependency, making the current test independent of changes made to the dependency. This also makes the test setup easier, allowing the test to only be concerned with the code within the module under test. @@ -36,19 +36,19 @@ Using mocks also allows the test to query the mock to determine if it was called There are two common ways to create mock objects in Jasmine. Mock objects can be constructed from scratch using `jasmine.createSpy` and `jasmine.createSpyObj` or spies can be installed onto existing objects using `spyOn()` and `spyOnProperty()`. -#### Using `jasmine.createSpy` and `jasmine.createSpyObj` +#### Using `jasmine.createSpy` and `jasmine.createSpyObj` {/* #using-jasminecreatespy-and-jasminecreatespyobj */} `jasmine.createSpyObj` creates a full mock object from scratch with a set of mock methods defined on creation. This is useful in that it is very simple. Nothing needs to be constructed or injected into the test. The disadvantage of using this function is that it allows the creation of objects that may not match the real objects. `jasmine.createSpy` is similar but it creates a stand-alone mock function. -#### Using `spyOn()` and `spyOnProperty()` +#### Using `spyOn()` and `spyOnProperty()` {/* #using-spyon-and-spyonproperty */} `spyOn()` installs the spy on an existing object. The advantage of using this technique is that if an attempt is made to spy on a method that does not exist on the object, an exception is raised. This prevents the test from mocking methods that do not exist. The disadvantage is that the test needs a fully formed object to begin with, which may increase the amount of test setup required. `spyOnProperty()` is similar with the difference being that it spies on a property and not a method. -### General Testing Structure +### General Testing Structure {/* #general-testing-structure */} Unit tests are contained in `spec` files with one `spec` file per entity (component, page, service, pipe, etc.). The `spec` files live side-by-side with and are named after the source that they are testing. For example, if the project has a service called WeatherService, the code for it is in a file named `weather.service.ts` with the tests in a file named `weather.service.spec.ts`. Both of those files are in the same folder. @@ -74,7 +74,7 @@ describe('Calculation', () => { The outer `describe` call states that the `Calculation` service is being tested, the inner `describe` calls state exactly what functionality is being tested, and the `it` calls state what the test cases are. When run the full label for each test case is a sentence that makes sense (Calculation divide cowardly refuses to divide by zero). -### Pages and Components +### Pages and Components {/* #pages-and-components */} Pages are just Angular components. Thus, pages and components are both tested using [Angular's Component Testing](https://angular.io/guide/testing#component-test-basics) guidelines. @@ -109,7 +109,7 @@ describe('TabsPage', () => { When doing component class testing, the component object is accessed using the component object defined via `component = fixture.componentInstance;`. This is an instance of the component class. When doing DOM testing, the `fixture.nativeElement` property is used. This is the actual `HTMLElement` for the component, which allows the test to use standard HTML API methods such as `HTMLElement.querySelector` in order to examine the DOM. -### Waiting for Components +### Waiting for Components {/* #waiting-for-components */} When testing Ionic components, use the `componentOnReady` helper exported from `@ionic/core` rather than calling `el.componentOnReady()` directly. The `el.componentOnReady()` method only exists on lazy-loaded elements and calling it directly throws an error on custom-element builds, which is what standalone projects use. The helper handles both. It awaits the element's own `componentOnReady()` promise when that exists. Otherwise it waits one animation frame, giving the component's inner contents a chance to render. Wait for the callback before asserting against the rendered DOM or running accessibility tests. @@ -137,11 +137,11 @@ describe('HomePage', () => { }); ``` -## Services +## Services {/* #services */} Services often fall into one of two broad categories: utility services that perform calculations and other operations, and data services that perform primarily HTTP operations and data manipulation. -### Basic Service Testing +### Basic Service Testing {/* #basic-service-testing */} The suggested way to test most services is to instantiate the service and manually inject mocks for any dependency the service has. This way, the code can be tested in isolation. @@ -206,7 +206,7 @@ describe('PayrolService', () => { }); ``` -#### Testing HTTP Data Services +#### Testing HTTP Data Services {/* #testing-http-data-services */} Most services that perform HTTP operations will use Angular's HttpClient service in order to perform those operations. For such tests, it is suggested to use Angular's `HttpClientTestingModule`. For detailed documentation of this module, please refer to Angular's [Angular's Testing HTTP requests](https://angular.io/guide/http#testing-http-requests) guide. @@ -257,7 +257,7 @@ describe('IssTrackingDataService', () => { }); ``` -### Pipes +### Pipes {/* #pipes */} A pipe is like a service with a specifically defined interface. It is a class that contains one public method, `transform`, which manipulates the input value (and other optional arguments) in order to create the output that is rendered on the page. To test a pipe: instantiate the pipe, call the transform method, and verify the results. @@ -309,13 +309,13 @@ describe('NamePipe', () => { It is also beneficial to exercise the pipe via DOM testing in the components and pages that utilize the pipe. -## End-to-end Testing +## End-to-end Testing {/* #end-to-end-testing */} End-to-end testing is used to verify that an application works as a whole and often includes a connection to live data. Whereas unit tests focus on code units in isolation and thus allow for low-level testing of the application logic, end-to-end tests focus on various user stories or usage scenarios, providing high-level testing of the overall flow of data through the application. Whereas unit tests try to uncover problems with an application's logic, end-to-end tests try to uncover problems that occur when those individual units are used together. End-to-end tests uncover problems with the overall architecture of the application. Since end-to-end tests exercise user stories and cover the application as a whole rather than individual code modules, end-to-end tests exist in their own application in the project apart from the code for the main application itself. Most end-to-end tests operate by automating common user interactions with the application and examining the DOM to determine the results of those interactions. -### Test Structure +### Test Structure {/* #test-structure */} When an `@ionic/angular` application is generated, a default end-to-end test application is generated in the `e2e` folder. This application uses Protractor to control the browser and Jasmine to structure and execute the tests. The application initially consists of four files: @@ -324,13 +324,13 @@ When an `@ionic/angular` application is generated, a default end-to-end test app - `src/app.po.ts` - a page object containing methods that navigate the application, query elements in the DOM, and manipulate elements on the page - `src/app.e2e-spec.ts` - a testing script -#### Page Objects +#### Page Objects {/* #page-objects */} End-to-end tests operate by automating common user interactions with the application, waiting for the application to respond, and examining the DOM to determine the results of the interaction. This involves a lot of DOM manipulation and examination. If this were all done manually, the tests would be very brittle and difficult to read and maintain. Page objects encapsulate the HTML for a single page in a TypeScript class, providing an API that the test scripts use to interact with the application. The encapsulation of the DOM manipulation logic in page objects makes the tests more readable and far easier to reason about, lowering the maintenance costs of the test. Creating well-crafted page objects is the key to creating high quality and maintainable end-to-end tests. -##### Base Page Object +##### Base Page Object {/* #base-page-object */} A lot of tests rely on actions such as waiting for a page to be visible, entering text into an input, and clicking a button. The methods used to do this remain consistent with only the CSS selectors used to get the appropriate DOM element changing. Therefore it makes sense to abstract this logic into a base class that can be used by the other page objects. @@ -396,7 +396,7 @@ export class PageObjectBase { } ``` -##### Per-Page Abstractions +##### Per-Page Abstractions {/* #per-page-abstractions */} Each page in the application will have its own page object class that abstracts the elements on that page. If a base page object class is used, creating the page object involves mostly creating custom methods for elements that are specific to that page. Often, these custom elements take advantage of methods in the base class in order to perform the work that is required. @@ -433,7 +433,7 @@ export class LoginPage extends PageObjectBase { } ``` -#### Testing Scripts +#### Testing Scripts {/* #testing-scripts */} Similar to unit tests, end-to-end test scripts consist of nested `describe()` and `it()` functions. In the case of end-to-end tests, the `describe()` functions generally denote specific scenarios with the `it()` functions denoting specific behaviors that should be exhibited by the application as actions are performed within that scenario. @@ -527,15 +527,15 @@ describe('Login', () => { }); ``` -### Configuration +### Configuration {/* #configuration */} The default configuration uses the same `environment.ts` file that is used for development. In order to provide better control over the data used by the end-to-end tests, it is often useful to create a specific environment for testing and use that environment for the tests. This section shows one possible way to create this configuration. -#### Testing Environment +#### Testing Environment {/* #testing-environment */} Setting up a testing environment involves creating a new environment file that uses a dedicated testing backend, updating the `angular.json` file to use that environment, and modifying the `e2e` script in the `package.json` to specify the `test` environment. -##### Create the `environment.e2e.ts` File +##### Create the `environment.e2e.ts` File {/* #create-the-environmente2ets-file */} The Angular `environment.ts` and `environment.prod.ts` files are often used to store information such as the base URL for the application's backend data services. Create an `environment.e2e.ts` that provides the same information, only connecting to backend services that are dedicated to testing rather than the development or production backend services. Here is an example: @@ -547,7 +547,7 @@ export const environment = { }; ``` -##### Modify the `angular.json` File +##### Modify the `angular.json` File {/* #modify-the-angularjson-file */} The `angular.json` file needs to be modified to use this file. This is a layered process. Follow the XPaths listed below to add the configuration that is required. @@ -580,7 +580,7 @@ Add a configuration at `/projects/app-e2e/architect/e2e/configurations` called ` } ``` -##### Modify the `package.json` File +##### Modify the `package.json` File {/* #modify-the-packagejson-file */} Modify the `package.json` file so that `npm run e2e` uses the `test` configuration. @@ -596,7 +596,7 @@ Modify the `package.json` file so that `npm run e2e` uses the `test` configurati }, ``` -#### Test Cleanup +#### Test Cleanup {/* #test-cleanup */} If the end-to-end tests modify data in any way it is helpful to reset the data to a known state once the test completes. One way to do that is to: diff --git a/docs/angular/virtual-scroll.mdx b/docs/angular/virtual-scroll.mdx index 0ee3289bf3d..d3b799e1fbc 100644 --- a/docs/angular/virtual-scroll.mdx +++ b/docs/angular/virtual-scroll.mdx @@ -6,7 +6,7 @@ ::: -## Installation +## Installation {/* #installation */} To setup the CDK Scroller, first install `@angular/cdk`: @@ -43,7 +43,7 @@ When we want to use the CDK Scroller, we'll need to import the module in our com With this added, we have access to the Virtual Scroller in the Tab1Page component. -## Usage +## Usage {/* #usage */} The CDK Virtual Scroller can be added to a component by adding the `cdk-virtual-scroll-viewport` to a component's template. @@ -114,7 +114,7 @@ cdk-virtual-scroll-viewport { Since the viewport is built to fit various use cases, the default sizing is not set and is up to developers to set. -## Usage with Ionic Components +## Usage with Ionic Components {/* #usage-with-ionic-components */} Ionic Framework requires that features such as collapsible large titles, `ion-infinite-scroll`, `ion-refresher`, and `ion-reorder-group` be used within an `ion-content`. To use these experiences with virtual scrolling, you must add the `.ion-content-scroll-host` class to the virtual scroll viewport. @@ -128,6 +128,6 @@ For example: ``` -## Further Reading +## Further Reading {/* #further-reading */} This only covers a small portion of what the CDK Virtual Scroller is capable of. For more details, please refer to the [Angular CDK Virtual Scrolling docs](https://material.angular.io/cdk/scrolling/overview). diff --git a/docs/angular/your-first-app.mdx b/docs/angular/your-first-app.mdx index 9da4af2492b..7db2aaac485 100644 --- a/docs/angular/your-first-app.mdx +++ b/docs/angular/your-first-app.mdx @@ -24,13 +24,7 @@ Here’s the finished app running on all 3 platforms: allowFullScreen > -:::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.mdx). - -::: - -## What We'll Build +## What We'll Build {/* #what-well-build */} We'll create a Photo Gallery app that offers the ability to take photos with your device's camera, display them in a grid, and store them permanently on the device. @@ -42,7 +36,7 @@ Highlights include: Find the [complete app code](https://github.com/ionic-team/tutorial-photo-gallery-angular) referenced in this guide on GitHub. -## Download Required Tools +## Download Required Tools {/* #download-required-tools */} Download and install these right away to ensure an optimal Ionic development experience: @@ -52,7 +46,7 @@ Download and install these right away to ensure an optimal Ionic development exp - **Windows** users: for the best Ionic experience, we recommend the built-in command line (cmd) or the Powershell CLI, running in Administrator mode. - **Mac/Linux** users: virtually any terminal will work. -## Install Ionic Tooling +## Install Ionic Tooling {/* #install-ionic-tooling */} 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: @@ -74,7 +68,7 @@ Consider setting up npm to operate globally without elevated permissions. Refer ::: -## Create an App +## Create an App {/* #create-an-app */} Next, create an Ionic Angular app that uses the "Tabs" starter template and adds Capacitor for native functionality: @@ -102,7 +96,7 @@ Next we'll need to install the necessary Capacitor plugins to make the app's nat npm install @capacitor/camera @capacitor/preferences @capacitor/filesystem ``` -### PWA Elements +### PWA Elements {/* #pwa-elements */} Some Capacitor plugins, including the [Camera API](/native/camera.mdx), provide the web-based functionality and UI via the Ionic [PWA Elements library](https://github.com/ionic-team/pwa-elements). @@ -138,7 +132,7 @@ bootstrapApplication(AppComponent, { That’s it! Now for the fun part - let’s run the app. -## Run the App +## Run the App {/* #run-the-app */} Run this command next: @@ -148,7 +142,7 @@ ionic serve And voilà! Your Ionic app is now running in a web browser. Most of your app can be built and tested right in the browser, greatly increasing development and testing speed. -## Photo Gallery +## Photo Gallery {/* #photo-gallery */} There are three tabs. Click on the "Tab2" tab. It’s a blank canvas, aka the perfect spot to transform into a Photo Gallery. The Ionic CLI features Live Reload, so when you make changes and save them, the app is updated immediately! diff --git a/docs/angular/your-first-app/2-taking-photos.mdx b/docs/angular/your-first-app/2-taking-photos.mdx index 2da3b1d7f76..898e2d6fc99 100644 --- a/docs/angular/your-first-app/2-taking-photos.mdx +++ b/docs/angular/your-first-app/2-taking-photos.mdx @@ -13,7 +13,7 @@ sidebar_label: Taking Photos Now for the fun part - adding the ability to take photos with the device’s camera using the Capacitor [Camera API](/native/camera.mdx). We’ll begin with building it for the web, then make some small tweaks to make it work on mobile (iOS and Android). -## Photo Service +## Photo Service {/* #photo-service */} All Capacitor logic (Camera usage and other native features) will be encapsulated in a service class. Create `PhotoService` using the `ionic generate` command: @@ -143,7 +143,7 @@ _(Your selfie is probably much better than mine)_ After taking a photo, it disappears right away. We need to display it within our app and save it for future access. -## Displaying Photos +## Displaying Photos {/* #displaying-photos */} To define the data structure for our photo metadata, create a new interface named `UserPhoto`. Add this interface at the very bottom of the `photo.service.ts` file, immediately after the `PhotoService` class definition: diff --git a/docs/angular/your-first-app/3-saving-photos.mdx b/docs/angular/your-first-app/3-saving-photos.mdx index 9cd3743f41e..5529c6dbd2c 100644 --- a/docs/angular/your-first-app/3-saving-photos.mdx +++ b/docs/angular/your-first-app/3-saving-photos.mdx @@ -13,7 +13,7 @@ sidebar_label: Saving Photos We’re now able to take multiple photos and display them in a photo gallery on the second tab of our app. These photos, however, are not currently being stored permanently, so when the app is closed, they will be deleted. -## Filesystem API +## Filesystem API {/* #filesystem-api */} Fortunately, saving them to the filesystem only takes a few steps. Begin by creating a new class method, `savePicture()`, in the `PhotoService` class. We pass in the `photo` object, which represents the newly captured device photo: diff --git a/docs/angular/your-first-app/4-loading-photos.mdx b/docs/angular/your-first-app/4-loading-photos.mdx index 3ff9608ebc2..5a5b5fc6263 100644 --- a/docs/angular/your-first-app/4-loading-photos.mdx +++ b/docs/angular/your-first-app/4-loading-photos.mdx @@ -15,7 +15,7 @@ We’ve implemented photo taking and saving to the filesystem. There’s one las Fortunately, this is easy: we’ll leverage the Capacitor [Preferences API](/native/preferences.mdx) to store our array of Photos in a key-value store. -## Preferences API +## Preferences API {/* #preferences-api */} Open `photo.service.ts` and begin by defining a new property in the `PhotoService` class that will act as the key for the store. diff --git a/docs/angular/your-first-app/5-adding-mobile.mdx b/docs/angular/your-first-app/5-adding-mobile.mdx index b3736d50de6..0f3ce3eb080 100644 --- a/docs/angular/your-first-app/5-adding-mobile.mdx +++ b/docs/angular/your-first-app/5-adding-mobile.mdx @@ -13,7 +13,7 @@ strip_number_prefixes: false Our photo gallery app won’t be complete until it runs on iOS, Android, and the web - all using one codebase. All it takes is some small logic changes to support mobile platforms, installing some native tooling, then running the app on a device. Let’s go! -## Import Platform API +## Import Platform API {/* #import-platform-api */} Let’s start with making some small code changes - then our app will “just work” when we deploy it to a device. @@ -45,7 +45,7 @@ export class PhotoService { } ``` -## Platform-specific Logic +## Platform-specific Logic {/* #platform-specific-logic */} First, we’ll update the photo saving functionality to support mobile. In the `savePicture()` method, check which platform the app is running on. If it’s “hybrid” (Capacitor, the native runtime), then read the photo file into base64 format using the `Filesystem.readFile()` method. Otherwise, use the same logic as before when running the app on the web. diff --git a/docs/angular/your-first-app/6-deploying-mobile.mdx b/docs/angular/your-first-app/6-deploying-mobile.mdx index b7ad08e6920..bf2b0963591 100644 --- a/docs/angular/your-first-app/6-deploying-mobile.mdx +++ b/docs/angular/your-first-app/6-deploying-mobile.mdx @@ -13,7 +13,7 @@ sidebar_label: Deploying Mobile Since we added Capacitor to our project when it was first created, there’s only a handful of steps remaining until the Photo Gallery app is on our device! -## Capacitor Setup +## Capacitor Setup {/* #capacitor-setup */} Capacitor is Ionic’s official app runtime that makes it easy to deploy web apps to native platforms like iOS, Android, and more. If you’ve used Cordova in the past, consider reading more about the [differences between Capacitor and Cordova](https://capacitorjs.com/docs/cordova#differences-between-capacitor-and-cordova). @@ -44,7 +44,7 @@ Note: After making updates to the native portion of the code (such as adding a n ionic cap sync ``` -## iOS Deployment +## iOS Deployment {/* #ios-deployment */} :::important @@ -82,7 +82,7 @@ Upon tapping the Camera button on the Photo Gallery tab, the permission prompt w ![Two iPhones side by side, one showing the camera permission prompt and the other displaying a photo taken with the app.](/img/guides/first-app-cap-ng/ios-permissions-photo.png 'iOS Camera Permission Prompt and Photo Result') -## Android Deployment +## Android Deployment {/* #android-deployment */} Capacitor Android apps are configured and managed through Android Studio. Before running this app on an Android device, there's a couple of steps to complete. diff --git a/docs/angular/your-first-app/7-live-reload.mdx b/docs/angular/your-first-app/7-live-reload.mdx index c300e4730ac..74dac3b0cf0 100644 --- a/docs/angular/your-first-app/7-live-reload.mdx +++ b/docs/angular/your-first-app/7-live-reload.mdx @@ -15,7 +15,7 @@ So far, we’ve learned how easy it is to develop a cross-platform app that work We can use the Ionic CLI’s [Live Reload functionality](../../cli/livereload.mdx) to boost our productivity when building Ionic apps. When active, Live Reload will reload the browser and/or WebView when changes in the app are detected. -## Live Reload +## Live Reload {/* #live-reload */} Remember `ionic serve`? That was Live Reload working in the browser, allowing us to iterate quickly. @@ -31,7 +31,7 @@ ionic cap run android -l --external The Live Reload server will start up, and the native IDE of choice will open if not opened already. Within the IDE, click the Play button to launch the app onto your device. -## Deleting Photos +## Deleting Photos {/* #deleting-photos */} With Live Reload running and the app open on your device, let’s implement photo deletion functionality. diff --git a/docs/angular/your-first-app/8-distribute.mdx b/docs/angular/your-first-app/8-distribute.mdx index f029858cb9b..d397a887f3e 100644 --- a/docs/angular/your-first-app/8-distribute.mdx +++ b/docs/angular/your-first-app/8-distribute.mdx @@ -15,13 +15,13 @@ Now that you have built your first app, you are going to want to get it distribu Below we will run through an overview of the steps. -## Connect Your Repo +## Connect Your Repo {/* #connect-your-repo */} Appflow works directly with Git version control and uses your existing code base as the source of truth for Deploy and Package builds. You will first need to integrate with your hosting service, such as GitHub or Bitbucket, or you can push your code directly to Appflow. Once this is completed, Appflow will have access to your code. For more on connecting your code repository to Appflow, checkout the [Connect your Repo](https://ionic.io/docs/appflow/quickstart/connect) section inside the Appflow docs. -## Install the Appflow SDK +## Install the Appflow SDK {/* #install-the-appflow-sdk */} The Appflow SDK (also known as Ionic Deploy plugin) will allow you to take advantage of arguably two of the best Appflow features: deploying live updates to your app and bypassing the app stores. Ionic Appflow's Live Update feature is shipped with Appflow SDK and features the capabilities of detecting and syncing the updates for your app that you have pushed to your identified channels within the dashboard. @@ -36,7 +36,7 @@ ionic deploy add \ For prerequisite and additional instructions on installing the Appflow SDK, visit the [Install the Appflow SDK](https://ionic.io/docs/appflow/quickstart/installation) section inside the Appflow docs. -## Push a Commit +## Push a Commit {/* #push-a-commit */} In order for Appflow to access the latest and greatest changes to your code, you will need to push a commit via the version control integration of your choosing. For those that use GitHub or Bitbucket, this would look as follows: @@ -48,7 +48,7 @@ git push origin main # push the changes from the main branch to your git host After the push is made, your commit appears under the `Commits` tab of the Appflow Dashboard. For more information, refer to the [Push a Commit](https://ionic.io/docs/appflow/quickstart/push) section inside the Appflow docs. -## Deploy a Live Update +## Deploy a Live Update {/* #deploy-a-live-update */} With the Appflow SDK installed and your commit pushed up to the Dashboard, you are ready to deploy a live update to a device. The Live Update feature uses the installed Appflow SDK with your native application to listen to a particular Deploy Channel Destination. When a live update is assigned to a Channel Destination, that update will be deployed to user devices running binaries that are configured to listen to that specific Channel Destination. @@ -66,7 +66,7 @@ Assuming the app is configured correctly to listen to the channel you deployed t To dive into more details on the steps to deploy a live update, as well as additional information such as disabling deploy for development, check out the [Deploy a Live Update](https://ionic.io/docs/appflow/quickstart/deploy) section inside the Appflow docs. -## Build a Native Binary +## Build a Native Binary {/* #build-a-native-binary */} Next up is a native binary for your app build and deploy process. This is done via the [Ionic Package](https://ionic.io/docs/appflow/package/intro) service. First things first, you will need to create a [Package build](https://ionic.io/docs/appflow/package/builds). This can be done by clicking the `Start build` icon from the `Commits` tab or by clicking the `New build` button in the top right from the `Build > Builds` tab. Then you will select the proper commit for your build and fill in all of the several required fields and any optional fields that you want to specify. After filling in all of the information and the build begins, you can check out it's progress and review the logs if you encounter any errors. @@ -74,19 +74,19 @@ Given a successful Package build, an iOS binary (`.ipa` or IPA) or/and an Androi Further information regarding building native binaries can be found inside of the [Build a Native Binary](https://ionic.io/docs/appflow/quickstart/package) section inside the Appflow docs. -## Create an Automation +## Create an Automation {/* #create-an-automation */} [Automations](https://ionic.io/docs/appflow/automation/intro) enable you and your team to utilize the full CI/CD powers of Appflow. You can create automations that trigger [Package builds](https://ionic.io/docs/appflow/package/builds) and [Deploy builds](https://ionic.io/docs/appflow/deploy/builds) every time your team commits new code to a given branch. The automations can also be configured to use different environments and native configurations for building different versions of your app for development, staging, QA and production. For more information, visit the [Create an Automation](https://ionic.io/docs/appflow/quickstart/automation) section within the Appflow docs. That section covers creating a single automation. However, you can create multiple automations for different branches or workflows and customize them to fit your needs. An important note is that the ability to create an automation is available for those on our [Basic plans](https://ionic.io/pricing) and above. -## Create an Environment +## Create an Environment {/* #create-an-environment */} [Package builds](https://ionic.io/docs/appflow/package/builds) and [Deploy builds](https://ionic.io/docs/appflow/deploy/builds) can be further customized via [Environments](https://ionic.io/docs/appflow/automation/environments). This powerful feature allows you to create different configurations based on the environment variables passed in at build time. When combined with the [Automation](https://ionic.io/docs/appflow/automation/intro) feature, development teams can easily configure development, staging, and production build configurations, allowing them to embrace DevOps best practices and ship better quality updates faster than ever. Creating an Environment is available for those on our [Basic plans](https://ionic.io/pricing) and above. More information on this can be found in the [Create an Environment](https://ionic.io/docs/appflow/quickstart/environment) section within the Appflow docs. -## Create a Native Configuration +## Create a Native Configuration {/* #create-a-native-configuration */} [Native Configurations](https://ionic.io/docs/appflow/package/native-configs) allow you to easily modify common configuration values that can change between different environments (development, production, staging, etc.) so you do not need to use extra logic or manually commit them to version control. Native configurations can be attached to any [Package build](https://ionic.io/docs/appflow/package/intro) or [Automation](https://ionic.io/docs/appflow/automation/intro). @@ -98,7 +98,7 @@ Native configs can be used to: For access to the ability to create a Native Configuration, you will need to be on our [Basic plans](https://ionic.io/pricing) and above. Additional details of this feature can be found in the [Create a Native Configuration](https://ionic.io/docs/appflow/quickstart/native-config) section within the Appflow docs. -## What’s Next? +## What’s Next? {/* #whats-next */} Congratulations! You developed a complete cross-platform Photo Gallery app that runs on the web, iOS, and Android. Not only that, you have also then built the app and deployed it to your users' devices! diff --git a/docs/angular/zoneless.mdx b/docs/angular/zoneless.mdx index 90ad3c2bf98..dfe025eadc3 100644 --- a/docs/angular/zoneless.mdx +++ b/docs/angular/zoneless.mdx @@ -15,7 +15,7 @@ Angular 21 made [zoneless change detection](https://angular.dev/guide/zoneless) With Zone.js, Angular automatically re-renders after almost any asynchronous task. Without it, Angular only re-renders when you explicitly tell it the view is out of date. Most of your app keeps working unchanged, but a few patterns that relied on Zone.js need a small adjustment. -## What keeps working automatically +## What keeps working automatically {/* #what-keeps-working-automatically */} You do not need to change these. Angular schedules change detection for them in a zoneless app: @@ -32,7 +32,7 @@ Angular 22 also makes `OnPush` the default change detection strategy. Under `OnP ::: -## What needs a notification +## What needs a notification {/* #what-needs-a-notification */} When you update component state from an asynchronous callback that Angular did not wrap, nothing schedules a re-render. The state changes, but the view does not update. This applies to any Angular code, not only Ionic, and the common sources in an Ionic app are: @@ -43,7 +43,7 @@ When you update component state from an asynchronous callback that Angular did n You can notify Angular in two ways: write to a [signal](https://angular.dev/guide/signals) that the template reads, or inject `ChangeDetectorRef` and call `markForCheck()` after the update. We recommend signals because they work the same with or without Zone.js. -### Signals (recommended) +### Signals (recommended) {/* #signals-recommended */} Writing a signal that a template reads schedules change detection automatically, so there is nothing extra to remember after the update. @@ -74,7 +74,7 @@ export class HomePage { } ``` -### `ChangeDetectorRef.markForCheck()` +### `ChangeDetectorRef.markForCheck()` {/* #changedetectorrefmarkforcheck */} If you are not using signals for a particular piece of state, inject `ChangeDetectorRef` and call `markForCheck()` after the asynchronous update. It is a no-op-or-better under Zone.js, so it is safe to leave in place if you later re-enable zones. @@ -101,11 +101,11 @@ export class ListPage { } ``` -## Common Ionic patterns +## Common Ionic patterns {/* #common-ionic-patterns */} These apply the two approaches above to patterns you are likely to hit in an Ionic app. -### Inline overlays with dynamic content +### Inline overlays with dynamic content {/* #inline-overlays-with-dynamic-content */} Content projected into an inline `ion-modal` or `ion-popover` follows the same rule. If you populate it asynchronously, update a signal or call `markForCheck()`: @@ -136,7 +136,7 @@ export class InlinePage { Inline overlays also expose their events as outputs (for example `ionModalDidDismiss`), which you can convert to a signal with [`toSignal`](https://angular.dev/api/core/rxjs-interop/toSignal) if you prefer a reactive style. -### Platform events +### Platform events {/* #platform-events */} `Platform` exposes its events as RxJS subjects. Update a signal inside the subscription so the view reflects the change: @@ -153,7 +153,7 @@ export class AppComponent { } ``` -## Change detection on Angular 22 +## Change detection on Angular 22 {/* #change-detection-on-angular-22 */} On Angular 22 a component that does not declare a strategy is `OnPush`. If your pages keep state in plain fields rather than signals, every component from your application root down to the one hosting `ion-router-outlet` or `ion-tabs` (your app shell) must stay eager. A tick starts at the application root and skips a clean `OnPush` view and everything below it, so an `OnPush` ancestor strands the page even when the page itself is eager: @@ -172,6 +172,6 @@ If other components sit between your application root and `ion-router-outlet`, e Hosting an `ion-nav` is fine either way, because its pages are attached as root views and are checked independently of the component hosting them. -## Staying on Zone.js +## Staying on Zone.js {/* #staying-on-zonejs */} If you are not ready to adopt zoneless change detection, you can opt back into Zone.js with `provideZoneChangeDetection()`. Refer to the [Keeping Zone.js section of the Ionic 9 upgrade guide](/updating/9-0.mdx#keeping-zonejs) for the exact configuration. diff --git a/docs/api/accordion-group.mdx b/docs/api/accordion-group.mdx index e5ac64dc415..d189bcaa776 100644 --- a/docs/api/accordion-group.mdx +++ b/docs/api/accordion-group.mdx @@ -17,9 +17,9 @@ Accordion group is a container for accordion instances. It manages the state of Refer to the [Accordion](./accordion) documentation for more information. -## Interfaces +## Interfaces {/* #interfaces */} -### AccordionGroupChangeEventDetail +### AccordionGroupChangeEventDetail {/* #accordiongroupchangeeventdetail */} ```typescript interface AccordionGroupChangeEventDetail { @@ -27,7 +27,7 @@ interface AccordionGroupChangeEventDetail { } ``` -### AccordionGroupCustomEvent +### AccordionGroupCustomEvent {/* #accordiongroupcustomevent */} While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component. @@ -38,26 +38,26 @@ interface AccordionGroupCustomEvent extends CustomEvent { } ``` -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/accordion.mdx b/docs/api/accordion.mdx index 8d301027b52..283424b0f97 100644 --- a/docs/api/accordion.mdx +++ b/docs/api/accordion.mdx @@ -23,13 +23,13 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Accordions provide collapsible sections in your content to reduce vertical space while providing a way of organizing and grouping information. All `ion-accordion` components should be grouped inside `ion-accordion-group` components. -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/accordion/basic/index.mdx'; -## Toggle Accordions +## Toggle Accordions {/* #toggle-accordions */} Which accordion is open is controlled by setting the `value` property on `ion-accordion-group`. Setting this property allows developers to programmatically expand or collapse certain accordions. @@ -37,7 +37,7 @@ import Toggle from '@site/static/usage/v10/accordion/toggle/index.mdx'; -## Listen for Accordion State Changes +## Listen for Accordion State Changes {/* #listen-for-accordion-state-changes */} :::caution @@ -53,7 +53,7 @@ import ListenChanges from '@site/static/usage/v10/accordion/listen-changes/index -## Multiple Accordions +## Multiple Accordions {/* #multiple-accordions */} Developers can allow multiple accordions to be open at once with the `multiple` property. @@ -61,9 +61,9 @@ import Multiple from '@site/static/usage/v10/accordion/multiple/index.mdx'; -## Disabling Accordions +## Disabling Accordions {/* #disabling-accordions */} -### Individual Accordion +### Individual Accordion {/* #individual-accordion */} Individual accordions can be disabled with the `disabled` property on `ion-accordion`. @@ -71,7 +71,7 @@ import DisableIndividual from '@site/static/usage/v10/accordion/disable/individu -### Accordion Group +### Accordion Group {/* #accordion-group */} The accordion group can be disabled with the `disabled` property on `ion-accordion-group`. @@ -79,9 +79,9 @@ import DisableGroup from '@site/static/usage/v10/accordion/disable/group/index.m -## Readonly Accordions +## Readonly Accordions {/* #readonly-accordions */} -### Individual Accordion +### Individual Accordion {/* #individual-accordion-1 */} Individual accordions can be disabled with the `readonly` property on `ion-accordion`. @@ -89,7 +89,7 @@ import ReadonlyIndividual from '@site/static/usage/v10/accordion/readonly/indivi -### Accordion Group +### Accordion Group {/* #accordion-group-1 */} The accordion group can be disabled with the `readonly` property on `ion-accordion-group`. @@ -97,21 +97,21 @@ import ReadonlyGroup from '@site/static/usage/v10/accordion/readonly/group/index -## Anatomy +## Anatomy {/* #anatomy */} -### Header +### Header {/* #header */} The `header` slot is used as the toggle that will expand or collapse your accordion. We recommend you use an `ion-item` here to take advantage of the accessibility and theming functionalities. When using `ion-item` in the `header` slot, the `ion-item`'s `button` prop is set to `true` and the `detail` prop is set to `false`. In addition, we will also automatically add a toggle icon to the `ion-item`. This icon will automatically be rotated when you expand or collapse the accordion. Refer to [Customizing Icons](#icons) for more information. -### Content +### Content {/* #content */} The `content` slot is used as the part of the accordion that is revealed or hidden depending on the state of your accordion. You can place anything here except for another `ion-content` instance as only one instance of `ion-content` should be added per page. -## Customization +## Customization {/* #customization */} -### Expansion Styles +### Expansion Styles {/* #expansion-styles */} There are two built in expansion styles: `compact` and `inset`. This expansion style is set via the `expand` property on `ion-accordion-group`. @@ -121,7 +121,7 @@ import ExpansionStyles from '@site/static/usage/v10/accordion/customization/expa -### Advanced Expansion Styles +### Advanced Expansion Styles {/* #advanced-expansion-styles */} You can customize the expansion behavior by styling based on the accordion's state. There are four state classes applied to `ion-accordion`. Styling using these classes can allow you to create advanced state transitions: @@ -145,7 +145,7 @@ import AdvancedExpansionStyles from '@site/static/usage/v10/accordion/customizat -### Icons +### Icons {/* #icons */} When using an `ion-item` in the `header` slot, we automatically add an `ion-icon`. The type of icon used can be controlled by the `toggleIcon` property, and the slot it is added to can be controlled with the `toggleIconSlot` property. @@ -157,7 +157,7 @@ import Icons from '@site/static/usage/v10/accordion/customization/icons/index.md -### Theming +### Theming {/* #theming */} Since `ion-accordion` acts as a shell around the header and content elements, you can easily theme the accordion however you would like. You can theme the header by targeting the slotted `ion-item`. Since you are using `ion-item`, you also have access to all of the [ion-item CSS Variables](./item#css-custom-properties) and [ion-item Shadow Parts](./item#css-shadow-parts). Theming the content is also easily achieved by targeting the element that is in the `content` slot. @@ -165,9 +165,9 @@ import Theming from '@site/static/usage/v10/accordion/customization/theming/inde -## Accessibility +## Accessibility {/* #accessibility */} -### Animations +### Animations {/* #animations */} By default, animations are enabled when expanding or collapsing an accordion item. Animations will be automatically disabled when the `prefers-reduced-motion` media query is supported and set to `reduce`. For browsers that do not support this, animations can be disabled by setting the `animated` config in your Ionic Framework app. @@ -175,7 +175,7 @@ import AccessibilityAnimations from '@site/static/usage/v10/accordion/accessibil -### Keyboard Interactions +### Keyboard Interactions {/* #keyboard-interactions */} When used inside an `ion-accordion-group`, `ion-accordion` has full keyboard support for interacting with the component. The following table details what each key does: @@ -189,9 +189,9 @@ When used inside an `ion-accordion-group`, `ion-accordion` has full keyboard sup | Home | When focus is on an accordion header, moves focus to the first accordion header. | | End | When focus is on an accordion header, moves focus to the last accordion header. | -## Performance +## Performance {/* #performance */} -### Animations +### Animations {/* #animations-1 */} The accordion animation works by knowing the height of the `content` slot when the animation starts. The accordion expects that this height will remain consistent throughout the animation. As a result, developers should avoid performing any operation that may change the height of the content during the animation. @@ -203,26 +203,26 @@ For example, lazily loading images may cause layout shifts as they load. As the 3. If neither of these options are applicable, developers may want to consider disabling animations altogether by using the `animated` property on [ion-accordion-group](./accordion-group). -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/action-sheet.mdx b/docs/api/action-sheet.mdx index 18c4e844df4..bda3e8bc307 100644 --- a/docs/api/action-sheet.mdx +++ b/docs/api/action-sheet.mdx @@ -26,7 +26,7 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; An Action Sheet is a dialog that displays a set of options. It appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. Destructive options are made obvious in `ios` mode. There are multiple ways to dismiss the action sheet, including tapping the backdrop or hitting the escape key on desktop. -## Inline Action Sheets (Recommended) +## Inline Action Sheets (Recommended) {/* #inline-action-sheets-recommended */} `ion-action-sheet` can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the Action Sheet. @@ -34,7 +34,7 @@ import Trigger from '@site/static/usage/v10/action-sheet/inline/trigger/index.md -### Using `isOpen` +### Using `isOpen` {/* #using-isopen */} The `isOpen` property on `ion-action-sheet` allows developers to control the presentation state of the Action Sheet from their application state. This means when `isOpen` is set to `true` the Action Sheet will be presented, and when `isOpen` is set to `false` the Action Sheet will be dismissed. @@ -44,7 +44,7 @@ import IsOpen from '@site/static/usage/v10/action-sheet/inline/isOpen/index.mdx' -## Controller Action Sheets +## Controller Action Sheets {/* #controller-action-sheets */} The `actionSheetController` can be used in situations where more control is needed over when the Action Sheet is presented and dismissed. @@ -52,13 +52,13 @@ import Controller from '@site/static/usage/v10/action-sheet/controller/index.mdx -## Buttons +## Buttons {/* #buttons */} A button's `role` property can either be `destructive` or `cancel`. Buttons without a role property will have the default look for the platform. Buttons with the `cancel` role will always load as the bottom button, no matter where they are in the array. All other buttons will be displayed in the order they have been added to the `buttons` array. Note: We recommend that `destructive` buttons are always the first button in the array, making them the top button. Additionally, if the action sheet is dismissed by tapping the backdrop, then it will fire the handler from the button with the cancel role. A button can also be passed data via the `data` property on `ActionSheetButton`. This will populate the `data` field in the return value of the `onDidDismiss` method. -## Collecting Role Information on Dismiss +## Collecting Role Information on Dismiss {/* #collecting-role-information-on-dismiss */} When the `didDismiss` event is fired, the `data` and `role` fields of the event detail can be used to gather information about how the Action Sheet was dismissed. @@ -66,11 +66,11 @@ import RoleInfo from '@site/static/usage/v10/action-sheet/role-info-on-dismiss/i -## Theming +## Theming {/* #theming */} Action Sheet uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector. -### Styling +### Styling {/* #styling */} We recommend passing a custom class to `cssClass` in the `create` method and using that to add custom styles to the host and inner elements. This property can also accept multiple classes separated by spaces. @@ -90,7 +90,7 @@ import Styling from '@site/static/usage/v10/action-sheet/theming/styling/index.m -### CSS Custom Properties +### CSS Custom Properties {/* #css-custom-properties */} Any of the defined [CSS Custom Properties](#css-custom-properties-1) can be used to style the Action Sheet without needing to target individual elements. @@ -98,17 +98,17 @@ import CssCustomProperties from '@site/static/usage/v10/action-sheet/theming/css -## Accessibility +## Accessibility {/* #accessibility */} -### Screen Readers +### Screen Readers {/* #screen-readers */} Action Sheets set aria properties in order to be [accessible](../reference/glossary#a11y) to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the action sheet is being used in an app. -#### Role +#### Role {/* #role */} Action Sheets are given a `role` of [`dialog`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/dialog_role). In order to align with the ARIA spec, either the `aria-label` or `aria-labelledby` attribute must be set. -#### Action Sheet Description +#### Action Sheet Description {/* #action-sheet-description */} It is strongly recommended that every Action Sheet have the `header` property defined, as Ionic will automatically set `aria-labelledby` to point to the header element. However, if you choose not to include a `header`, an alternative is to use the `htmlAttributes` property to provide a descriptive `aria-label` or set a custom `aria-labelledby` value. @@ -164,7 +164,7 @@ const actionSheet = await actionSheetController.create({ -#### Action Sheet Buttons Description +#### Action Sheet Buttons Description {/* #action-sheet-buttons-description */} Buttons containing text will be read by a screen reader. If a button contains only an icon, or a description other than the existing text is desired, a label should be assigned to the button by passing `aria-label` to the `htmlAttributes` property on the button. @@ -244,9 +244,9 @@ const actionSheet = await actionSheetController.create({ -## Interfaces +## Interfaces {/* #interfaces */} -### ActionSheetButton +### ActionSheetButton {/* #actionsheetbutton */} ```typescript interface ActionSheetButton { @@ -261,7 +261,7 @@ interface ActionSheetButton { } ``` -### ActionSheetOptions +### ActionSheetOptions {/* #actionsheetoptions */} ```typescript interface ActionSheetOptions { @@ -282,26 +282,26 @@ interface ActionSheetOptions { } ``` -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties-1 */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/alert.mdx b/docs/api/alert.mdx index d68636539ed..678cd99e014 100644 --- a/docs/api/alert.mdx +++ b/docs/api/alert.mdx @@ -26,7 +26,7 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; An Alert is a dialog that presents users with information or collects information from the user using inputs. An alert appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. It can also optionally have a `header`, `subHeader` and `message`. -## Inline Alerts (Recommended) +## Inline Alerts (Recommended) {/* #inline-alerts-recommended */} `ion-alert` can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the Alert. @@ -34,7 +34,7 @@ import Trigger from '@site/static/usage/v10/alert/presenting/trigger/index.mdx'; -### Using `isOpen` +### Using `isOpen` {/* #using-isopen */} The `isOpen` property on `ion-alert` allows developers to control the presentation state of the Alert from their application state. This means when `isOpen` is set to `true` the Alert will be presented, and when `isOpen` is set to `false` the Alert will be dismissed. @@ -44,7 +44,7 @@ import IsOpen from '@site/static/usage/v10/alert/presenting/isOpen/index.mdx'; -## Controller Alerts +## Controller Alerts {/* #controller-alerts */} The `alertController` can be used in situations where more control is needed over when the Alert is presented and dismissed. @@ -52,7 +52,7 @@ import Controller from '@site/static/usage/v10/alert/presenting/controller/index -## Buttons +## Buttons {/* #buttons */} In the array of `buttons`, each button includes properties for its `text`, and optionally a `handler`. If a handler returns `false` then the alert will not automatically be dismissed when the button is clicked. All buttons will show up in the order they have been added to the `buttons` array from left to right. Note: The right most button (the last one in the array) is the main button. @@ -62,23 +62,23 @@ import Buttons from '@site/static/usage/v10/alert/buttons/index.mdx'; -## Inputs +## Inputs {/* #inputs */} Alerts can also include several different inputs whose data can be passed back to the app. Inputs can be used as a simple way to prompt users for information. Radios, checkboxes and text inputs are all accepted, but they cannot be mixed. For example, an alert could have all radio button inputs, or all checkbox inputs, but the same alert cannot mix radio and checkbox inputs. Do note however, different types of "text" inputs can be mixed, such as `url`, `email`, `text`, `textarea` etc. If you require a complex form UI which doesn't fit within the guidelines of an alert then we recommend building the form within a modal instead. -### Text Inputs Example +### Text Inputs Example {/* #text-inputs-example */} import TextInputs from '@site/static/usage/v10/alert/inputs/text-inputs/index.mdx'; -### Radio Example +### Radio Example {/* #radio-example */} import Radios from '@site/static/usage/v10/alert/inputs/radios/index.mdx'; -## Customization +## Customization {/* #customization */} Alert uses scoped encapsulation, which means it will automatically scope its CSS by appending each of the styles with an additional class at runtime. Overriding scoped selectors in CSS requires a [higher specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity) selector. @@ -114,17 +114,17 @@ If you are building an Ionic Angular app, the styles need to be added to a globa ::: -## Accessibility +## Accessibility {/* #accessibility */} -### Screen Readers +### Screen Readers {/* #screen-readers */} Alerts set aria properties in order to be [accessible](../reference/glossary#a11y) to screen readers, but these properties can be overridden if they aren't descriptive enough or don't align with how the alert is being used in an app. -#### Role +#### Role {/* #role */} Ionic automatically sets the Alert's `role` to either [`alertdialog`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alertdialog_role) if there are any inputs or buttons included, or [`alert`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role) if there are none. -#### Alert Description +#### Alert Description {/* #alert-description */} If the `header` property is defined for the Alert, the `aria-labelledby` attribute will be automatically set to the header's ID. The `subHeader` element will be used as a fallback if `header` is not defined. Similarly, the `aria-describedby` attribute will be automatically set to the ID of the `message` element if that property is defined. @@ -188,7 +188,7 @@ const alert = await alertController.create({ All ARIA attributes can be manually overwritten by defining custom values in the `htmlAttributes` property of the Alert. -#### Alert Buttons Description +#### Alert Buttons Description {/* #alert-buttons-description */} Buttons containing text will be read by a screen reader. If a description other than the existing text is desired, a label can be set on the button by passing `aria-label` to the `htmlAttributes` property on the button. @@ -268,9 +268,9 @@ const alert = await alertController.create({ -## Interfaces +## Interfaces {/* #interfaces */} -### AlertButton +### AlertButton {/* #alertbutton */} ```typescript type AlertButtonOverlayHandler = boolean | void | { [key: string]: any }; @@ -285,7 +285,7 @@ interface AlertButton { } ``` -### AlertInput +### AlertInput {/* #alertinput */} ```typescript interface AlertInput { @@ -309,7 +309,7 @@ interface AlertInput { } ``` -### AlertOptions +### AlertOptions {/* #alertoptions */} ```typescript interface AlertOptions { @@ -333,26 +333,26 @@ interface AlertOptions { } ``` -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/app.mdx b/docs/api/app.mdx index 7614a5374b4..8fb575dbcd8 100644 --- a/docs/api/app.mdx +++ b/docs/api/app.mdx @@ -30,7 +30,7 @@ Using `ion-app` enables the following behaviors: - [Ripple effect](./ripple-effect) when activating buttons on Material Design mode - Other tap and focus utilities which make the experience of using an Ionic app feel more native -## Programmatic Focus +## Programmatic Focus {/* #programmatic-focus */} Ionic offers focus utilities for components with the `ion-focusable` class. These utilities automatically manage focus for components when certain keyboard keys, like Tab, are pressed. Components can also be programmatically focused in response to user actions using the `setFocus` method from `ion-app`. @@ -38,26 +38,26 @@ import SetFocus from '@site/static/usage/v10/app/set-focus/index.mdx'; -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/avatar.mdx b/docs/api/avatar.mdx index b1449c19baa..db51aa49fef 100644 --- a/docs/api/avatar.mdx +++ b/docs/api/avatar.mdx @@ -25,52 +25,52 @@ Avatars are circular components that usually wrap an image or icon. They can be Avatars can be used by themselves or inside of any element. If placed inside of an `ion-chip` or `ion-item`, the avatar will resize to fit the parent component. To position an avatar on the left or right side of an item, set the slot to `start` or `end`, respectively. -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/avatar/basic/index.mdx'; -## Chip Avatar +## Chip Avatar {/* #chip-avatar */} import Chip from '@site/static/usage/v10/avatar/chip/index.mdx'; -## Item Avatar +## Item Avatar {/* #item-avatar */} import Item from '@site/static/usage/v10/avatar/item/index.mdx'; -## Theming +## Theming {/* #theming */} -### CSS Custom Properties +### CSS Custom Properties {/* #css-custom-properties */} import CSSProps from '@site/static/usage/v10/avatar/theming/css-properties/index.mdx'; -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties-1 */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/back-button.mdx b/docs/api/back-button.mdx index 25d11285181..92f12d27288 100644 --- a/docs/api/back-button.mdx +++ b/docs/api/back-button.mdx @@ -23,13 +23,13 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; The back button navigates back in the app's history when clicked. It is only displayed when there is history in the navigation stack, unless [`defaultHref`](#default-back-history) is set. The back button displays different text and icon based on the mode, but this can be customized. -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/back-button/basic/index.mdx'; -## Custom Back Button +## Custom Back Button {/* #custom-back-button */} By default, the back button will display the text `"Back"` with a `"chevron-back"` icon on `ios`, and an `"arrow-back-sharp"` icon on `md`. This can be customized per back button component by setting the `icon` or `text` properties. Alternatively, it can be set globally using the `backButtonIcon` or `backButtonText` properties in the global config. Refer to the [Config docs](../developing/config) for more information. @@ -37,30 +37,30 @@ import Custom from '@site/static/usage/v10/back-button/custom/index.mdx'; -## Default Back History +## Default Back History {/* #default-back-history */} Occasionally an app may need to show the back button and navigate back when there is no history. This can be done by setting the `defaultHref` on the back button to a path. In order to use `defaultHref`, the app must contain a router with paths set. -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/backdrop.mdx b/docs/api/backdrop.mdx index 02c5e0cbd26..1c7a2dd6c5f 100644 --- a/docs/api/backdrop.mdx +++ b/docs/api/backdrop.mdx @@ -15,7 +15,7 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Backdrops are full screen components that overlay other components. They are useful behind components that transition in on top of other content and can be used to dismiss that component. -## Basic Usage +## Basic Usage {/* #basic-usage */} The backdrop prevents clicking or tapping on the content behind it. It is transparent by default, so the below demo includes CSS to make it visible. @@ -23,7 +23,7 @@ import Basic from '@site/static/usage/v10/backdrop/basic/index.mdx'; -## Styling +## Styling {/* #styling */} The backdrop can be customized by assigning CSS properties directly to the backdrop element. Common properties include `background-color`, `background` and `opacity`. @@ -33,26 +33,26 @@ import Styling from '@site/static/usage/v10/backdrop/styling/index.mdx'; -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/badge.mdx b/docs/api/badge.mdx index c5fccb26d80..dd6110a889e 100644 --- a/docs/api/badge.mdx +++ b/docs/api/badge.mdx @@ -23,13 +23,13 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Badges are inline block elements that usually appear near another element. Typically they contain a number or other characters. They can be used as a notification that there are additional items associated with an element and indicate how many items there are. Badges are hidden if no content is passed in. -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/badge/basic/index.mdx'; -## Badges in Tab Buttons +## Badges in Tab Buttons {/* #badges-in-tab-buttons */} Badges can be added inside a tab button, often used to indicate notifications or highlight additional items associated with the element. @@ -43,40 +43,40 @@ import InsideTabBar from '@site/static/usage/v10/badge/inside-tab-bar/index.mdx' -## Theming +## Theming {/* #theming */} -### Colors +### Colors {/* #colors */} import Colors from '@site/static/usage/v10/badge/theming/colors/index.mdx'; -### CSS Properties +### CSS Properties {/* #css-properties */} import CSSProps from '@site/static/usage/v10/badge/theming/css-properties/index.mdx'; -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/breadcrumb.mdx b/docs/api/breadcrumb.mdx index 49da6c7e669..c9bfbb868a9 100644 --- a/docs/api/breadcrumb.mdx +++ b/docs/api/breadcrumb.mdx @@ -17,9 +17,9 @@ A Breadcrumb is a single navigation item that is a child of the Breadcrumbs comp Refer to the [Breadcrumbs](./breadcrumbs) documentation for more information. -## Interfaces +## Interfaces {/* #interfaces */} -### BreadcrumbCollapsedClickEventDetail +### BreadcrumbCollapsedClickEventDetail {/* #breadcrumbcollapsedclickeventdetail */} ```typescript interface BreadcrumbCollapsedClickEventDetail { @@ -27,7 +27,7 @@ interface BreadcrumbCollapsedClickEventDetail { } ``` -### BreadcrumbCustomEvent +### BreadcrumbCustomEvent {/* #breadcrumbcustomevent */} While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing . @@ -38,26 +38,26 @@ interface BreadcrumbCustomEvent extends CustomEvent { } ``` -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/breadcrumbs.mdx b/docs/api/breadcrumbs.mdx index f1ddd018be5..b1b6e4cb72a 100644 --- a/docs/api/breadcrumbs.mdx +++ b/docs/api/breadcrumbs.mdx @@ -15,29 +15,29 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Breadcrumbs are navigation items that are used to indicate where a user is on an app or site. They should be used for large sites and apps with hierarchically arranged pages. Breadcrumbs can be collapsed based on the maximum number that can show, and the collapsed indicator can be clicked on to present a popover with more information or expand the collapsed breadcrumbs. -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/breadcrumbs/basic/index.mdx'; -## Using Icons +## Using Icons {/* #using-icons */} -### Icons on Items +### Icons on Items {/* #icons-on-items */} import IconsOnItems from '@site/static/usage/v10/breadcrumbs/icons/icons-on-items/index.mdx'; -### Custom Separators +### Custom Separators {/* #custom-separators */} import CustomSeparators from '@site/static/usage/v10/breadcrumbs/icons/custom-separators/index.mdx'; -## Collapsing Items +## Collapsing Items {/* #collapsing-items */} -### Max Items +### Max Items {/* #max-items */} If there are more items than the value of `maxItems`, the breadcrumbs will be collapsed. By default, only the first and last items will be shown. @@ -45,7 +45,7 @@ import MaxItems from '@site/static/usage/v10/breadcrumbs/collapsing-items/max-it -### Items Before or After Collapse +### Items Before or After Collapse {/* #items-before-or-after-collapse */} Once the items are collapsed, the number of items to show can be controlled by the `itemsBeforeCollapse` and `itemsAfterCollapse` properties. @@ -53,7 +53,7 @@ import ItemsBeforeAfter from '@site/static/usage/v10/breadcrumbs/collapsing-item -### Collapsed Indicator Click -- Expand Breadcrumbs +### Collapsed Indicator Click -- Expand Breadcrumbs {/* #collapsed-indicator-click----expand-breadcrumbs */} Clicking the collapsed indicator will fire the `ionCollapsedClick` event. This can be used to, for example, expand the breadcrumbs. @@ -61,7 +61,7 @@ import ExpandOnClick from '@site/static/usage/v10/breadcrumbs/collapsing-items/e -### Collapsed Indicator Click -- Present Popover +### Collapsed Indicator Click -- Present Popover {/* #collapsed-indicator-click----present-popover */} The `ionCollapsedClick` event can also be used to present an overlay (in this case, an `ion-popover`) showing the hidden breadcrumbs. @@ -69,40 +69,40 @@ import PopoverOnClick from '@site/static/usage/v10/breadcrumbs/collapsing-items/ -## Theming +## Theming {/* #theming */} -### Colors +### Colors {/* #colors */} import Colors from '@site/static/usage/v10/breadcrumbs/theming/colors/index.mdx'; -### CSS Custom Properties +### CSS Custom Properties {/* #css-custom-properties */} import CSSProps from '@site/static/usage/v10/breadcrumbs/theming/css-properties/index.mdx'; -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties-1 */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/button.mdx b/docs/api/button.mdx index 3a446968cf2..93c34fd2dd0 100644 --- a/docs/api/button.mdx +++ b/docs/api/button.mdx @@ -23,13 +23,13 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Buttons provide a clickable element, which can be used in forms, or anywhere that needs simple, standard button functionality. They may display text, icons, or both. Buttons can be styled with several attributes to look a specific way. -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/button/basic/index.mdx'; -## Expand +## Expand {/* #expand */} This property lets you specify how wide the button should be. By default, buttons have `display: inline-block`, but setting this property will change the button to a full-width element with `display: block`. @@ -37,7 +37,7 @@ import Expand from '@site/static/usage/v10/button/expand/index.mdx'; -## Shape +## Shape {/* #shape */} This property lets you specify the shape of the button. By default, buttons are rectangular with a small border radius, but setting this to `"round"` will change the button to a rounded element. @@ -45,7 +45,7 @@ import Shape from '@site/static/usage/v10/button/shape/index.mdx'; -## Fill +## Fill {/* #fill */} This property determines the background and border color of the button. By default, buttons have a solid background unless the button is inside of a toolbar, in which case it has a transparent background. @@ -53,7 +53,7 @@ import Fill from '@site/static/usage/v10/button/fill/index.mdx'; -## Size +## Size {/* #size */} This property specifies the size of the button. Setting this property will change the height and padding of a button. @@ -61,31 +61,31 @@ import Size from '@site/static/usage/v10/button/size/index.mdx'; -## Icons +## Icons {/* #icons */} import Icons from '@site/static/usage/v10/button/icons/index.mdx'; -## Theming +## Theming {/* #theming */} -### Colors +### Colors {/* #colors */} import Colors from '@site/static/usage/v10/button/theming/colors/index.mdx'; -### CSS Custom Properties +### CSS Custom Properties {/* #css-custom-properties */} import CSSProps from '@site/static/usage/v10/button/theming/css-properties/index.mdx'; -## Accessibility +## Accessibility {/* #accessibility */} Buttons are built to be accessible, but may need some adjustments depending on their content. The button component renders a native [button element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button) which allows it to take advantage of the functionality that a native button provides. -### Overflowing Text Content +### Overflowing Text Content {/* #overflowing-text-content */} There are many cases where a button's text content may overflow the container. It is recommended to wrap the text inside of the button when this happens so that all of the text can still be read. The button component will automatically adjust its height to accommodate the extra lines of text. @@ -101,26 +101,26 @@ import TextWrapping from '@site/static/usage/v10/button/text-wrapping/index.mdx' -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties-1 */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/buttons.mdx b/docs/api/buttons.mdx index 7371cf50bb0..2fa0e42d5be 100644 --- a/docs/api/buttons.mdx +++ b/docs/api/buttons.mdx @@ -23,13 +23,13 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; The Buttons component is a container element. It should be used inside of a [toolbar](./toolbar) and can contain several types of buttons, including standard [buttons](./button), [menu buttons](./menu-button), and [back buttons](./back-button). -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/buttons/basic/index.mdx'; -## Buttons Placement +## Buttons Placement {/* #buttons-placement */} Buttons can be positioned inside of the toolbar using a named slot. The below chart has a description of each slot. @@ -44,7 +44,7 @@ import Placement from '@site/static/usage/v10/buttons/placement/index.mdx'; -## Types of Buttons +## Types of Buttons {/* #types-of-buttons */} A button in a toolbar is styled to be clear by default, but this can be changed using the [`fill`](./button#fill) property on the button. The properties included on [back button](./back-button) and [menu button](./menu-button) in this example are for display purposes; refer to their respective documentation for proper usage. @@ -52,7 +52,7 @@ import Types from '@site/static/usage/v10/buttons/types/index.mdx'; -## Collapsible Buttons +## Collapsible Buttons {/* #collapsible-buttons */} The `collapse` property can be set on the buttons to collapse them when the header collapses. This is typically used with [collapsible large titles](./title#collapsible-large-titles). @@ -67,26 +67,26 @@ import CollapsibleLargeTitleButtons from '@site/static/usage/v10/title/collapsib -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/card-content.mdx b/docs/api/card-content.mdx index 3bbaa700990..5f09c7a2c72 100644 --- a/docs/api/card-content.mdx +++ b/docs/api/card-content.mdx @@ -15,26 +15,26 @@ Card content is a child component of card that adds padding around its contents. Refer to the [Card](./card) documentation for more information. -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/card-header.mdx b/docs/api/card-header.mdx index c00364e877b..0721c076932 100644 --- a/docs/api/card-header.mdx +++ b/docs/api/card-header.mdx @@ -17,26 +17,26 @@ Card header is a child component of card that should be placed before the card c Refer to the [Card](./card) documentation for more information. -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/card-subtitle.mdx b/docs/api/card-subtitle.mdx index 2418b28e4a2..bf5f8ae884e 100644 --- a/docs/api/card-subtitle.mdx +++ b/docs/api/card-subtitle.mdx @@ -17,26 +17,26 @@ Card subtitle is a child component of card that should be placed inside of a [ca Refer to the [Card](./card) documentation for more information. -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/card-title.mdx b/docs/api/card-title.mdx index fa1be55ba35..5c739b7fe2b 100644 --- a/docs/api/card-title.mdx +++ b/docs/api/card-title.mdx @@ -25,26 +25,26 @@ Card title is a child component of card that should be placed inside of a [card Refer to the [Card](./card) documentation for more information. -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/card.mdx b/docs/api/card.mdx index 35cee7e72c9..dea028d0216 100644 --- a/docs/api/card.mdx +++ b/docs/api/card.mdx @@ -27,64 +27,64 @@ and content. Cards are broken up into several components to accommodate this str [card header](./card-header), [card title](./card-title), [card subtitle](./card-subtitle), and [card content](./card-content). -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/card/basic/index.mdx'; -## Media Cards +## Media Cards {/* #media-cards */} import Media from '@site/static/usage/v10/card/media/index.mdx'; -## Card Buttons +## Card Buttons {/* #card-buttons */} import Buttons from '@site/static/usage/v10/card/buttons/index.mdx'; -## List Card +## List Card {/* #list-card */} import List from '@site/static/usage/v10/card/list/index.mdx'; -## Theming +## Theming {/* #theming */} -### Colors +### Colors {/* #colors */} import Colors from '@site/static/usage/v10/card/theming/colors/index.mdx'; -### CSS Custom Properties +### CSS Custom Properties {/* #css-custom-properties */} import CSSProps from '@site/static/usage/v10/card/theming/css-properties/index.mdx'; -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties-1 */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/checkbox.mdx b/docs/api/checkbox.mdx index b513f1bb7ce..3add1427354 100644 --- a/docs/api/checkbox.mdx +++ b/docs/api/checkbox.mdx @@ -23,13 +23,13 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Checkboxes allow the selection of multiple options from a set of options. They appear as checked (ticked) when activated. Clicking on a checkbox will toggle the `checked` property. They can also be checked programmatically by setting the `checked` property. -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/checkbox/basic/index.mdx'; -## Label Placement +## Label Placement {/* #label-placement */} Developers can use the `labelPlacement` property to control how the label is placed relative to the control. This property mirrors the flexbox `flex-direction` property. @@ -37,7 +37,7 @@ import LabelPlacement from '@site/static/usage/v10/checkbox/label-placement/inde -## Alignment +## Alignment {/* #alignment */} 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. @@ -51,7 +51,7 @@ import Alignment from '@site/static/usage/v10/checkbox/alignment/index.mdx'; -## Justification +## Justification {/* #justification */} Developers can use the `justify` property to control how the label and control are packed on a line. This property mirrors the flexbox `justify-content` property. @@ -65,13 +65,13 @@ import Justify from '@site/static/usage/v10/checkbox/justify/index.mdx'; ::: -## Indeterminate Checkboxes +## Indeterminate Checkboxes {/* #indeterminate-checkboxes */} import Indeterminate from '@site/static/usage/v10/checkbox/indeterminate/index.mdx'; -## Links inside of Labels +## Links inside of Labels {/* #links-inside-of-labels */} Checkbox labels can sometimes be accompanied with links. These links can provide more information related to the checkbox. However, clicking the link should not check the checkbox. To achieve this, we can use [stopPropagation](https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation) to prevent the click event from bubbling. When using this approach, the rest of the label still remains clickable. @@ -79,7 +79,7 @@ import LabelLink from '@site/static/usage/v10/checkbox/label-link/index.mdx'; -## Helper & Error Text +## Helper & Error Text {/* #helper--error-text */} Helper and error text can be used inside of a checkbox with the `helperText` and `errorText` property. The error text will not be displayed unless the `ion-invalid` and `ion-touched` classes are added to the `ion-checkbox`. This ensures errors are not shown before the user has a chance to enter data. @@ -89,17 +89,17 @@ import HelperError from '@site/static/usage/v10/checkbox/helper-error/index.mdx' -## Theming +## Theming {/* #theming */} -### CSS Custom Properties +### CSS Custom Properties {/* #css-custom-properties */} import CSSProps from '@site/static/usage/v10/checkbox/theming/css-properties/index.mdx'; -## Interfaces +## Interfaces {/* #interfaces */} -### CheckboxChangeEventDetail +### CheckboxChangeEventDetail {/* #checkboxchangeeventdetail */} ```typescript interface CheckboxChangeEventDetail { @@ -108,7 +108,7 @@ interface CheckboxChangeEventDetail { } ``` -### CheckboxCustomEvent +### CheckboxCustomEvent {/* #checkboxcustomevent */} While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component. @@ -119,26 +119,26 @@ interface CheckboxCustomEvent extends CustomEvent { } ``` -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties-1 */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/chip.mdx b/docs/api/chip.mdx index 47ffef5f9e2..679e61aa5e4 100644 --- a/docs/api/chip.mdx +++ b/docs/api/chip.mdx @@ -23,52 +23,52 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Chips represent complex entities in small blocks, such as a contact. A chip can contain several different elements such as avatars, text, and icons. -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/chip/basic/index.mdx'; -## Slotting Components and Icons +## Slotting Components and Icons {/* #slotting-components-and-icons */} import SlotExample from '@site/static/usage/v10/chip/slots/index.mdx'; -## Theming +## Theming {/* #theming */} -### Colors +### Colors {/* #colors */} import Colors from '@site/static/usage/v10/chip/theming/colors/index.mdx'; -### CSS Custom Properties +### CSS Custom Properties {/* #css-custom-properties */} import CSSProps from '@site/static/usage/v10/chip/theming/css-properties/index.mdx'; -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties-1 */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/col.mdx b/docs/api/col.mdx index 3f15a7ccd05..451020527a6 100644 --- a/docs/api/col.mdx +++ b/docs/api/col.mdx @@ -25,30 +25,30 @@ Columns are cellular components of the [grid](./grid) system and go inside of a Refer to the [grid](./grid) documentation for more information. -## Column Alignment +## Column Alignment {/* #column-alignment */} By default, columns will stretch to fill the entire height of the row. Columns are [flex items](https://developer.mozilla.org/en-US/docs/Glossary/Flex_Item), so there are several [CSS classes](/layout/css-utilities.mdx#flex-item-properties) that can be applied to a column to customize this behavior. -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/content.mdx b/docs/api/content.mdx index 4cb4eb5ac34..d0253d23ba8 100644 --- a/docs/api/content.mdx +++ b/docs/api/content.mdx @@ -27,13 +27,13 @@ view. Content, along with many other Ionic components, can be customized to modify its padding, margin, and more using the global styles provided in the [CSS Utilities](/layout/css-utilities.mdx) or by individually styling it using CSS and the available [CSS Custom Properties](#css-custom-properties). -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/content/basic/index.mdx'; -## Header & Footer +## Header & Footer {/* #header--footer */} Content can be the only top-level component in a page, or it can be used alongside a [header](./header), [footer](./footer), or both. When used with a header or footer, it will adjust its size to fill the remaining height. @@ -41,7 +41,7 @@ import HeaderFooter from '@site/static/usage/v10/content/header-footer/index.mdx -## Fullscreen Content +## Fullscreen Content {/* #fullscreen-content */} By default, content fills the space between a [header](./header) and [footer](./footer) but does not go behind them. In certain cases, it may be desired to have the content scroll behind the header and footer, such as when the `translucent` property is set on either of them, or `opacity` is set on the toolbar. This can be achieved by setting the `fullscreen` property on the content to `true`. @@ -49,7 +49,7 @@ import Fullscreen from '@site/static/usage/v10/content/fullscreen/index.mdx'; -## Fixed Content +## Fixed Content {/* #fixed-content */} To place elements outside of the scrollable area, assign them to the `fixed` slot. Doing so will [absolutely position](https://developer.mozilla.org/en-US/docs/Web/CSS/position#absolute_positioning) the element to the top left of the content. In order to change the position of the element, it can be styled using the [top, right, bottom, and left](https://developer.mozilla.org/en-US/docs/Web/CSS/position) CSS properties. @@ -59,7 +59,7 @@ import Fixed from '@site/static/usage/v10/content/fixed/index.mdx'; -## Scroll Methods +## Scroll Methods {/* #scroll-methods */} Content provides [methods](#methods) that can be called to scroll the content to the bottom, top, or to a specific point. They can be passed a `duration` in order to smoothly transition instead of instantly changing the position. @@ -67,7 +67,7 @@ import ScrollMethods from '@site/static/usage/v10/content/scroll-methods/index.m -## Scroll Events +## Scroll Events {/* #scroll-events */} Scroll events are disabled by default for content due to performance. However, they can be enabled by setting `scrollEvents` to `true`. This is necessary before listening to any of the scroll [events](#events). @@ -75,27 +75,27 @@ import ScrollEvents from '@site/static/usage/v10/content/scroll-events/index.mdx -## Theming +## Theming {/* #theming */} -### Colors +### Colors {/* #colors */} import Colors from '@site/static/usage/v10/content/theming/colors/index.mdx'; -### CSS Shadow Parts +### CSS Shadow Parts {/* #css-shadow-parts */} import CSSParts from '@site/static/usage/v10/content/theming/css-shadow-parts/index.mdx'; -### CSS Custom Properties +### CSS Custom Properties {/* #css-custom-properties */} import CSSProps from '@site/static/usage/v10/content/theming/css-properties/index.mdx'; -### Safe Area Padding +### Safe Area Padding {/* #safe-area-padding */} The content component will not automatically apply padding to any of its sides to account for the [safe area](/theming/advanced.mdx#safe-area-padding). This is because the content component is often used in conjunction with other components that apply their own padding, such as [headers](./header) and [footers](./footer). However, if the content component is being used on its own, it may be desired to apply padding to the safe area. This can be done through CSS by using the `--ion-safe-area-(dir)` variables described in [Application Variables](../theming/advanced.mdx#application-variables). @@ -119,9 +119,9 @@ import SafeArea from '@site/static/usage/v10/content/theming/safe-area/index.mdx -## Interfaces +## Interfaces {/* #interfaces */} -### ScrollBaseDetail +### ScrollBaseDetail {/* #scrollbasedetail */} ```typescript interface ScrollBaseDetail { @@ -129,7 +129,7 @@ interface ScrollBaseDetail { } ``` -### ScrollDetail +### ScrollDetail {/* #scrolldetail */} ```typescript interface ScrollDetail extends GestureDetail, ScrollBaseDetail { @@ -138,7 +138,7 @@ interface ScrollDetail extends GestureDetail, ScrollBaseDetail { } ``` -### ScrollBaseCustomEvent +### ScrollBaseCustomEvent {/* #scrollbasecustomevent */} While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing on the `ionScrollStart` and `ionScrollEnd` events. @@ -149,7 +149,7 @@ interface ScrollBaseCustomEvent extends CustomEvent { } ``` -### ScrollCustomEvent +### ScrollCustomEvent {/* #scrollcustomevent */} While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing on the `ionScroll` event. @@ -159,26 +159,26 @@ interface ScrollCustomEvent extends ScrollBaseCustomEvent { } ``` -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts-1 */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties-1 */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/datetime-button.mdx b/docs/api/datetime-button.mdx index abf61fe207d..a8c5eca4f73 100644 --- a/docs/api/datetime-button.mdx +++ b/docs/api/datetime-button.mdx @@ -23,23 +23,23 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Datetime Button links with a [Datetime](./datetime) component to display the formatted date and time. It also provides buttons to present the datetime in a modal, popover, and more. -## Overview +## Overview {/* #overview */} Datetime Button should be used when space is constrained. This component displays buttons which show the current date and time values. When the buttons are tapped, the date or time pickers open in the overlay. When using Datetime Button with a JavaScript framework such as Angular, React, or Vue be sure to use the [keepContentsMounted property on ion-modal](./modal#prop-keep-contents-mounted) or the [keepContentsMounted property on ion-popover](./popover#prop-keep-contents-mounted). This allows the linked datetime instance to be mounted even if the overlay has not been presented yet. -## Basic Usage +## Basic Usage {/* #basic-usage */} import Basic from '@site/static/usage/v10/datetime-button/basic/index.mdx'; -## Localization +## Localization {/* #localization */} The localized text on `ion-datetime-button` is determined by the `locale` property on the associated `ion-datetime` instance. Refer to [Datetime Localization](./datetime#localization) for more details. -## Format Options +## Format Options {/* #format-options */} You can customize the format of the date and time in a Datetime Button by providing `formatOptions` on the associated Datetime instance. Refer to [Datetime Format Options](./datetime#format-options) for more details. @@ -47,30 +47,30 @@ import FormatOptions from '@site/static/usage/v10/datetime-button/format-options -## Usage with Modals and Popovers +## Usage with Modals and Popovers {/* #usage-with-modals-and-popovers */} `ion-datetime-button` must be associated with a mounted `ion-datetime` instance. As a result, [Inline Modals](./modal#inline-modals-recommended) and [Inline Popovers](./popover#inline-popovers) with the `keepContentsMounted` property set to `true` must be used. -## Properties +## Properties {/* #properties */} -## Events +## Events {/* #events */} -## Methods +## Methods {/* #methods */} -## CSS Shadow Parts +## CSS Shadow Parts {/* #css-shadow-parts */} -## CSS Custom Properties +## CSS Custom Properties {/* #css-custom-properties */} -## Slots +## Slots {/* #slots */} diff --git a/docs/api/datetime.mdx b/docs/api/datetime.mdx index f3373cd54e1..f7bcd341417 100644 --- a/docs/api/datetime.mdx +++ b/docs/api/datetime.mdx @@ -61,7 +61,7 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Datetimes present a calendar interface and time wheel, making it easy for users to select dates and times. Datetimes are similar to the native `input` elements of `datetime-local`, however, Ionic Framework's Datetime component makes it easy to display the date and time in the preferred format, and manage the datetime values. -## Overview +## Overview {/* #overview */} Historically, handling datetime values within JavaScript, or even within HTML inputs, has always been a challenge. Specifically, JavaScript's `Date` object is @@ -72,7 +72,7 @@ parse various datetime strings differently, especially per locale. Fortunately, Ionic Framework's datetime input has been designed so developers can avoid the common pitfalls, allowing developers to easily manipulate datetime values and give the user a simple datetime picker for a great user experience. -### ISO 8601 Datetime Format: `YYYY-MM-DDTHH:mmZ` +### ISO 8601 Datetime Format: `YYYY-MM-DDTHH:mmZ` {/* #iso-8601-datetime-format-yyyy-mm-ddthhmmz */} Ionic Framework uses the [ISO 8601 datetime format](https://www.w3.org/TR/NOTE-datetime) for its value. The value is simply a string, rather than using JavaScript's @@ -103,21 +103,21 @@ While seconds, milliseconds, and time zone can be specified using the ISO 8601 d ::: -## Basic Usage +## Basic Usage {/* #basic-usage */} -## Usage with Datetime Button +## Usage with Datetime Button {/* #usage-with-datetime-button */} If you need to present a datetime in an overlay such as a modal or a popover, we recommend using [ion-datetime-button](./datetime-button). `ion-datetime-button` should be used when space is constrained. This component displays buttons which show the current date and time values. When the buttons are tapped, the date or time pickers open in the overlay. -## Setting Values Asynchronously +## Setting Values Asynchronously {/* #setting-values-asynchronously */} If its `value` is updated programmatically after a datetime has already been created, the datetime will automatically jump to the new date. However, it is recommended to avoid updating the `value` in this way when users are able to interact with the datetime, as this could be disorienting for those currently trying to select a date. For example, if a datetime's `value` is loaded by an asynchronous process, it is recommended to hide the datetime with CSS until the value has finished updating. -## Date Constraints +## Date Constraints {/* #date-constraints */} -### Max and Min Dates +### Max and Min Dates {/* #max-and-min-dates */} To customize the minimum and maximum datetime values, the `min` and `max` component properties can be provided which may make more sense for the app's use-case. Following the same IS0 8601 format listed in the table above, each component can restrict which dates can be selected by the user. @@ -125,7 +125,7 @@ The following example restricts date selection to March 2022 through May 2022 on -### Selecting Specific Values +### Selecting Specific Values {/* #selecting-specific-values */} While the `min` and `max` properties allow you to restrict date selection to a certain range, the `monthValues`, `dayValues`, `yearValues`, `hourValues`, and `minuteValues` properties allow you choose specific days and times that users can select. @@ -133,7 +133,7 @@ The following example allows minutes to be selected in increments of 15. It also -### Advanced Date Constraints +### Advanced Date Constraints {/* #advanced-date-constraints */} With the `isDateEnabled` property, developers can customize the `ion-datetime` to disable a specific day, range of dates, weekends or any custom rule using an ISO 8601 date string. The `isDateEnabled` property accepts a function returning a boolean, indicating if a date is enabled. The function is called for each rendered calendar day, for the previous, current and next month. Custom implementations should be optimized for performance to avoid jank. @@ -142,11 +142,11 @@ The following example shows how to disable all weekend dates. For more advanced -## Localization +## Localization {/* #localization */} Ionic Framework makes use of the [Intl.DatetimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DatetimeFormat) Web API which allows us to automatically localize the month and day names according to the language and region set on the user's device. -### Custom Locale +### Custom Locale {/* #custom-locale */} For instances where you need a specific locale, you can use the `locale` property to set it. The locale controls both the language and the date and time formats that are displayed. @@ -160,7 +160,7 @@ The time label is not automatically localized. Refer to [Time Label](#time-label ::: -### Hour Cycle +### Hour Cycle {/* #hour-cycle */} `ion-datetime` will use the hour cycle that is specified by the `locale` property by default. For example, if `locale` is set to `en-US`, then `ion-datetime` will use a 12 hour cycle. @@ -185,19 +185,19 @@ In the following example, we can use the `hourCycle` property to force `ion-date -### First Day of the Week +### First Day of the Week {/* #first-day-of-the-week */} For `ion-datetime`, the default first day of the week is Sunday. As of 2022, there is no browser API that lets Ionic automatically determine the first day of the week based on a device's locale, though there is on-going work regarding this (refer to [TC39 GitHub](https://github.com/tc39/ecma402/issues/6)). -### Time Label +### Time Label {/* #time-label */} The time label is not automatically localized. Fortunately, Ionic makes it easy to provide custom localizations with the `time-label` slot. -### Locale Extension Tags +### Locale Extension Tags {/* #locale-extension-tags */} `ion-datetime` also supports [locale extension tags](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) as part of the `Intl.Locale` API. These tags let you encode information about the locale in the locale string itself. Developers may prefer to use the extension tag approach if they are using the [Intl.Locale API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) in their apps. @@ -211,13 +211,13 @@ Be sure to check the [Browser Compatibility Chart](https://developer.mozilla.org ::: -## Presentation +## Presentation {/* #presentation */} By default, `ion-datetime` allows users to select both date and time. In addition, users have access to selecting the specific month, year, hour, and minute. Some use cases may call for only date selection or only time selection. The `presentation` property allows you to specify which pickers to show and the order to show them in. For example, setting `date-time` will have the calendar picker appear before the time picker. Setting `time-date` will have the calendar picker appear after the time picker. -### Month and Year Selection +### Month and Year Selection {/* #month-and-year-selection */} Month and year selection is available by passing `month-year`, `month`, or `year` to the `presentation` property. @@ -225,7 +225,7 @@ This example shows a datetime with the `month-year` configuration. -### Time Selection +### Time Selection {/* #time-selection */} Time selection is available by passing `date-time`, `time-date`, or `time` to the `presentation` property. @@ -233,7 +233,7 @@ This example shows a datetime with the `time` configuration. -## Overview +## Overview {/* #overview */} Ionic focuses on the frontend UX and UI interaction of an app — UI controls, interactions, gestures, animations. It's easy to learn, and integrates with other libraries or frameworks, such as [Angular](angular/overview.mdx), [React](react/overview.mdx), or [Vue](vue/overview.mdx). Alternatively, it can be used standalone without any frontend framework using a simple [script include](intro/cdn.mdx). If you’d like to learn more about Ionic before diving in, we [created a video](https://youtu.be/p3AN3igqiRc) to walk you through the basics. -### One codebase, running everywhere +### One codebase, running everywhere {/* #one-codebase-running-everywhere */} Ionic is the only mobile app stack that enables web developers to build apps for all major app stores and the mobile web from a single codebase. And with [Adaptive Styling](theming/platform-styles.mdx), Ionic apps look and feel at home on every device. -### A focus on performance +### A focus on performance {/* #a-focus-on-performance */} Ionic is built to perform and behave great on the latest mobile devices with best practices like efficient hardware accelerated transitions, and touch-optimized gestures. -### Clean, simple, and functional design +### Clean, simple, and functional design {/* #clean-simple-and-functional-design */} Ionic is designed to work and display beautifully on all current mobile devices and platforms. With ready-made components, typography, and a gorgeous (yet extensible) base theme that adapts to each platform, you'll be building in style. -### Native and Web optimized +### Native and Web optimized {/* #native-and-web-optimized */} Ionic emulates native app UI guidelines and uses native SDKs, bringing the UI standards and device features of native apps together with the full power and flexibility of the open web. Ionic uses Capacitor (or Cordova) to deploy natively, or runs in the browser as a Progressive Web App. -## Goals +## Goals {/* #goals */} -### Cross-platform +### Cross-platform {/* #cross-platform */} Build and deploy apps that work across multiple platforms, such as native iOS, Android, and the web as a Progressive Web App - all with one code base. Write once, run anywhere. -### Web Standards-based +### Web Standards-based {/* #web-standards-based */} Ionic is built on top of reliable, [standardized web technologies](reference/glossary.mdx#web-standards): HTML, CSS, and JavaScript, using modern Web APIs such as Custom Elements and Shadow DOM. Because of this, Ionic components have a stable API, and aren't at the whim of a single platform vendor. -### Beautiful Design +### Beautiful Design {/* #beautiful-design */} Clean, simple, and functional. Ionic is designed to work and display beautifully out-of-the-box across all platforms. Start with pre-designed components, typography, interactive paradigms, and a gorgeous (yet extensible) base theme. -### Simplicity +### Simplicity {/* #simplicity */} Ionic is built with simplicity in mind, so that creating apps is enjoyable, easy to learn, and accessible to just about anyone with web development skills. -## Framework Compatibility +## Framework Compatibility {/* #framework-compatibility */} While past releases of Ionic were tightly coupled to Angular, version 4.x of the framework was re-engineered to work as a standalone [Web Component](https://developer.mozilla.org/en-US/docs/Web/Web_Components) library, with integrations for the latest JavaScript frameworks, like Angular. Ionic can be used in most frontend frameworks with success, including React and Vue, though some frameworks need a shim for full Web Component support. -### JavaScript +### JavaScript {/* #javascript */} One of the main goals with moving Ionic to [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) was to remove any hard requirement on a single framework to host the components. This made it possible for the core components to work standalone in a web page with just a script tag. While working with frameworks can be great for larger teams and larger apps, it is now possible to use Ionic as a standalone library in a single page even in a context like WordPress. -### Angular +### Angular {/* #angular */} Angular has always been at the center of what makes Ionic great. While the core components have been written to work as a standalone Web Component library, the `@ionic/angular` package makes integration with the Angular ecosystem a breeze. `@ionic/angular` includes all the functionality that Angular developers would expect coming from Ionic 2/3, and integrates with core Angular libraries, like the Angular router. -### React +### React {/* #react */} Ionic now has official support for the popular React library. Ionic React lets React developers use their existing web skills to build apps that target iOS, Android, and the web. With `@ionic/react`, you can use all the core Ionic components, but in a way that feels like using native React components. -### Vue +### Vue {/* #vue */} Ionic now has official support for the popular Vue 3 library. Ionic Vue lets Vue developers use their existing web skills to build apps that target iOS, Android, and the web. With `@ionic/vue`, you can use all the core Ionic components, but in a way that feels like using native Vue components. -### Future Support +### Future Support {/* #future-support */} Support for other frameworks will be considered in future releases. -## Ionic CLI +## Ionic CLI {/* #ionic-cli */} The official [Ionic CLI](cli.mdx), or Command Line Interface, is a tool that quickly scaffolds Ionic apps and provides a number of helpful commands to Ionic developers. In addition to installing and updating Ionic, the CLI comes with a built-in development server, build and debugging tools, and much more. If you are an [Appflow](#appflow) member, the CLI can be used to perform cloud builds and deployments, and administer your account. -## Appflow +## Appflow {/* #appflow */} To help build, deploy, and manage Ionic apps throughout their lifecycle, we offer a commercial service for production apps called [Appflow](https://ionic.io/appflow), which is **separate from the open source Framework.** @@ -131,11 +131,11 @@ Appflow helps developers and teams compile native app builds and deploy live cod Appflow requires an [Ionic Account](https://dashboard.ionicframework.com/signup) and comes with a free “Hobby” plan for those interested in playing around with some of its features. -## Ecosystem +## Ecosystem {/* #ecosystem */} Ionic is actively developed and maintained full-time by a core team, and its ecosystem is guided by an international community of developers and contributors fueling its growth and adoption. Developers and companies small and large use Ionic to build and ship amazing apps that run everywhere. -### Join the Community +### Join the Community {/* #join-the-community */} There are millions of Ionic developers in over 200 countries worldwide. Here are some ways to join: @@ -144,7 +144,7 @@ There are millions of Ionic developers in over 200 countries worldwide. Here are - [GitHub:](https://github.com/ionic-team/ionic) For reporting bugs or requesting new features, create an issue here. PRs welcome! - [Content authoring:](https://ionicframework.com/contributors) Write a technical blog or share your story with the Ionic community. -## License +## License {/* #license */} The Ionic UI Toolkit is a free and open source project, released under the permissible [MIT license](https://opensource.org/licenses/MIT). This means it can be used in personal or commercial projects for free. MIT is the same license used by such popular projects as jQuery and Ruby on Rails. diff --git a/docs/intro/cdn.mdx b/docs/intro/cdn.mdx index 55aad3c90c7..380f5bbbea7 100644 --- a/docs/intro/cdn.mdx +++ b/docs/intro/cdn.mdx @@ -16,7 +16,7 @@ import DocsCards from '@components/global/DocsCards'; Ionic Framework offers npm packages for Angular, React, Vue, and JavaScript, plus CDN links for quick prototyping. Choose your framework below to get started, or use the CDN to test Ionic Framework components in the browser. -## Ionic Angular +## Ionic Angular {/* #ionic-angular */} Start a new Ionic Angular app or add Ionic to your existing Angular project. @@ -40,7 +40,7 @@ Start a new Ionic Angular app or add Ionic to your existing Angular project. -## Ionic React +## Ionic React {/* #ionic-react */} Start a new Ionic React app or add Ionic to your existing React project. @@ -64,7 +64,7 @@ Start a new Ionic React app or add Ionic to your existing React project. -## Ionic Vue +## Ionic Vue {/* #ionic-vue */} Start a new Ionic Vue app or add Ionic to your existing Vue project. @@ -88,7 +88,7 @@ Start a new Ionic Vue app or add Ionic to your existing Vue project. -## Ionic JavaScript +## Ionic JavaScript {/* #ionic-javascript */} Start a new Ionic JavaScript app. @@ -104,7 +104,7 @@ Start a new Ionic JavaScript app. -## Ionic Framework CDN +## Ionic Framework CDN {/* #ionic-framework-cdn */} Ionic Framework can be included from a CDN for quick testing in a [StackBlitz](https://stackblitz.com/), [Plunker](https://plnkr.co/), [Codepen](https://codepen.io), or any other online code editor! @@ -118,7 +118,7 @@ It's recommended to use [jsdelivr](https://www.jsdelivr.com/) to access the Fram With this it's possible to use all of the Ionic Framework core components without having to install a framework. The CSS bundle will include all of the Ionic [Global Stylesheets](/layout/global-stylesheets.mdx). -## Ionicons CDN +## Ionicons CDN {/* #ionicons-cdn */} Ionicons is packaged by default with the Ionic Framework, so no installation is necessary if you're using Ionic. To use Ionicons without Ionic Framework, place the following ` ``` -## Navigate to the New Page +## Navigate to the New Page {/* #navigate-to-the-new-page */} To navigate to the new page, update the button in `HomePage.js` to be inside of an `ion-router-link`: @@ -336,7 +336,7 @@ Navigating can also be performed programmatically using `document.querySelector( ::: -## Add Icons to the New Page +## Add Icons to the New Page {/* #add-icons-to-the-new-page */} Ionic JavaScript comes with [Ionicons](https://ionic.io/ionicons/) support. To use icons, you need to import them, register them with `addIcons`, and then use them with the `ion-icon` component. @@ -383,7 +383,7 @@ customElements.define('new-page', NewPage); For more information, refer to the [Icon documentation](/api/icon.mdx) and the [Ionicons documentation](https://ionic.io/ionicons/). -## Call Component Methods +## Call Component Methods {/* #call-component-methods */} Let's add a button that can scroll the content area to the bottom. Update `NewPage.js` to include scrollable content and a scroll button: @@ -452,7 +452,7 @@ To call methods on Ionic components: You can find available methods for each component in the [Methods](/api/content.mdx#methods) section of their API documentation. -## Run on a Device +## Run on a Device {/* #run-on-a-device */} Ionic's components work everywhere: on iOS, Android, and PWAs. To deploy to mobile, use [Capacitor](https://capacitorjs.com): @@ -475,11 +475,11 @@ npx cap open android Refer to [Capacitor's Getting Started guide](https://capacitorjs.com/docs/getting-started/with-ionic) for more. -## Framework Integrations +## Framework Integrations {/* #framework-integrations */} Ionic Core also works with other frameworks and libraries that support custom elements, such as [Alpine.js](https://alpinejs.dev/), [Lit](https://lit.dev/), and [Svelte](https://svelte.dev/). However, when using Ionic Core with these libraries, you won't have the built-in form and routing capabilities that are tightly coupled with Ionic's official Angular, React, and Vue framework integrations, and will need to use their respective routing and form solutions instead. -## Explore More +## Explore More {/* #explore-more */} This guide covered the basics of creating an Ionic JavaScript app with Vite, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out: diff --git a/docs/layout/css-utilities.mdx b/docs/layout/css-utilities.mdx index a2621f8cfa9..a04a912d4ed 100644 --- a/docs/layout/css-utilities.mdx +++ b/docs/layout/css-utilities.mdx @@ -18,9 +18,9 @@ If your app was not started using an available Ionic Framework starter, the styl ::: -## Text Modification +## Text Modification {/* #text-modification */} -### Text Align +### Text Align {/* #text-align */} ```html @@ -78,7 +78,7 @@ If your app was not started using an available Ionic Framework starter, the styl | `.ion-text-wrap` | `white-space: normal` | Sequences of whitespace are collapsed. Newline characters in the source are handled as other whitespace. Breaks lines as necessary to fill line boxes. | | `.ion-text-nowrap` | `white-space: nowrap` | Collapses whitespace as for `normal`, but suppresses line breaks (text wrapping) within text. | -### Text Transform +### Text Transform {/* #text-transform */} ```html @@ -111,7 +111,7 @@ If your app was not started using an available Ionic Framework starter, the styl | `.ion-text-lowercase` | `text-transform: lowercase` | Forces all characters to be converted to lowercase. | | `.ion-text-capitalize` | `text-transform: capitalize` | Forces the first letter of each word to be converted to uppercase. | -### Responsive Text Classes +### Responsive Text Classes {/* #responsive-text-classes */} All of the text classes listed above have additional classes to modify the text based on the screen size. Instead of `text-` in each class, use `text-{breakpoint}-` to only use the class on specific screen sizes, where `{breakpoint}` is one of the breakpoint names listed in [Ionic Breakpoints](#ionic-breakpoints). @@ -125,9 +125,9 @@ The table below shows the default behavior, where `{modifier}` is any of the fol | `.ion-text-lg-{modifier}` | Applies the modifier to the element when `min-width: 992px`. | | `.ion-text-xl-{modifier}` | Applies the modifier to the element when `min-width: 1200px`. | -## Element Placement +## Element Placement {/* #element-placement */} -### Float +### Float {/* #float */} The [float](https://developer.mozilla.org/en-US/docs/Web/CSS/float) CSS property specifies that an element should be placed along the left or right side of its container, where text and inline elements will wrap around it. This way, the element is taken from the normal flow of the web page, though still remaining a part of the flow, contrary to absolute positioning. @@ -174,7 +174,7 @@ The [float](https://developer.mozilla.org/en-US/docs/Web/CSS/float) CSS property | `.ion-float-start` | `float: left` / `float: right` | The same as `float-left` if direction is left-to-right and `float-right` if direction is right-to-left. | | `.ion-float-end` | `float: left` / `float: right` | The same as `float-right` if direction is left-to-right and `float-left` if direction is right-to-left. | -### Responsive Float Classes +### Responsive Float Classes {/* #responsive-float-classes */} All of the float classes listed above have additional classes to modify the float based on the screen size. Instead of `float-` in each class, use `float-{breakpoint}-` to only use the class on specific screen sizes, where `{breakpoint}` is one of the breakpoint names listed in [Ionic Breakpoints](#ionic-breakpoints). @@ -188,9 +188,9 @@ The table below shows the default behavior, where `{modifier}` is any of the fol | `.ion-float-lg-{modifier}` | Applies the modifier to the element when `min-width: 992px`. | | `.ion-float-xl-{modifier}` | Applies the modifier to the element when `min-width: 1200px`. | -## Element Display +## Element Display {/* #element-display */} -### Display +### Display {/* #display */} The [display](https://developer.mozilla.org/en-US/docs/Web/CSS/display) CSS property sets whether an element is treated as a block or inline box and the layout used for its children, such as flow layout, grid or flex. It can also be used to completely hide an element from the layout. @@ -210,7 +210,7 @@ Ionic provides the following utility classes for `display`: | `.ion-display-table-cell` | `display: table-cell` | The element behaves like an HTML `` element. | | `.ion-display-table-row` | `display: table-row` | The element behaves like an HTML `` element. | -### Responsive Display Classes +### Responsive Display Classes {/* #responsive-display-classes */} All of the display classes listed above have additional classes to modify the display based on the screen size. Instead of `display-` in each class, use `display-{breakpoint}-` to only use the class on specific screen sizes, where `{breakpoint}` is one of the breakpoint names listed in [Ionic Breakpoints](#ionic-breakpoints). @@ -224,7 +224,7 @@ The table below shows the default behavior, where `{modifier}` is any of the fol | `.ion-display-lg-{modifier}` | Applies the modifier to the element when `min-width: 992px`. | | `.ion-display-xl-{modifier}` | Applies the modifier to the element when `min-width: 1200px`. | -### Deprecated Classes +### Deprecated Classes {/* #deprecated-classes */} :::warning[Deprecation Notice] @@ -240,9 +240,9 @@ The following classes are deprecated and will be removed in the next major relea | `.ion-hide-lg-{dir}` | Applies the modifier to the element when `min-width: 992px` (`up`) or `max-width: 992px` (`down`).
**Deprecated** — Use the `ion-display-lg-{modifier}` classes instead. | | `.ion-hide-xl-{dir}` | Applies the modifier to the element when `min-width: 1200px` (`up`) or `max-width: 1200px` (`down`).
**Deprecated** — Use the `ion-display-xl-{modifier}` classes instead. | -## Content Space +## Content Space {/* #content-space */} -### Padding +### Padding {/* #padding */} The padding class sets the padding area of an element. The padding area is the space between the content of the element and its border. @@ -292,7 +292,7 @@ The default amount of `padding` to be applied is `16px` and is set by the `--ion | `.ion-padding-horizontal` | `padding: 0 16px` | Applies padding to the left and right. | | `.ion-no-padding` | `padding: 0` | Applies no padding to all sides. | -### Margin +### Margin {/* #margin */} The margin area extends the border area with an empty area used to separate the element from its neighbors. @@ -342,13 +342,13 @@ The default amount of `margin` to be applied is `16px` and is set by the `--ion- | `.ion-margin-horizontal` | `margin: 0 16px` | Applies margin to the left and right. | | `.ion-no-margin` | `margin: 0` | Applies no margin to all sides. | -## Flex Container Properties +## Flex Container Properties {/* #flex-container-properties */} Flexbox properties are divided into two categories: **container properties** that control the layout of all flex items, and **item properties** that control individual flex items. Refer to [Flex Item Properties](#flex-item-properties) for item-level alignment. -### Align Items +### Align Items {/* #align-items */} The [align-items](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items) CSS property sets the [align-self](#align-self) value on all direct children as a group. In flexbox, it controls the alignment of items on the cross axis. In grid layout, it controls the alignment of items on the block axis within their grid areas. @@ -364,7 +364,7 @@ Ionic provides the following utility classes for `align-items`: | `.ion-align-items-baseline` | `align-items: baseline` | Items are aligned so that their baselines align. | | `.ion-align-items-stretch` | `align-items: stretch` | Items are stretched to fill the container. | -### Align Content +### Align Content {/* #align-content */} The [align-content](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content) CSS property sets the distribution of space between and around content items along a flexbox's cross axis, or a grid or block-level element's block axis. @@ -383,7 +383,7 @@ Ionic provides the following utility classes for `align-content`: | `.ion-align-content-between` | `align-content: space-between` | Lines are evenly distributed on the cross axis. | | `.ion-align-content-around` | `align-content: space-around` | Lines are evenly distributed with equal space around them. | -### Justify Content +### Justify Content {/* #justify-content */} The [justify-content](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content) CSS property defines how the browser distributes space between and around content items along the main axis of a flex container and the inline axis of grid and multi-column containers. @@ -400,7 +400,7 @@ Ionic provides the following utility classes for `justify-content`: | `.ion-justify-content-between` | `justify-content: space-between` | Items are evenly distributed on the main axis. | | `.ion-justify-content-evenly` | `justify-content: space-evenly` | Items are distributed so that the spacing between any two items is equal. | -### Flex Direction +### Flex Direction {/* #flex-direction */} The [flex-direction](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction) CSS property sets how flex items are placed in the flex container defining the main axis and the direction (normal or reversed). @@ -415,7 +415,7 @@ Ionic provides the following utility classes for `flex-direction`: | `.ion-flex-column` | `flex-direction: column` | Items are placed vertically. | | `.ion-flex-column-reverse` | `flex-direction: column-reverse` | Items are placed vertically in reverse order. | -### Flex Wrap +### Flex Wrap {/* #flex-wrap */} The [flex-wrap](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap) CSS property sets whether flex items are forced onto one line or can wrap onto multiple lines. If wrapping is allowed, it sets the direction that lines are stacked. @@ -429,7 +429,7 @@ Ionic provides the following utility classes for `flex-wrap`: | `.ion-flex-wrap` | `flex-wrap: wrap` | Items will wrap onto multiple lines, from top to bottom. | | `.ion-flex-wrap-reverse` | `flex-wrap: wrap-reverse` | Items will wrap onto multiple lines, from bottom to top. | -### Responsive Flex Container Classes +### Responsive Flex Container Classes {/* #responsive-flex-container-classes */} All of the flex container classes listed above have additional classes to modify the properties based on the screen size. Instead of the base class name, use `{property}-{breakpoint}-{modifier}` to only use the class on specific screen sizes, where `{breakpoint}` is one of the breakpoint names listed in [Ionic Breakpoints](#ionic-breakpoints). @@ -443,7 +443,7 @@ The table below shows the default behavior, where `{property}` is one of the fol | `.ion-{property}-lg-{modifier}` | Applies the modifier to the element when `min-width: 992px`. | | `.ion-{property}-xl-{modifier}` | Applies the modifier to the element when `min-width: 1200px`. | -### Deprecated Classes +### Deprecated Classes {/* #deprecated-classes-1 */} :::warning[Deprecation Notice] @@ -457,11 +457,11 @@ The following classes are deprecated and will be removed in the next major relea | `.ion-wrap` | Items will wrap onto multiple lines, from top to bottom.
**Deprecated** — Use `.ion-flex-wrap` instead. | | `.ion-wrap-reverse` | Items will wrap onto multiple lines, from bottom to top.
**Deprecated** — Use `.ion-flex-wrap-reverse` instead. | -## Flex Item Properties +## Flex Item Properties {/* #flex-item-properties */} Flex item properties control how individual flex items behave within their flex container. See also: [Flex Container Properties](#flex-container-properties) for container-level alignment. -### Align Self +### Align Self {/* #align-self */} The [align-self](https://developer.mozilla.org/en-US/docs/Web/CSS/align-self) CSS property overrides a grid or flex item's align-items value. In grid, it aligns the item inside the grid area. In flexbox, it aligns the item on the cross axis. @@ -480,7 +480,7 @@ Ionic provides the following utility classes for `align-self`: | `.ion-align-self-stretch` | `align-self: stretch` | Item is stretched to fill the container. | | `.ion-align-self-auto` | `align-self: auto` | Item is positioned according to the parent's `align-items` value. | -### Flex +### Flex {/* #flex */} The [flex](https://developer.mozilla.org/en-US/docs/Web/CSS/flex) CSS property is a shorthand property for `flex-grow`, `flex-shrink` and `flex-basis`. It sets how a flex item will grow or shrink to fit the space available in its flex container. @@ -495,7 +495,7 @@ Ionic provides the following utility classes for `flex`: | `.ion-flex-initial` | `flex: initial` | Item shrinks to its minimum content size but does not grow. | | `.ion-flex-none` | `flex: none` | Item does not grow or shrink. | -### Flex Grow +### Flex Grow {/* #flex-grow */} The [flex-grow](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow) CSS property sets the flex grow factor, which specifies how much of the flex container's positive free space, if any, should be assigned to the flex item's main size. @@ -508,7 +508,7 @@ Ionic provides the following utility classes for `flex-grow`: | `.ion-flex-grow-0` | `flex-grow: 0` | Item does not grow beyond its content size. | | `.ion-flex-grow-1` | `flex-grow: 1` | Item grows to fill available space proportionally. | -### Flex Shrink +### Flex Shrink {/* #flex-shrink */} The [flex-shrink](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink) CSS property sets the flex shrink factor of a flex item. If the size of all flex items is larger than the flex container, the flex items can shrink to fit according to their `flex-shrink` value. Each flex line's negative free space is distributed between the line's flex items that have a `flex-shrink` value greater than `0`. @@ -521,7 +521,7 @@ Ionic provides the following utility classes for `flex-shrink`: | `.ion-flex-shrink-0` | `flex-shrink: 0` | Item does not shrink below its content size. | | `.ion-flex-shrink-1` | `flex-shrink: 1` | Item shrinks proportionally when container is too small. | -### Order +### Order {/* #order */} The [order](https://developer.mozilla.org/en-US/docs/Web/CSS/order) CSS property sets the order to lay out an item in a flex or grid container. Items in a container are sorted by ascending `order` value and then by their source code order. Items not given an explicit `order` value are assigned the default value of `0`. @@ -547,7 +547,7 @@ Ionic provides the following utility classes for `order`: | `.ion-order-12` | `order: 12` | Item appears after items with order 11. | | `.ion-order-last` | `order: 13` | Item appears last in the flex container. | -### Responsive Flex Item Classes +### Responsive Flex Item Classes {/* #responsive-flex-item-classes */} All of the flex item classes listed above have additional classes to modify the properties based on the screen size. Instead of the base class name, use `{property}-{breakpoint}-{modifier}` to only use the class on specific screen sizes, where `{breakpoint}` is one of the breakpoint names listed in [Ionic Breakpoints](#ionic-breakpoints). @@ -561,7 +561,7 @@ The table below shows the default behavior, where `{property}` is one of the fol | `.ion-{property}-lg-{modifier}` | Applies the modifier to the element when `min-width: 992px`. | | `.ion-{property}-xl-{modifier}` | Applies the modifier to the element when `min-width: 1200px`. | -## Border Display +## Border Display {/* #border-display */} The `.ion-no-border` utility class can be used to remove borders from Ionic components. This class can be applied to the `ion-header` and `ion-footer` components. @@ -583,7 +583,7 @@ The `.ion-no-border` utility class can be used to remove borders from Ionic comp | ---------------- | -------------------------------- | | `.ion-no-border` | The element will have no border. | -## Ionic Breakpoints +## Ionic Breakpoints {/* #ionic-breakpoints */} Ionic uses breakpoints in media queries in order to style an application differently based on the screen size. The following breakpoint names are used in the utility classes listed above, where the class will apply when the width is met. diff --git a/docs/layout/dynamic-font-scaling.mdx b/docs/layout/dynamic-font-scaling.mdx index 14e95451422..efc82582b42 100644 --- a/docs/layout/dynamic-font-scaling.mdx +++ b/docs/layout/dynamic-font-scaling.mdx @@ -2,7 +2,7 @@ Dynamic Font Scaling is a feature that allows users to choose the size of the text displayed on the screen. This helps users who need larger text for better readability, and it also accommodates users who can read smaller text. -## Try It Out +## Try It Out {/* #try-it-out */} :::tip @@ -18,19 +18,19 @@ import DynamicFontScaling from '@site/static/usage/v10/layout/dynamic-font-scali -## Using Dynamic Font Scaling +## Using Dynamic Font Scaling {/* #using-dynamic-font-scaling */} -### Enabling in an Application +### Enabling in an Application {/* #enabling-in-an-application */} Dynamic Font Scaling is enabled by default as long as the [typography.css](/layout/global-stylesheets.mdx#typographycss) file is imported. Importing this file will define the `--ion-dynamic-font` variable which will activate Dynamic Font Scaling. While not recommended, developers can opt-out of Dynamic Font Scaling by setting this variable to `initial` in their application code. -### Integrating Custom Components +### Integrating Custom Components {/* #integrating-custom-components */} Developers can configure their custom components to take advantage of Dynamic Font Scaling by converting any `font-size` declarations that use `px` units to use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths) instead. An easy way to convert from `px` to `rem` is to divide the pixel font size by the default browser font size, which is typically `16px`. For example, if a component has a font size of `14px`, then this could be converted to `rem` by doing `14px / 16px = 0.875rem`. Also note that any Ionic components that have had their font sizes overridden should also be updated to use `rem` units. One thing to keep in mind is that the dimensions of your components may need to change to accommodate the larger font sizes. For example, `width` and `height` properties may need to change to `min-width` and `min-height`, respectively. Developers should audit their applications for any CSS properties that use [length values](https://developer.mozilla.org/en-US/docs/Web/CSS/length) and make any applicable conversions from `px` to `rem`. We also recommend having long text wrap to the next line instead of truncating to keep large text readable. -### Custom Font Family +### Custom Font Family {/* #custom-font-family */} We recommend using the default fonts in Ionic as they are designed to look good at any size and ensure consistency with other mobile apps. However, developers can use a custom font family with Dynamic Font Scaling via CSS: @@ -41,7 +41,7 @@ html { } ``` -### `em` units versus `rem` units +### `em` units versus `rem` units {/* #em-units-versus-rem-units */} Developers have two options for relative font sizes: [`em` and `rem`](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#ems_and_rems). @@ -93,11 +93,11 @@ In the following example, the computed font size of `.child` is `32px` because t } ``` -## How Dynamic Font Scaling works in Ionic +## How Dynamic Font Scaling works in Ionic {/* #how-dynamic-font-scaling-works-in-ionic */} Ionic components that define font sizes and participate in Dynamic Font Scaling typically use [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths). This sizes the text in each component relative to the font size of the root element, which is usually the `html` element. This means that as the root element's font size changes, the text in all Ionic components scale in a consistent manner. This avoids the need to manually override each component's font size. Some elements inside of these components, such as icons, use `em` units instead so the elements are sized relative to the text, though the text itself is sized using `rem` units. -### iOS +### iOS {/* #ios */} Dynamic Font Scaling in Ionic builds on top of an iOS feature called [Dynamic Type](https://developer.apple.com/documentation/uikit/uifont/scaling_fonts_automatically#overview). To do this, Ionic sets the [font](https://developer.mozilla.org/en-US/docs/Web/CSS/font) of the root element to an Apple-defined text style. For consistency, Ionic uses the [body](https://developer.apple.com/documentation/uikit/uifont/textstyle/1616682-body) text style. @@ -109,7 +109,7 @@ Ionic follows [Apple's Human Interface Guidelines for Typography](https://develo 2. Components such as `ion-badge` and `ion-back-button` will have minimum font sizes so they remain readable. 3. Text in components such as `ion-tab-bar` and `ion-picker` do not participate in Dynamic Font Scaling according to Apple's Human Interface Guidelines. -### Android Web View +### Android Web View {/* #android-web-view */} The Android Web View's font scaling mechanism is always enabled in web content and will automatically scale font sizes defined using the `px` unit. This means that any maximum or minimum font sizes specified using `px` will still be scaled even if the final font size does not align with the maximum or minimum font sizes specified. @@ -127,7 +127,7 @@ This is larger than our defined maximum of `14px`, so one might assume that the As a result, this means that the maximum computed font size is actually `21px` since `14 * 1.5 = 21` and therefore the overall computed font size of `.foo` is `21px`. -### Chrome for Android +### Chrome for Android {/* #chrome-for-android */} The Chrome Web Browser on Android behaves differently than the Android Web View. By default, Chrome for Android does not respect the system-level font scale setting. However, the Chromium team is working on a new feature to allow for this. When enabled, this feature will change the `zoom` level of the `html` element which will cause the layout to increase in size in addition to the text. @@ -135,7 +135,7 @@ Developers can test this behavior by enabling the experimental "Accessibility Pa See https://bugs.chromium.org/p/chromium/issues/detail?id=645717 for more information. -### Using Modes on Different Platforms +### Using Modes on Different Platforms {/* #using-modes-on-different-platforms */} Each platform has slightly different font scaling behaviors, and the `ios` and `md` modes have been implemented to take advantage of the scaling behaviors on their respective platforms. @@ -143,17 +143,17 @@ For example, `ios` mode makes use of maximum and minimum font sizes to follow [A As a result, we strongly recommend using `ios` mode on iOS devices and `md` mode on Android devices when using Dynamic Font Scaling. -## Changing the Font Size on a Device +## Changing the Font Size on a Device {/* #changing-the-font-size-on-a-device */} Font scaling preferences are configured on a per-device basis by the user. This allows the user to scale the font for all applications that support this behavior. This guide shows how to enable font scaling for each platform. -### iOS +### iOS {/* #ios-1 */} Font scaling on iOS can be configured in the Settings app. Refer to [Apple Support](https://support.apple.com/en-us/102453) for more information. -### Android +### Android {/* #android */} Where users access the font scaling configuration varies across devices, but it is typically found in the "Accessibility" page in the Settings app. @@ -163,9 +163,9 @@ The Chrome Web Browser on Android has some limitations with respecting system-le ::: -## Troubleshooting +## Troubleshooting {/* #troubleshooting */} -### Dynamic Font Scaling is not working +### Dynamic Font Scaling is not working {/* #dynamic-font-scaling-is-not-working */} There are a number of reasons why Dynamic Font Scaling may not have any effect on an app. The following list, while not exhaustive, provides some things to check to debug why Dynamic Font Scaling is not working. @@ -175,21 +175,21 @@ There are a number of reasons why Dynamic Font Scaling may not have any effect o 4. Verify that your code does not override font sizes on Ionic components. Ionic components that set `font-size` rules will use `rem` units. However, if your app overrides that to use `px`, then that custom rule will need to be converted to use `rem`. Refer to [Integrating Custom Components](#integrating-custom-components) for more information. 5. Verify "Accessibility Page Zoom" is enabled if using Chrome for Android. Refer to [Chrome for Android](#chrome-for-android) for more information. -### Maximum and minimum font sizes are not being respected on Android +### Maximum and minimum font sizes are not being respected on Android {/* #maximum-and-minimum-font-sizes-are-not-being-respected-on-android */} The Android Web View scales any font sizes defined using the `px` unit by the system-level font scale preference. This means that actual font sizes may be larger or smaller than the font sizes defined in [min()](https://developer.mozilla.org/en-US/docs/Web/CSS/min), [max()](https://developer.mozilla.org/en-US/docs/Web/CSS/max), or [clamp()](https://developer.mozilla.org/en-US/docs/Web/CSS/clamp). Refer to [how font scaling works on Android](#android) for more information. -### Font sizes are larger/smaller even with Dynamic Font Scaling disabled +### Font sizes are larger/smaller even with Dynamic Font Scaling disabled {/* #font-sizes-are-largersmaller-even-with-dynamic-font-scaling-disabled */} Ionic components define font sizes using [rem units](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Values_and_units#lengths) even when Dynamic Font Scaling is disabled. This sizes the text in each component relative to the font size of the root element, which is usually the `html` element. As a result, if the font size of `html` changes, the computed font size of all Ionic components will change too. -### Scaled Ionic iOS component font sizes do not exactly match native iOS equivalents +### Scaled Ionic iOS component font sizes do not exactly match native iOS equivalents {/* #scaled-ionic-ios-component-font-sizes-do-not-exactly-match-native-ios-equivalents */} Certain native iOS components such as the Action Sheet make use of private font scales that Ionic does not have access to. While we try to stay as close as possible to the native behavior, text in some components may render slightly larger or smaller than their native counterparts. -### The text size in my Ionic app on iOS changed when enabling Dynamic Font Scaling +### The text size in my Ionic app on iOS changed when enabling Dynamic Font Scaling {/* #the-text-size-in-my-ionic-app-on-ios-changed-when-enabling-dynamic-font-scaling */} The root element's default font size is typically `16px`. However, Dynamic Font Scaling on iOS devices make use of the ["Body" text style](https://developer.apple.com/design/human-interface-guidelines/typography#Specifications) which has a default font size of `17px`. Since the text in Ionic components is scaled relative to the root element's font size, some text may get larger or smaller when Dynamic Font Scaling is enabled, even if the system-level text scale did not change. diff --git a/docs/layout/global-stylesheets.mdx b/docs/layout/global-stylesheets.mdx index 1075494da54..28ffbac6189 100644 --- a/docs/layout/global-stylesheets.mdx +++ b/docs/layout/global-stylesheets.mdx @@ -12,60 +12,60 @@ title: Global Stylesheets While Ionic Framework component styles are self-contained, there are several global stylesheets that should be included in order to use all of Ionic's features. Some of the stylesheets are required in order for an Ionic Framework app to look and behave properly, and others include optional utilities to quickly style your app. -## Available +## Available {/* #available */} -### Required +### Required {/* #required */} The following CSS file must be included in order for Ionic Framework to work properly. -#### core.css +#### core.css {/* #corecss */} This file is the only stylesheet that is required in order for Ionic components to work properly. It includes app specific styles, and allows the `color` property to work across components. If this file is not included the colors will not show up and some elements may not appear properly. -### Recommended +### Recommended {/* #recommended */} The following CSS files are recommended to be included in an Ionic Framework app. If they are not included, some elements may have undesired styles. If Ionic Framework components are being used outside of an app, these files may not be necessary. -#### structure.css +#### structure.css {/* #structurecss */} Applies styles to `` and defaults `box-sizing` to `border-box`. It ensures scrolling behaves like native in mobile devices. -#### typography.css +#### typography.css {/* #typographycss */} Typography changes the font-family of the entire document and modifies the font styles for heading elements. It also applies positioning styles to some native text elements. This file is necessary for [Dynamic Font Scaling](./dynamic-font-scaling) to work. -#### normalize.css +#### normalize.css {/* #normalizecss */} Makes browsers render all elements more consistently and in line with modern standards. It is based on [Normalize.css](https://necolas.github.io/normalize.css/). -### Optional +### Optional {/* #optional */} The following set of CSS files are optional and can safely be commented out or removed if the application is not using any of the features. -#### padding.css +#### padding.css {/* #paddingcss */} Adds utility classes to modify the padding or margin on any element, refer to [CSS Utilities](css-utilities.mdx#content-space) for usage information. -#### float-elements.css +#### float-elements.css {/* #float-elementscss */} Adds utility classes to float an element based on the breakpoint and side, refer to [CSS Utilities](css-utilities.mdx#element-placement) for usage information. -#### text-alignment.css +#### text-alignment.css {/* #text-alignmentcss */} Adds utility classes to align the text of an element or adjust the white space based on the breakpoint, refer to [CSS Utilities](css-utilities.mdx#text-align) for usage information. -#### text-transformation.css +#### text-transformation.css {/* #text-transformationcss */} Adds utility classes to transform the text of an element to `uppercase`, `lowercase` or `capitalize` based on the breakpoint, refer to [CSS Utilities](css-utilities.mdx#text-transform) for usage information. -#### flex-utils.css +#### flex-utils.css {/* #flex-utilscss */} Adds utility classes to align flex containers and items, refer to [CSS Utilities](css-utilities.mdx#flex-container-properties) for usage information. -#### display.css +#### display.css {/* #displaycss */} Adds utility classes to hide any element based on the breakpoint, refer to [CSS Utilities](css-utilities.mdx#element-display) for usage information. -## Usage +## Usage {/* #usage */} Refer to [Ionic Packages](../intro/cdn.mdx) for how to include the global stylesheets based on the framework and [CSS Utilities](css-utilities.mdx) for how to use the optional utilities. diff --git a/docs/layout/structure.mdx b/docs/layout/structure.mdx index 6ef346fd9c8..ef8c6c7285d 100644 --- a/docs/layout/structure.mdx +++ b/docs/layout/structure.mdx @@ -15,9 +15,9 @@ import DocsCards from '@components/global/DocsCards'; Ionic Framework provides several different layouts that can be used to structure an app. From single page layouts, to split pane views and modals. -## Header and Footer Layout +## Header and Footer Layout {/* #header-and-footer-layout */} -### Header +### Header {/* #header */} The most simple layout available consists of a [header](../api/header.mdx) and [content](../api/content.mdx). Most pages in an app generally have both of these, but a header is not required in order to use content. @@ -25,7 +25,7 @@ import Header from '@site/static/usage/v10/header/basic/index.mdx';
-### Footer +### Footer {/* #footer */} While a toolbar in a header appears above the content, a footer appears below the content. A header and a footer can also be used together on the same page. @@ -33,7 +33,7 @@ import Footer from '@site/static/usage/v10/footer/basic/index.mdx';