@@ -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.
.default})
-### 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 acea28c2c5..f042b9e43c 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/v9/layout/dynamic-font-scalin
-## 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 1075494da5..28ffbac618 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 079d705184..20c48cba93 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/v9/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/v9/footer/basic/index.mdx';
-## Tabs Layout
+## Tabs Layout {/* #tabs-layout */}
A layout consisting of horizontal [tabs](../api/tabs.mdx) can be used to let the user quickly change between content views. Each tab can contain static content or a navigation stack by using a [router outlet](../api/router-outlet.mdx) or [nav](../api/nav.mdx).
@@ -41,7 +41,7 @@ import Tabs from '@site/static/usage/v9/tabs/router/index.mdx';
-## Menu Layout
+## Menu Layout {/* #menu-layout */}
A standard layout among mobile apps includes the ability to toggle a side [menu](../api/menu.mdx) by clicking a button or swiping it open from the side. Side menus are generally used for navigation, but they can contain any content.
@@ -49,7 +49,7 @@ import Menu from '@site/static/usage/v9/menu/basic/index.mdx';
-## Split Pane Layout
+## Split Pane Layout {/* #split-pane-layout */}
A [split pane](../api/split-pane.mdx) layout has a more complex structure because it can combine the previous layouts. It allows for multiple views to be displayed when the viewport is above a specified breakpoint. If the device's screen size is below a certain size, the split pane view will be hidden.
diff --git a/docs/native-faq.mdx b/docs/native-faq.mdx
index 10c8a9eadf..3251f29cd2 100644
--- a/docs/native-faq.mdx
+++ b/docs/native-faq.mdx
@@ -5,11 +5,11 @@ slug: /native/faq
# Frequently Asked Question
-## What is Capacitor?
+## What is Capacitor? {/* #what-is-capacitor */}
Capacitor is a native runtime built by the Ionic team that offers web developers the ability to deploy their web apps to a native device. Capacitor is also exposing native device capabilities through JavaScript so developers can access features like native location services, filesystem access, or notifications as if they are interacting with any other JavaScript library.
-## Permission Issues
+## Permission Issues {/* #permission-issues */}
If you're using a plugin, it may require adding additional permissions to your native project after you install the plugin. For instance, the Capacitor Camera plugin requires the following permission for iOS:
@@ -19,6 +19,6 @@ If you're using a plugin, it may require adding additional permissions to your n
You need to manually add those permissions to the `info.plist` in your native project. Otherwise, calls to the native camera API will fail.
-## Unexpected behavior
+## Unexpected behavior {/* #unexpected-behavior */}
If for some reason the plugin does not behave in a way that is unexpected, please [open an issue on our github repo](https://github.com/ionic-team/capacitor-plugins)! Providing a clear issue report along with a reproduction can help get your issue resolved.
diff --git a/docs/native-setup.mdx b/docs/native-setup.mdx
index 03a10ea286..e4889b192f 100644
--- a/docs/native-setup.mdx
+++ b/docs/native-setup.mdx
@@ -24,7 +24,7 @@ import TabItem from '@theme/TabItem';
Getting started with Capacitor is fairly straight forward for Ionic developers. Adding plugins to your project is no different than adding any dependencies you may need to a project.
-## Install
+## Install {/* #install */}
To install a plugin, find the plugin you want to use and install it using your package manager, like npm:
@@ -33,7 +33,7 @@ To install a plugin, find the plugin you want to use and install it using your p
$ npm install @capacitor/camera
```
-## Usage
+## Usage {/* #usage */}
Once installed, plugins can be imported into a component and you can call the native functionality directly from your code.
diff --git a/docs/react/add-to-existing.mdx b/docs/react/add-to-existing.mdx
index 95d0807954..d74edc5777 100644
--- a/docs/react/add-to-existing.mdx
+++ b/docs/react/add-to-existing.mdx
@@ -22,7 +22,7 @@ This guide uses TypeScript examples. If you're using JavaScript, the setup proce
:::
-## Setup
+## Setup {/* #setup */}
:::info
@@ -32,13 +32,13 @@ This guide follows the structure of a React app created with Vite. If you starte
Follow these steps to add Ionic React to your existing React project:
-#### 1. Install the Package
+#### 1. Install the Package {/* #1-install-the-package */}
```bash
npm install @ionic/react
```
-#### 2. Configure Ionic React
+#### 2. Configure Ionic React {/* #2-configure-ionic-react */}
Update `src/App.tsx` to include `setupIonicReact` and import the required Ionic Framework stylesheets:
@@ -68,7 +68,7 @@ While `core.css` is required, `normalize.css`, `structure.css`, and `typography.
:::
-## Using Individual Components
+## Using Individual Components {/* #using-individual-components */}
After completing the setup above, you can start using Ionic components in your existing React app. Here's an example of how to use them:
@@ -106,11 +106,11 @@ If your existing React app imports a global stylesheet (such as `index.css`) in
:::
-## 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 */}
Update the imported stylesheets in `src/App.tsx`:
@@ -134,7 +134,7 @@ import '@ionic/react/css/display.css';
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:
@@ -171,7 +171,7 @@ setupIonicReact();
The `variables.css` file can be used to create custom Ionic Framework themes. The `dark.system.css` import 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 to `theme/variables.css`.
-#### 3. Update the App Component
+#### 3. Update the App Component {/* #3-update-the-app-component */}
Update `src/App.tsx` to the following:
@@ -224,7 +224,7 @@ const App = () => {
export default App;
```
-#### 4. Create a Home Page
+#### 4. Create a Home Page {/* #4-create-a-home-page */}
Create a new file at `src/pages/Home.tsx` with the following:
@@ -298,7 +298,7 @@ Then, create `src/pages/Home.css`:
}
```
-#### 5. Set up Routing
+#### 5. Set up Routing {/* #5-set-up-routing */}
:::important
@@ -340,7 +340,7 @@ export default App;
You're all set! Your Ionic React app is now configured with full Ionic page support. Run `npm run dev` to start your development server and view your app.
-## Next Steps
+## Next Steps {/* #next-steps */}
Now that you have Ionic React integrated into your project, check out:
diff --git a/docs/react/lifecycle.mdx b/docs/react/lifecycle.mdx
index 3501dec7cd..da588fecda 100644
--- a/docs/react/lifecycle.mdx
+++ b/docs/react/lifecycle.mdx
@@ -13,7 +13,7 @@ sidebar_label: Lifecycle
This guide discusses how to use the Ionic Lifecycle events in an Ionic React application.
-## Ionic Lifecycle Methods
+## Ionic Lifecycle Methods {/* #ionic-lifecycle-methods */}
Ionic provides a few lifecycle methods that you can use in your apps:
@@ -28,7 +28,7 @@ These lifecycles are only called on components directly mapped by a router. This
The way you access these methods varies based on if you are using class-based components or functional components. We cover both methods below.
-## Lifecycle Methods in Class-Based Components
+## Lifecycle Methods in Class-Based Components {/* #lifecycle-methods-in-class-based-components */}
to use the Ionic Lifecycle methods in a class-based component, you must wrap your component with the `withIonLifeCycle` higher order component (HOC) like so:
@@ -82,7 +82,7 @@ class HomePage extends React.Component {
export default withIonLifeCycle(HomePage);
```
-## Lifecycle Methods in Functional Components
+## Lifecycle Methods in Functional Components {/* #lifecycle-methods-in-functional-components */}
Ionic React exports hooks for each of the lifecycle methods that you can use in your functional components. Each of the hooks takes the method you want called when the event fires.
@@ -147,11 +147,11 @@ useIonViewDidEnter(() => {
}, [data]);
```
-## React LifeCycle Methods
+## React LifeCycle Methods {/* #react-lifecycle-methods */}
All the lifecycle methods in React (`componentDidMount`, `componentWillUnmount`, etc..) are available for you to use as well. However, since Ionic React manages the lifetime of a page, certain events might not fire when you expect them to. For instance, `componentDidMount` fires the first time a page is displayed, but if you navigate away from the page Ionic might keep the page around in the DOM, and a subsequent visit to the page might not call `componentDidMount` again. This scenario is the main reason the Ionic lifecycle methods exist, to still give you a way to call logic when views enter and exit when the native framework's events might not fire.
-## Guidance for Each LifeCycle Method
+## Guidance for Each LifeCycle Method {/* #guidance-for-each-lifecycle-method */}
Below are some tips on use cases for each of the life cycle events.
@@ -160,7 +160,7 @@ Below are some tips on use cases for each of the life cycle events.
- `ionViewWillLeave` - Can be used for cleanup, like unsubscribing from data sources. Since `componentWillUnmount` might not fire when you navigate from the current page, put your cleanup code here if you don't want it active while the screen is not in view.
- `ionViewDidLeave` - When this event fires, you know the new page has fully transitioned in, so any logic you might not normally do when the view is visible can go here.
-## Passing state between pages
+## Passing state between pages {/* #passing-state-between-pages */}
Since Ionic React manages the lifetime of a page, state on previous pages may update as users navigate your application. This can impact state that is determined using `useEffect` from React or `useLocation` from React Router. For example, if `PageA` calls `useLocation`, the state of `useLocation` will change when the user navigates from `PageA` to `PageB`.
diff --git a/docs/react/navigation.mdx b/docs/react/navigation.mdx
index 0557db6278..88ea09bff2 100644
--- a/docs/react/navigation.mdx
+++ b/docs/react/navigation.mdx
@@ -19,7 +19,7 @@ This guide covers how routing works in an app built with Ionic and React.
Everything you know about routing using React Router carries over into Ionic React. Let's walk through the basics of an Ionic React app and how routing works with it.
-## Routing in Ionic React
+## Routing in Ionic React {/* #routing-in-ionic-react */}
Here is a sample `App` component that defines a single route to the "/dashboard" URL. When you visit "/dashboard", the route renders the `DashboardPage` component.
@@ -46,11 +46,11 @@ You can also conditionally redirect based on a condition, like checking if a use
: } />
```
-## IonReactRouter
+## IonReactRouter {/* #ionreactrouter */}
The `IonReactRouter` component wraps the traditional [`BrowserRouter`](https://reactrouter.com/6.28.0/router-components/browser-router) component from React Router, and sets the app up for routing. Therefore, use `IonReactRouter` in place of `BrowserRouter`. You can pass in any props to `IonReactRouter` and they will be passed down to the underlying `BrowserRouter`.
-## Nested Routes
+## Nested Routes {/* #nested-routes */}
Inside the Dashboard page, we define more routes related to this specific section of the app:
@@ -71,9 +71,9 @@ Note the `ionPage` prop on `IonRouterOutlet`. When a component serves as a neste
These routes are grouped in an `IonRouterOutlet`, let's discuss that next.
-## Components
+## Components {/* #components */}
-### IonRouterOutlet
+### IonRouterOutlet {/* #ionrouteroutlet */}
The `IonRouterOutlet` component provides a container for Routes that render Ionic "pages". When a page is in an `IonRouterOutlet`, the container controls the transition animation between the pages as well as controls when a page is created and destroyed, which helps maintain the state between the views when switching back and forth between them.
@@ -81,7 +81,7 @@ The `DashboardPage` above shows a users list page and a details page. When navig
An `IonRouterOutlet` should only contain `Route`s. Any other component should be rendered either as a result of a `Route` or outside of the `IonRouterOutlet`.
-### Fallback Route
+### Fallback Route {/* #fallback-route */}
A common routing use case is to provide a "fallback" route to be rendered in the event the location navigated to does not match any of the routes defined.
@@ -113,7 +113,7 @@ const DashboardPage: React.FC = () => (
);
```
-### IonPage
+### IonPage {/* #ionpage */}
The `IonPage` component wraps each view in an Ionic React app and allows page transitions and stack navigation to work properly. Each view that is navigated to using the router must include an `IonPage` component.
@@ -138,7 +138,7 @@ const Home: React.FC = () => {
export default Home;
```
-## Navigation
+## Navigation {/* #navigation */}
There are several options available when routing to different views in an Ionic React app. Here, the `UsersListPage` uses `IonItem`'s `routerLink` prop to specify the route to go to when the item is tapped/clicked:
@@ -201,7 +201,7 @@ const MyComponent: React.FC = () => {
};
```
-### Navigating using `navigate` with delta
+### Navigating using `navigate` with delta {/* #navigating-using-navigate-with-delta */}
React Router's `navigate` function can accept a delta number to move forward or backward through the application history.
@@ -213,7 +213,7 @@ If you were to call `navigate(-2)` on `/pageC`, you would be brought back to `/p
Using `navigate()` with delta values is not recommended in Ionic React because it follows the browser's linear history, which does not account for Ionic's non-linear tab and nested outlet navigation stacks. Use the `useIonRouter` hook's [`goBack()`](./utility-functions.mdx#back-navigation) method instead, which navigates within the current Ionic navigation stack.
-## URL Parameters
+## URL Parameters {/* #url-parameters */}
The second route defined in the Dashboard Page has a URL parameter defined (the ":id" portion in the path). URL parameters are dynamic portions of the `path`, and when the user navigates to a URL such as "/dashboard/users/1", the "1" is saved to a parameter named "id", which can be accessed in the component the route renders. Let's walk through how that's done.
@@ -242,9 +242,9 @@ The [`useParams`](https://reactrouter.com/6.28.0/hooks/use-params) hook returns
Note how we use a TypeScript generic to strongly type the params object. This gives us type safety and code completion inside of the component.
-## 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.
@@ -268,7 +268,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.
@@ -296,7 +296,7 @@ If tapping the back button simply called `navigate(-1)` from the `Ted Lasso` vie
Non-linear routing allows for sophisticated user flows that linear routing cannot handle. However, certain linear routing APIs such as `navigate()` with delta values cannot be used in this non-linear environment. This means that `navigate(-1)` or similar delta navigation 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.
@@ -306,11 +306,11 @@ For more on tabs, refer to [Working with Tabs](#working-with-tabs).
For more on nested router outlets, 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:
@@ -329,7 +329,7 @@ const App: React.FC = () => (
The above routes are considered "shared" because they reuse the `dashboard` piece of the URL. Since these routes are flat siblings in the same `IonRouterOutlet` (not nested), they don't need a `/*` suffix.
-### Nested Routes
+### Nested Routes {/* #nested-routes-1 */}
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:
@@ -354,7 +354,7 @@ const DashboardRouterOutlet: React.FC = () => (
The above routes are nested because they are rendered inside the `DashboardRouterOutlet` component, which is a child of the parent route. The parent route uses a `/*` suffix to match all sub-paths, and the nested `IonRouterOutlet` renders the appropriate child route.
-### 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.
@@ -362,7 +362,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 */}
When working with tabs, Ionic needs a way to know which view belongs to which tab. The `IonTabs` component comes in handy here, but let's examine the routing setup for this:
@@ -425,7 +425,7 @@ If you have worked with Ionic Framework before, this should feel familiar. We cr
:::
-### 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).
@@ -433,7 +433,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 `tab1/view` route as a sibling of the `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 `IonTabBar`.
@@ -463,7 +463,7 @@ When adding additional routes to tabs you should write them as sibling routes wi
```
-### 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.
@@ -501,13 +501,13 @@ The example below shows how the Spotify app reuses the same album component to s
| :-------------------------------------------------: | :---------------------------------------------------: |
| })
| })
|
-## Live Example
+## Live Example {/* #live-example */}
import NavigationPlayground from '@site/static/usage/v9/navigation/index.mdx';
-### IonRouterOutlet in a Tabs View
+### IonRouterOutlet in a Tabs View {/* #ionrouteroutlet-in-a-tabs-view */}
When working in a tabs view, Ionic React needs a way to determine what views belong to which tabs. It does this by matching the path prefix of each route.
@@ -523,7 +523,7 @@ For example, the routes for a view with two tabs (sessions and speakers) can be
When a user navigates to a session detail page ("/sessions/1" for instance), `IonRouterOutlet` sees that both the list and detail pages share the same "sessions" path prefix and provides an animated page transition to the new view. If a user navigates to a different tab ("speakers" in this case), `IonRouterOutlet` knows not to provide the animation.
-## More Information
+## More Information {/* #more-information */}
For more info on routing in React using the React Router implementation that Ionic uses under the hood, check out their docs at [https://reactrouter.com/6.28.0](https://reactrouter.com/6.28.0).
diff --git a/docs/react/overlays.mdx b/docs/react/overlays.mdx
index da08888461..6bef22fbe1 100644
--- a/docs/react/overlays.mdx
+++ b/docs/react/overlays.mdx
@@ -6,7 +6,7 @@ sidebar_label: Overlays
For Ionic React, there are two techniques you can use to display overlay components like modals, alerts, action sheets, etc. In this guide, we will go over both of them.
-## Overlay Hooks
+## Overlay Hooks {/* #overlay-hooks */}
Starting in Ionic React 5.6, we introduced new React hooks you can use to control displaying and dismissing overlays. These hooks provide a programmatic way of controlling the overlays, as well as a way to use overlays outside of your Ionic Page without the need of a state management system.
@@ -66,7 +66,7 @@ const [present, dismiss] = useIonModal(Greeting, { name: 'Dave' });
Passing a JSX element instead of a component binds the props to the element, and `componentProps` is not type checked.
-## Overlay Components
+## Overlay Components {/* #overlay-components */}
Overlays can also be displayed by using components from `@ionic/react`. The components take a `isOpen` prop that you provide to control if the overlay is currently being displayed or not. When `isOpen` switches from true to false (and vise versa), Ionic will open/close the overlay with the appropriate animation. You can also supply any other additional config options as props to the overlay:
@@ -92,7 +92,7 @@ The Overlay Components are still a valid way of displaying overlays and are in n
:::
-## Docs for Overlays in Ionic
+## Docs for Overlays in Ionic {/* #docs-for-overlays-in-ionic */}
For full docs and usage examples for both the hook and component approach, visit the docs page for each of the overlays in Ionic:
diff --git a/docs/react/overview.mdx b/docs/react/overview.mdx
index 178ee6af6c..c355aae937 100644
--- a/docs/react/overview.mdx
+++ b/docs/react/overview.mdx
@@ -16,19 +16,19 @@ import DocsCards from '@components/global/DocsCards';
`@ionic/react` brings the full power of the Ionic Framework to React developers. It offers seamless integration with the React ecosystem, so you can build high-quality cross-platform apps using familiar React tools, components, and best practices. You also get access to Ionic's extensive UI library and native capabilities.
-## React Version Support
+## React Version Support {/* #react-version-support */}
Ionic React supports the latest versions of React. For detailed information on supported versions and our support policy, refer to the [Ionic React Support Policy](/reference/support.mdx#ionic-react).
-## React Tooling
+## React Tooling {/* #react-tooling */}
Ionic React works seamlessly with the React CLI and popular React tooling. You can use your favorite libraries for state management, testing, and more. Ionic React is designed to fit naturally into the React ecosystem, so you can use tools like Create React App, Vite, or Next.js to scaffold and build your 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 */}
```shell-session
$ npm install -g @ionic/cli
@@ -38,7 +38,7 @@ $ cd myApp
$ ionic serve █
```
-## Resources
+## Resources {/* #resources */}
diff --git a/docs/react/performance.mdx b/docs/react/performance.mdx
index c5d029b11a..013614bc59 100644
--- a/docs/react/performance.mdx
+++ b/docs/react/performance.mdx
@@ -11,7 +11,7 @@ sidebar_label: Performance
/>
-## Loops with Ionic Components
+## Loops with Ionic Components {/* #loops-with-ionic-components */}
When using loops with Ionic components, we recommend using React's `key` attribute. This allows React to re-render loop elements in an efficient way by only updating the content inside of the component rather than re-creating the component altogether.
diff --git a/docs/react/platform.mdx b/docs/react/platform.mdx
index eb391d0479..83d1a62e59 100644
--- a/docs/react/platform.mdx
+++ b/docs/react/platform.mdx
@@ -1,6 +1,6 @@
# Platform
-## isPlatform
+## isPlatform {/* #isplatform */}
The `isPlatform` method can be used to test if your app is running on a certain platform:
@@ -12,7 +12,7 @@ isPlatform('ios'); // returns true when running on a iOS device
Depending on the platform the user is on, isPlatform(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.
-## getPlatforms
+## getPlatforms {/* #getplatforms */}
The `getPlatforms` method can be used to determine which platforms your app is currently running on.
@@ -24,7 +24,7 @@ getPlatforms(); // returns ["iphone", "ios", "mobile", "mobileweb"] from an iPho
Depending on what device you are on, `getPlatforms` can return multiple values. Each possible value is a hierarchy of platforms. For example, on an iPhone, it would return mobile, ios, and iphone.
-## Platforms
+## Platforms {/* #platforms */}
Below is a table listing all the possible platform values along with corresponding descriptions.
@@ -45,7 +45,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.
diff --git a/docs/react/pwa.mdx b/docs/react/pwa.mdx
index d7d74f57fd..9ffbcfe2af 100644
--- a/docs/react/pwa.mdx
+++ b/docs/react/pwa.mdx
@@ -11,7 +11,7 @@ sidebar_label: Progressive Web Apps
/>
-## Making your React app a PWA with Vite
+## Making your React app a PWA with Vite {/* #making-your-react-app-a-pwa-with-vite */}
The two main requirements of a PWA are a [Service Worker](https://developers.google.com/web/fundamentals/primers/service-workers/) and a [Web Application Manifest](https://developers.google.com/web/fundamentals/web-app-manifest/). While it's possible to add both of these to an app manually, we recommend using the [Vite PWA Plugin](https://vite-pwa-org.netlify.app/) instead.
@@ -39,7 +39,7 @@ For more information on configuring the Vite PWA Plugin, refer to the [Vite PWA
Refer to the [Vite PWA "Deploy" Guide](https://vite-pwa-org.netlify.app/deployment/) for information on how to deploy your PWA.
-## Making your React app a PWA with Create React App
+## Making your React app a PWA with Create React App {/* #making-your-react-app-a-pwa-with-create-react-app */}
:::note
@@ -85,15 +85,15 @@ Features like Service Workers and many JavaScript APIs (such as geolocation) req
:::
-### Service Worker configuration
+### Service Worker configuration {/* #service-worker-configuration */}
By default, CRA/React Scripts come with a preconfigured Service Worker setup based on [Workbox's Webpack plugin](https://developers.google.com/web/tools/workbox/modules/workbox-webpack-plugin). This utilizes a cache-first strategy, meaning that your app will load from a cache, even if the network returns a newer version of the app.
Because of the nature of CRA/React Scripts, the configuration for this is internal to React Scripts, meaning that it cannot be customized without ejecting from React Scripts. Currently, the Ionic CLI does not support an ejected React App, so if this action is taken, you'll need to use npm/yarn scripts instead of the Ionic CLI.
-### 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/react/quickstart.mdx b/docs/react/quickstart.mdx
index 3bd67d309c..972203a096 100644
--- a/docs/react/quickstart.mdx
+++ b/docs/react/quickstart.mdx
@@ -18,7 +18,7 @@ Welcome! This guide will walk you through the basics of Ionic React development.
If you're looking for a high-level overview of what Ionic React is and how it fits into the React ecosystem, refer to the [Ionic React 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):
@@ -51,7 +51,7 @@ After running `ionic serve`, your project will open in the browser.
-## Explore the Project Structure
+## Explore the Project Structure {/* #explore-the-project-structure */}
Your new app's directory will look like this:
@@ -75,7 +75,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.tsx`:
@@ -105,7 +105,7 @@ export default App;
This sets up the root of your application, using Ionic's `IonApp` and `IonReactRouter` components. The `IonRouterOutlet` is where your pages will be displayed.
-## View Routes
+## View Routes {/* #view-routes */}
Routes are defined within the `IonRouterOutlet` in `App.tsx`:
@@ -118,7 +118,7 @@ Routes are defined within the `IonRouterOutlet` in `App.tsx`:
When you visit the root URL (`/`), the `Home` component will be loaded.
-## View the Home Page
+## View the Home Page {/* #view-the-home-page */}
The Home page component, defined in `Home.tsx`, imports the Ionic components and defines the page template:
@@ -158,7 +158,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, import and add a [Button](/api/button.mdx) at the end of the `IonContent` in `Home.tsx`:
@@ -186,7 +186,7 @@ const Home: React.FC = () => {
export default Home;
```
-## Add a New Page
+## Add a New Page {/* #add-a-new-page */}
Create a new page at `New.tsx`:
@@ -226,7 +226,7 @@ When creating your own pages, always use `IonPage` as the root component. This i
:::
-## Navigate to the New Page
+## Navigate to the New Page {/* #navigate-to-the-new-page */}
To navigate to the new page, create a route for it by first importing it at the top of `App.tsx` after the `Home` import:
@@ -256,7 +256,7 @@ Navigating can also be performed programmatically using the `useIonRouter` hook.
:::
-## Add Icons to the New Page
+## Add Icons to the New Page {/* #add-icons-to-the-new-page */}
Ionic React comes with [Ionicons](https://ionic.io/ionicons/) pre-installed. You can use any icon by setting the `icon` property of the `IonIcon` component.
@@ -278,7 +278,7 @@ Note that we are passing the imported SVG reference, **not** the icon name as a
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.
@@ -331,7 +331,7 @@ This pattern is necessary because React refs store the component instance in the
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):
@@ -350,7 +350,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 React app, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out:
diff --git a/docs/react/slides.mdx b/docs/react/slides.mdx
index e5dffb8625..d6625d33c4 100644
--- a/docs/react/slides.mdx
+++ b/docs/react/slides.mdx
@@ -26,7 +26,7 @@ Using Swiper's React component is **not** required to use Swiper.js with Ionic F
:::
-## Getting Started
+## Getting Started {/* #getting-started */}
First, update to the latest version of Ionic:
@@ -46,7 +46,7 @@ Developers using Create React App must use `react-scripts` v5.0.0+ with the late
:::
-## Swiping with Style
+## Swiping with Style {/* #swiping-with-style */}
Next, we need to import the base Swiper styles. We are also going to import the styles that Ionic provides which will let us customize the Swiper styles using the same CSS Variables that we used with `IonSlides`.
@@ -74,7 +74,7 @@ Importing `@ionic/react/css/ionic-swiper.css` is **not** required to use Swiper.
:::
-### Updating Selectors
+### Updating Selectors {/* #updating-selectors */}
Previously, we were able to target `ion-slides` and `ion-slide` to apply any custom styling. The contents of those style blocks remain the same, but we need to update the selectors. Below is a list of selector changes when going from `ion-slides` to Swiper React:
@@ -83,7 +83,7 @@ Previously, we were able to target `ion-slides` and `ion-slide` to apply any cus
| `ion-slides` | `.swiper` |
| `ion-slide` | `.swiper-slide` |
-### Pre-processors (optional)
+### Pre-processors (optional) {/* #pre-processors-optional */}
For developers using SCSS or Less styles, Swiper also provides imports for those files.
@@ -123,7 +123,7 @@ const Home: React.FC = () => {
export default Home;
```
-## Using Components
+## Using Components {/* #using-components */}
Swiper exports two components: `Swiper` and `SwiperSlide`. The `Swiper` component is the equivalent of `IonSlides`, and `SwiperSlide` is the equivalent of `IonSlide`.
@@ -153,7 +153,7 @@ const Home: React.FC = () => {
export default Home;
```
-## Using Modules
+## Using Modules {/* #using-modules */}
By default, Swiper for React does not import any additional modules. To use modules such as Navigation or Pagination, you need to import them first.
@@ -268,7 +268,7 @@ Refer to [Swiper's React usage documentation](https://swiperjs.com/react#usage)
:::
-## The IonicSlides Module
+## The IonicSlides Module {/* #the-ionicslides-module */}
With `IonSlides`, 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.
@@ -319,7 +319,7 @@ The `IonicSlides` module must be the last module in the array. This will let it
:::
-## Properties
+## Properties {/* #properties */}
Swiper options are provided as props directly on the `` component rather than via the `options` object in `IonSlides`.
@@ -371,7 +371,7 @@ All properties available in Swiper React can be found in the [Swiper React props
:::
-## Events
+## Events {/* #events */}
Since the `Swiper` component is not provided by Ionic Framework, event names will not have an `onIonSlide` prefix to them.
@@ -430,7 +430,7 @@ All events available in Swiper can be found in the [Swiper API events documentat
:::
-## Methods
+## Methods {/* #methods */}
Most methods have been removed in favor of accessing the `Swiper` props directly.
@@ -473,7 +473,7 @@ Below is a full list of method changes when going from `IonSlides` to Swiper Rea
| `startAutoplay()` | Use the `autoplay` property instead. |
| `stopAutoplay()` | Use the `autoplay` property instead. |
-## Effects
+## Effects {/* #effects */}
If you are using effects such as Cube or Fade, you can install them just like we did with the other modules. In this example, we will use the fade effect. To start, we will import `EffectFade` from `swiper` and provide it in the `modules` array:
@@ -564,21 +564,21 @@ For more information on effects in Swiper, please refer to the [Swiper React eff
:::
-## 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 React Introduction](https://swiperjs.com/react) 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/react/storage.mdx b/docs/react/storage.mdx
index 81cb1632d5..69511d121f 100644
--- a/docs/react/storage.mdx
+++ b/docs/react/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-react/blob/main/demos/sqlcipher-kv-pair/src/utils/mobile-kv-store.ts)
- [Web Service](https://github.com/ionic-enterprise/tutorials-and-demos-react/blob/main/demos/sqlcipher-kv-pair/src/utils/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/react/testing/introduction.mdx b/docs/react/testing/introduction.mdx
index 44d6fe6a74..25698b2956 100644
--- a/docs/react/testing/introduction.mdx
+++ b/docs/react/testing/introduction.mdx
@@ -8,11 +8,11 @@ description: Learn how to test an Ionic React application. This document provide
This document provides an overview of how to test an application built with `@ionic/react`. It covers the basics of testing with React, as well as the specific tools and libraries developers can use to test their applications.
-## Introduction
+## Introduction {/* #introduction */}
Testing is an important part of the development process, and it helps to ensure that an application is working as intended. In `@ionic/react`, testing is done using a combination of tools and libraries, including Jest or Vitest, React Testing Library, Playwright or Cypress.
-## Types of Tests
+## Types of Tests {/* #types-of-tests */}
There are two types of tests that can be written:
diff --git a/docs/react/testing/unit-testing/best-practices.mdx b/docs/react/testing/unit-testing/best-practices.mdx
index 6af22f45d4..1a705eb4db 100644
--- a/docs/react/testing/unit-testing/best-practices.mdx
+++ b/docs/react/testing/unit-testing/best-practices.mdx
@@ -4,7 +4,7 @@ sidebar_label: Best Practices
# Best Practices
-## IonApp is required for test templates
+## IonApp is required for test templates {/* #ionapp-is-required-for-test-templates */}
In your test template when rendering with React Testing Library, you must wrap your component with an `IonApp` component. This is required for the component to be rendered correctly.
@@ -24,7 +24,7 @@ test('example', () => {
});
```
-## Use `user-event` for user interactions
+## Use `user-event` for user interactions {/* #use-user-event-for-user-interactions */}
React Testing Library recommends using the `user-event` library for simulating user interactions. This library provides a more realistic simulation of user interactions than the `fireEvent` function provided by React Testing Library.
@@ -50,7 +50,7 @@ test('example', async () => {
For more information on `user-event`, refer to the [user-event documentation](https://testing-library.com/docs/user-event/intro/).
-## Waiting for Components
+## Waiting for Components {/* #waiting-for-components */}
When you need to wait for an Ionic component to render before asserting against its DOM, use the `componentOnReady` helper exported from `@ionic/core`. Do not call `el.componentOnReady()` directly. `@ionic/react` uses Stencil's custom elements build, where that method does not exist on the element. The helper waits one animation frame instead, giving the component's inner contents a chance to render.
diff --git a/docs/react/testing/unit-testing/examples.mdx b/docs/react/testing/unit-testing/examples.mdx
index 39275eef66..1b5a84ac10 100644
--- a/docs/react/testing/unit-testing/examples.mdx
+++ b/docs/react/testing/unit-testing/examples.mdx
@@ -6,11 +6,11 @@ description: Learn how to test an Ionic React application. This document provide
# Examples
-## Testing a modal presented from a trigger
+## Testing a modal presented from a trigger {/* #testing-a-modal-presented-from-a-trigger */}
This example shows how to test a modal that is presented from a trigger. The modal is presented when the user clicks a button.
-### Example component
+### Example component {/* #example-component */}
```tsx title="src/Example.tsx"
import { IonButton, IonModal } from '@ionic/react';
@@ -25,7 +25,7 @@ export default function Example() {
}
```
-### Testing the modal
+### Testing the modal {/* #testing-the-modal */}
```tsx title="src/Example.test.tsx"
import { IonApp } from '@ionic/react';
@@ -49,11 +49,11 @@ test('button presents a modal when clicked', async () => {
});
```
-## Testing a modal presented from useIonModal
+## Testing a modal presented from useIonModal {/* #testing-a-modal-presented-from-useionmodal */}
This example shows how to test a modal that is presented using the `useIonModal` hook. The modal is presented when the user clicks a button.
-### Example component
+### Example component {/* #example-component-1 */}
```tsx title="src/Example.tsx"
import { IonContent, useIonModal, IonHeader, IonToolbar, IonTitle, IonButton, IonPage } from '@ionic/react';
@@ -87,7 +87,7 @@ const Example: React.FC = () => {
export default Example;
```
-### Testing the modal
+### Testing the modal {/* #testing-the-modal-1 */}
```tsx title="src/Example.test.tsx"
import { IonApp } from '@ionic/react';
diff --git a/docs/react/testing/unit-testing/setup.mdx b/docs/react/testing/unit-testing/setup.mdx
index 0e4cf3d1ed..aae81f5703 100644
--- a/docs/react/testing/unit-testing/setup.mdx
+++ b/docs/react/testing/unit-testing/setup.mdx
@@ -8,7 +8,7 @@ description: Learn how to set up unit tests for an Ionic React application.
Ionic requires a few additional steps to set up unit tests. If you are using an Ionic starter project, these steps have already been completed for you.
-### Install React Testing Library
+### Install React Testing Library {/* #install-react-testing-library */}
React Testing Library is a set of utilities that make it easier to test React components. It's used to interact with components and test their behavior.
@@ -16,7 +16,7 @@ React Testing Library is a set of utilities that make it easier to test React co
npm install --save-dev @testing-library/react @testing-library/jest-dom @testing-library/user-event
```
-### Initialize Ionic React
+### Initialize Ionic React {/* #initialize-ionic-react */}
Ionic React requires the `setupIonicReact` function to be called before any tests are run. Failing to do so will result in mode-based classes and platform behaviors not being applied to your components.
diff --git a/docs/react/utility-functions.mdx b/docs/react/utility-functions.mdx
index 905c470606..15e7037413 100644
--- a/docs/react/utility-functions.mdx
+++ b/docs/react/utility-functions.mdx
@@ -13,17 +13,17 @@ sidebar_label: Utility Functions
Ionic React provides utility functions for common tasks like programmatic navigation and controlling page transitions.
-## Router
+## Router {/* #router */}
-### Functions
+### Functions {/* #functions */}
-#### useIonRouter
+#### useIonRouter {/* #useionrouter */}
▸ **useIonRouter**(): [`UseIonRouterResult`](#useionrouterresult)
Returns the Ionic router instance, which provides methods for programmatic navigation with control over page transitions. Use this hook instead of React Router's `useNavigate` when you need to customize the transition animation or use Ionic-aware back navigation.
-##### Customizing Page Transitions
+##### Customizing Page Transitions {/* #customizing-page-transitions */}
```tsx
import { useIonRouter } from '@ionic/react';
@@ -44,7 +44,7 @@ const MyComponent: React.FC = () => {
};
```
-##### Back Navigation
+##### Back Navigation {/* #back-navigation */}
The `goBack()` method navigates within the current Ionic navigation stack, unlike React Router's `navigate(-1)` which follows the browser's linear history.
@@ -64,7 +64,7 @@ const MyComponent: React.FC = () => {
};
```
-##### canGoBack
+##### canGoBack {/* #cangoback */}
Use `canGoBack()` to check whether there are additional routes in the Ionic router's history. This is useful when deciding whether to show a back button or handle the hardware back button on Android.
@@ -81,7 +81,7 @@ const MyComponent: React.FC = () => {
};
```
-##### navigateRoot
+##### navigateRoot {/* #navigateroot */}
Use `navigateRoot()` to navigate to a new root pathname, clearing the navigation history and unmounting all previous views. After navigation, `canGoBack()` will return `false`. This is useful for navigating to a new root after login or logout.
@@ -101,9 +101,9 @@ const MyComponent: React.FC = () => {
Review the [React Navigation Documentation](./navigation.mdx) for more navigation examples.
-### Interfaces
+### Interfaces {/* #interfaces */}
-#### UseIonRouterResult
+#### UseIonRouterResult {/* #useionrouterresult */}
```typescript
import { AnimationBuilder, RouterDirection, RouteAction, RouterOptions, RouteInfo } from '@ionic/react';
diff --git a/docs/react/virtual-scroll.mdx b/docs/react/virtual-scroll.mdx
index 355d58a06a..c9816a72a6 100644
--- a/docs/react/virtual-scroll.mdx
+++ b/docs/react/virtual-scroll.mdx
@@ -8,7 +8,7 @@
One virtual scrolling solution to consider for your Ionic React app is [Virtuoso](https://virtuoso.dev/). This guide will go over how to install `Virtuoso` into your Ionic React application and use it with other Ionic components.
-## Installation
+## Installation {/* #installation */}
To setup the virtual scroller, first install `react-virtuoso`:
@@ -16,7 +16,7 @@ To setup the virtual scroller, first install `react-virtuoso`:
npm install react-virtuoso
```
-## Usage
+## Usage {/* #usage */}
There are a few components that Virtuoso includes, but this example will use the `Virtuoso` component. This component should be added inside of your `IonContent` component:
@@ -57,7 +57,7 @@ From there, we can use the `itemContent` property to pass a function that will b
An important thing to note here is the `div` that wraps our `IonItem` component. When lazy loading Ionic components, there may be a few frames where the component is loaded but the styles have not loaded in. When this happens, the component's dimension will be `0`, and Virtuoso may throw an error. This is because Virtuoso needs distinct positions for each item it renders, and it cannot determine that when a component's dimension is `0`.
-## 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.
@@ -71,6 +71,6 @@ For example:
```
-## Further Reading
+## Further Reading {/* #further-reading */}
This guide only covers a small portion of what `Virtuoso` is capable of. For more details, please refer to the [Virtuoso documentation](https://virtuoso.dev/).
diff --git a/docs/react/your-first-app.mdx b/docs/react/your-first-app.mdx
index cd95427ae0..fa052a476d 100644
--- a/docs/react/your-first-app.mdx
+++ b/docs/react/your-first-app.mdx
@@ -24,7 +24,7 @@ Here’s the finished app running on all 3 platforms:
allowFullScreen
>
-## 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.
@@ -36,7 +36,7 @@ Highlights include:
Find the [complete app code](https://github.com/ionic-team/tutorial-photo-gallery-react) 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:
@@ -46,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:
@@ -68,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 React app that uses the "Tabs" starter template and adds Capacitor for native functionality:
@@ -90,7 +90,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).
@@ -123,7 +123,7 @@ root.render(
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:
@@ -133,7 +133,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/react/your-first-app/2-taking-photos.mdx b/docs/react/your-first-app/2-taking-photos.mdx
index 198614407d..b65238b780 100644
--- a/docs/react/your-first-app/2-taking-photos.mdx
+++ b/docs/react/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 Gallery Hook
+## Photo Gallery Hook {/* #photo-gallery-hook */}
We will create a [custom React hook](https://react.dev/learn/reusing-logic-with-custom-hooks#extracting-your-own-custom-hook-from-a-component) to manage the photos for the gallery.
@@ -91,7 +91,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 `usePhotoGallery.ts` file, immediately after the `usePhotoGallery()` method definition.
diff --git a/docs/react/your-first-app/3-saving-photos.mdx b/docs/react/your-first-app/3-saving-photos.mdx
index 258477749e..0a88055487 100644
--- a/docs/react/your-first-app/3-saving-photos.mdx
+++ b/docs/react/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 `usePhotoGallery()` method in `usePhotoGallery.ts`.
diff --git a/docs/react/your-first-app/4-loading-photos.mdx b/docs/react/your-first-app/4-loading-photos.mdx
index 579bbe051e..6bd1465a38 100644
--- a/docs/react/your-first-app/4-loading-photos.mdx
+++ b/docs/react/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 `usePhotoGallery.ts` and begin by defining a constant variable that will act as the key for the store.
diff --git a/docs/react/your-first-app/5-adding-mobile.mdx b/docs/react/your-first-app/5-adding-mobile.mdx
index 302988e4e3..c0e285d68f 100644
--- a/docs/react/your-first-app/5-adding-mobile.mdx
+++ b/docs/react/your-first-app/5-adding-mobile.mdx
@@ -13,7 +13,7 @@ sidebar_label: Adding Mobile
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.
@@ -33,7 +33,7 @@ import { Capacitor } from '@capacitor/core';
// ...existing code...
```
-## 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/react/your-first-app/6-deploying-mobile.mdx b/docs/react/your-first-app/6-deploying-mobile.mdx
index 64b4888315..ba2d1181c0 100644
--- a/docs/react/your-first-app/6-deploying-mobile.mdx
+++ b/docs/react/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
-## 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/react/your-first-app/7-live-reload.mdx b/docs/react/your-first-app/7-live-reload.mdx
index 25665f016d..f93cf02adb 100644
--- a/docs/react/your-first-app/7-live-reload.mdx
+++ b/docs/react/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/react/your-first-app/8-distribute.mdx b/docs/react/your-first-app/8-distribute.mdx
index e1c6a8ac23..157c9764b5 100644
--- a/docs/react/your-first-app/8-distribute.mdx
+++ b/docs/react/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/reference/browser-support.mdx b/docs/reference/browser-support.mdx
index 0776df2a8f..5f0c5d38db 100644
--- a/docs/reference/browser-support.mdx
+++ b/docs/reference/browser-support.mdx
@@ -12,7 +12,7 @@ title: Browser Support
Ionic's earliest goal was to make it easy to develop mobile apps using web technologies like HTML, CSS, and JavaScript. Because of this foundation in web technologies, Ionic can run anywhere the web runs — iOS, Android, browsers, PWAs, and more.
-## Mobile Platforms
+## Mobile Platforms {/* #mobile-platforms */}
In pursuit of [adaptive styling](../core-concepts/fundamentals.mdx#adaptive-styling), Ionic fully supports and is well tested on the mobile platforms listed below:
@@ -31,13 +31,13 @@ Check the [latest Android stats](https://developer.android.com/about/dashboards/
:::
-### A Note on Android Support
+### A Note on Android Support {/* #a-note-on-android-support */}
Starting with Android 5.0, the webview was moved to a separate application that can be updated independently of Android. This means that most Android 5.0+ devices are going to be running a modern version of Chromium. However, there are a still a subset of Android devices that are unable to have their webview updated. These webviews are typically stuck at the version that was available when the device initially shipped.
To figure out what version of the webview a device is running, log `window.navigator.userAgent` to the console when inspecting the application using Chrome Dev Tools.
-## Browsers
+## Browsers {/* #browsers */}
Ionic supports the following browsers:
diff --git a/docs/reference/support.mdx b/docs/reference/support.mdx
index 409485fb54..405c5ebe07 100644
--- a/docs/reference/support.mdx
+++ b/docs/reference/support.mdx
@@ -10,11 +10,11 @@ title: Support Policy
/>
-## Community Maintenance
+## Community Maintenance {/* #community-maintenance */}
The Ionic Framework has been 100% open source (MIT) since the very beginning, and always will be. Developers can ensure Ionic is the right choice for their cross-platform apps through Ionic’s community maintenance strategy. The Ionic team regularly ships new releases, bug fixes, and is very welcoming to community pull requests.
-## Framework Maintenance and Support Status
+## Framework Maintenance and Support Status {/* #framework-maintenance-and-support-status */}
Given the reality of time and resource constraints as well as the desire to keep innovating in the frontend development space, over time it becomes necessary for the Ionic team to shift focus to newer versions of the Framework. However, Ionic will do everything it can to make the transition to newer versions as smooth as possible. The Ionic team recommends updating to the newest version of the Ionic Framework for the latest features, improvements and stability updates.
@@ -35,13 +35,13 @@ The current status of each Ionic Framework version is:
- **Maintenance**: Only critical bug and security fixes. No major feature improvements.
- **Extended Support**: For teams and organizations that require additional long term maintenance support, Ionic has extended support options available.
-## Compatibility Recommendations
+## Compatibility Recommendations {/* #compatibility-recommendations */}
The Ionic team has compiled a set of recommendations for using the Ionic Framework in conjunction with other contextually-relevant software. This is not meant to be a comprehensive list, but covers many common compatibility questions. The Ionic team strongly recommends reviewing your project dependencies once each quarter to keep track of new releases, features and bug fixes.
-### Core Dependencies
+### Core Dependencies {/* #core-dependencies */}
-#### Ionic Angular
+#### Ionic Angular {/* #ionic-angular */}
| Framework | Minimum Angular Version | Maximum Angular Version | TypeScript |
| :-------: | :---------------------: | :---------------------: | :--------: |
@@ -67,7 +67,7 @@ Angular's support policy for iOS is the two most recent major versions. This mea
Note that later versions of Ionic do not support iOS 13; refer to the [mobile support table](./browser-support.mdx#mobile-platforms).
-#### Ionic React
+#### Ionic React {/* #ionic-react */}
| Framework | Required React Version | TypeScript |
| :-------: | :--------------------: | :--------: |
@@ -78,7 +78,7 @@ Note that later versions of Ionic do not support iOS 13; refer to the [mobile su
| v5 | v16.8+ | 3.7+ |
| v4 | v16.8+ | 3.7+ |
-#### Ionic Vue
+#### Ionic Vue {/* #ionic-vue */}
| Framework | Required Vue Version | TypeScript |
| :-------: | :------------------: | :--------: |
@@ -88,7 +88,7 @@ Note that later versions of Ionic do not support iOS 13; refer to the [mobile su
| v6 | v3.0.6+ | 3.9+ |
| v5 | v3.0+ | 3.9+ |
-#### Ionic Vue Router
+#### Ionic Vue Router {/* #ionic-vue-router */}
| Framework | Required Vue Router Version |
| :-------: | :-------------------------: |
@@ -98,7 +98,7 @@ Note that later versions of Ionic do not support iOS 13; refer to the [mobile su
| v6 | v4+ |
| v5 | v4+ |
-### Native Bridges
+### Native Bridges {/* #native-bridges */}
| Framework | Cordova | Capacitor |
| :------------: | :----------------------------------: | :----------------------: |
@@ -115,7 +115,7 @@ Note that later versions of Ionic do not support iOS 13; refer to the [mobile su
- As iOS and Android (and related tools) are updated, you can expect more updates for Cordova and Capacitor, so it is recommended to stay on the latest version(s) of Cordova and Capacitor.
- Starting with Ionic v9, Capacitor 7 is the minimum officially supported version. Earlier versions of Ionic ran on Capacitor 2 and later.
-### Ionic Platform & Products
+### Ionic Platform & Products {/* #ionic-platform--products */}
| Framework | Appflow | Ionic Native Premier Plugins\* |
| :----------: | :-------------------: | :-----------------------------------------------: |
@@ -129,7 +129,7 @@ Note that later versions of Ionic do not support iOS 13; refer to the [mobile su
- For Capacitor projects, follow the [Capacitor installation guide for Cordova plugins](https://capacitorjs.com/docs/cordova/using-cordova-plugins)
- If you need to use an Enterprise plugin with an Ionic 3 project, please [contact us](https://ionic.zendesk.com/hc)
-### Ionic Platform & Products (Cont.)
+### Ionic Platform & Products (Cont.) {/* #ionic-platform--products-cont */}
| Framework | Ionic Studio | Ionic Native Community Plugins\* |
| :----------: | :---------------------: | :------------------------------: |
diff --git a/docs/reference/versioning.mdx b/docs/reference/versioning.mdx
index 51ee30f725..0dc2631609 100644
--- a/docs/reference/versioning.mdx
+++ b/docs/reference/versioning.mdx
@@ -2,21 +2,21 @@
Ionic Framework follows the [Semantic Versioning (SemVer)](https://semver.org/) convention: major.minor.patch. Incompatible API changes increment the major version, adding backwards-compatible functionality increments the minor version, and backwards-compatible bug fixes increment the patch version.
-## Release Schedule
+## Release Schedule {/* #release-schedule */}
-### Major Release
+### Major Release {/* #major-release */}
A major release will be published when there is a breaking change introduced in the API. Major releases will occur roughly every **6 months** and may contain breaking changes. Several release candidates will be published prior to a major release in order to get feedback before the final release. An outline of what is changing and why will be included with the release candidates.
-### Minor Release
+### Minor Release {/* #minor-release */}
A minor release will be published when a new feature is added or API changes that are non-breaking are introduced. We will heavily test any changes so that we are confident with the release, but with new code comes the potential for new issues. We are scheduled to release a minor version **every 4 weeks**, if any features or API changes were made.
-### Patch Release
+### Patch Release {/* #patch-release */}
A patch release will be published when bug fixes were included, but the API has not changed and no breaking changes were introduced. We are scheduled to release a new patch version **every week**, but there may be times where we need to release sooner or later than scheduled. To ensure patch releases can fix existing code without introducing new issues from the new features, patch releases will always be published prior to a minor release.
-## Changelog
+## Changelog {/* #changelog */}
For a list of all notable changes to Ionic please refer to the [changelog](https://github.com/ionic-team/ionic/blob/master/CHANGELOG.md). This contains an ordered
list of all bug fixes and new features under each release.
diff --git a/docs/techniques/security.mdx b/docs/techniques/security.mdx
index 9aebc97ca9..b7d5c801bf 100644
--- a/docs/techniques/security.mdx
+++ b/docs/techniques/security.mdx
@@ -13,7 +13,7 @@ title: Security
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
-## Sanitizing User Input
+## Sanitizing User Input {/* #sanitizing-user-input */}
For components such as `ion-alert` developers can allow for custom or user-provided content. This content can be plain text or HTML and should be considered untrusted. As with any untrusted input, it is important to sanitize it before doing anything else with it. In particular, using things like `innerHTML` without sanitization provides an attack vector for bad actors to input malicious content and potentially launch a [Cross Site Scripting attack (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting).
@@ -21,7 +21,7 @@ Ionic comes built in with a basic sanitization implementation for the components
For developers who are not using a framework, or for developers whose framework does not provide the sanitization methods they need, we recommend using [sanitize-html](https://www.npmjs.com/package/sanitize-html). This package provides a simple HTML sanitizer that allows the developer to specify the exact tags and attributes that they want to allow in their application.
-### Angular
+### Angular {/* #angular */}
Angular comes built in with the `DomSanitizer` class. This helps prevent XSS issues by ensuring that values are safe to be used in the DOM. By default, Angular will mark any values it deems unsafe. For example, the following link would be marked as unsafe by Angular because it would attempt to execute some JavaScript.
@@ -35,7 +35,7 @@ public myUrl: string = 'javascript:alert("oh no!")';
To learn more about the built-in protections that Angular provides, refer to the [Angular Security Guide](https://angular.io/guide/security).
-### React
+### React {/* #react */}
React DOM escapes values embedded in JSX before rendering them by converting them to strings. For example, the following would be safe as `name` is converted to a string before being rendered:
@@ -53,17 +53,17 @@ const element = Click Me!;
If the developer needs to achieve more comprehensive sanitization, they can use the [sanitize-html](https://www.npmjs.com/package/sanitize-html) package.
-### Vue
+### Vue {/* #vue */}
Vue does not provide any type of sanitizing methods built in. It is recommended that developers use a package such as [sanitize-html](https://www.npmjs.com/package/sanitize-html).
To learn more about the security recommendations for binding to directives such as `v-html`, refer to the [Vue Syntax Guide](https://vuejs.org/v2/guide/syntax.html#Raw-HTML).
-## Enabling Custom HTML Parsing via `innerHTML`
+## Enabling Custom HTML Parsing via `innerHTML` {/* #enabling-custom-html-parsing-via-innerhtml */}
`ion-alert`, `ion-infinite-scroll-content`, `ion-loading`, `ion-refresher-content`, `ion-select-option`, and `ion-toast` can accept custom HTML as strings for certain properties. These strings are added to the DOM using `innerHTML` and must be properly sanitized by the developer. This behavior is disabled by default which means values passed to the affected components will always be interpreted as plaintext. Developers can enable this custom HTML behavior by setting `innerHTMLTemplatesEnabled: true` in the [IonicConfig](../developing/config.mdx#ionicconfig).
-## Ejecting from the built-in sanitizer
+## Ejecting from the built-in sanitizer {/* #ejecting-from-the-built-in-sanitizer */}
For developers who wish to add complex HTML to components such as `ion-toast`, they will need to eject from the sanitizer that is built into Ionic Framework. Developers can either disable the sanitizer across their entire app or bypass it on a case-by-case basis.
@@ -73,11 +73,11 @@ Bypassing sanitization functionality can make your application vulnerable to [XS
:::
-### Disabling the sanitizer via config
+### Disabling the sanitizer via config {/* #disabling-the-sanitizer-via-config */}
Ionic Framework provides an application config option called `sanitizerEnabled` that is set to `true` by default. Set this value to `false` to globally disable Ionic Framework's built in sanitizer. Please note that this does not disable any sanitizing functionality provided by other frameworks such as Angular.
-### Bypassing the sanitizer on a case-by-case basis
+### Bypassing the sanitizer on a case-by-case basis {/* #bypassing-the-sanitizer-on-a-case-by-case-basis */}
Developers can also choose to eject from the sanitizer in certain scenarios. Ionic Framework provides the `IonicSafeString` class that allows developers to do just that.
@@ -91,7 +91,7 @@ Refer to [Enabling Custom HTML Parsing](#enabling-custom-html-parsing-via-innerh
:::
-#### Usage
+#### Usage {/* #usage */}
````mdx-code-block
{
````
-## Content Security Policies (CSP)
+## Content Security Policies (CSP) {/* #content-security-policies-csp */}
A [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) is a security mechanism that helps protect web applications against certain types of attacks, such as cross-site scripting (XSS) and data injection. It is implemented through an HTTP header that instructs the browser on which sources of content, such as scripts, stylesheets, and images, are allowed to be loaded and executed on a web page.
The main purpose of a CSP is to mitigate the risks associated with code injection attacks. By defining a policy, web developers can specify from which domains or sources the browser should allow the loading and execution of various types of content. This effectively limits the potential damage that can be caused by malicious scripts or unauthorized content.
-### Enabling CSPs
+### Enabling CSPs {/* #enabling-csps */}
Developers can assign a CSP to their application by setting a meta tag with the policy details and the expected nonce value on script and style tags.
@@ -203,7 +203,7 @@ Developers can assign a CSP to their application by setting a meta tag with the
/>
```
-### Ionic and CSP
+### Ionic and CSP {/* #ionic-and-csp */}
Ionic Framework provides a function to help developers set the nonce value used when constructing the web component stylesheets. This function should be called before any Ionic components are loaded. This is required to pass the nonce value to the web components so that they can be used in a CSP environment.
@@ -221,7 +221,7 @@ In Angular this can be called in the `main.ts` file, before the application is b
For more information on how to use CSPs with Stencil web components, refer to the [Stencil documentation](https://stenciljs.com/docs/csp-nonce).
-### Angular
+### Angular {/* #angular-1 */}
Starting in Angular 16, Angular provides two options for setting the nonce value.
diff --git a/docs/theming/advanced.mdx b/docs/theming/advanced.mdx
index 935a77e05b..26570ed441 100644
--- a/docs/theming/advanced.mdx
+++ b/docs/theming/advanced.mdx
@@ -15,7 +15,7 @@ import CodeColor from '@components/page/theming/CodeColor';
CSS-based theming enables apps to customize the colors quickly by loading a CSS file or changing a few CSS property values.
-## `theme-color` Meta
+## `theme-color` Meta {/* #theme-color-meta */}
The `theme-color` value for a meta tag indicates a color that browsers can use to customize the display of a page or of the surrounding interface. This kind of meta tag can also accept media queries which allow developers to set the theme color for both light and dark modes.
@@ -52,11 +52,11 @@ Browsers will prefer the `theme-color` meta over `theme` in `manifest.json` if b
For more information, refer to the [MDN theme-color documentation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta/name/theme-color).
-## Global Variables
+## Global Variables {/* #global-variables */}
While the application and stepped variables in the themes section are useful for changing the colors of an application, often times there is a need for variables that are used in multiple components. The following variables are shared across components to change global padding settings and more.
-### Application Variables
+### Application Variables {/* #application-variables */}
| Name | Description |
| --------------------------- | ---------------------------------------------------------------------------------------------------- |
@@ -70,7 +70,7 @@ While the application and stepped variables in the themes section are useful for
| `--ion-padding` | Adjust the padding of the [Padding attributes](../layout/css-utilities.mdx#padding) |
| `--ion-placeholder-opacity` | Adjust the opacity of the placeholders used in the input, textarea, searchbar, and select components |
-### Grid Variables
+### Grid Variables {/* #grid-variables */}
| Name | Description |
| ------------------------------ | ---------------------------------------------- |
@@ -86,9 +86,9 @@ While the application and stepped variables in the themes section are useful for
| `--ion-grid-column-padding-lg` | Padding of the grid columns for lg breakpoints |
| `--ion-grid-column-padding-xl` | Padding of the grid columns for xl breakpoints |
-## Known Limitations with Variables
+## Known Limitations with Variables {/* #known-limitations-with-variables */}
-### The Alpha Problem
+### The Alpha Problem {/* #the-alpha-problem */}
There is not yet full [browser support](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Browser_compatibility) for alpha use of a hex color. The [`rgba()`]() function only accepts a value in `R, G, B, A` (Red, Green, Blue, Alpha) format. The following code shows examples of correct and incorrect values passed to `rgba()`.
@@ -137,7 +137,7 @@ body {
}
```
-### Variables in Media Queries
+### Variables in Media Queries {/* #variables-in-media-queries */}
CSS variables in [media queries](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries) are not currently supported, but there are open drafts to add [custom media queries](https://drafts.csswg.org/mediaqueries-5/#custom-mq) and [custom environment variables](https://drafts.csswg.org/css-env-1/) that would solve this problem! However, with the current state of support, the following will **not** work:
@@ -151,7 +151,7 @@ CSS variables in [media queries](https://developer.mozilla.org/en-US/docs/Web/CS
}
```
-### Modifying CSS Color Variables
+### Modifying CSS Color Variables {/* #modifying-css-color-variables */}
While it is possible to easily alter a color in Sass using its built-in functions, it is currently not as easy to modify colors set in CSS Variables. This can be accomplished in CSS by splitting the [RGB](https://developer.mozilla.org/en-US/docs/Glossary/RGB) or [HSL](https://en.wikipedia.org/wiki/HSL_and_HSV) channels and modifying each value, but it is complex and has missing functionality.
@@ -186,7 +186,7 @@ This is normally not a problem, but when an application needs to have dynamic th
There are drafts and issues discussing [color modification proposals](https://github.com/w3c/csswg-drafts/issues/3187) that would make this possible.
-## Safe Area Padding
+## Safe Area Padding {/* #safe-area-padding */}
The safe area of a display is the section that is not covered by the device's notch, status bar, or other elements that are part of the device's UI and not the app's. The dimensions of the safe area are different across devices and orientations (portrait or landscape).
diff --git a/docs/theming/basics.mdx b/docs/theming/basics.mdx
index b330a7383e..9d7b01ffad 100644
--- a/docs/theming/basics.mdx
+++ b/docs/theming/basics.mdx
@@ -15,7 +15,7 @@ import ColorAccordion from '@components/page/theming/ColorAccordion';
Ionic Framework is built to be a blank slate that can easily be customized and modified to fit a brand, while still following the standards of the different platforms. Theming Ionic apps is now easier than ever. Because the framework is built with CSS, it comes with pre-baked default styles which are extremely easy to change and modify.
-## Colors
+## Colors {/* #colors */}
Ionic has nine default colors that can be used to change the color of many components. Each color is actually a collection of multiple properties, including a `shade` and `tint`, used throughout Ionic.
@@ -23,20 +23,20 @@ When changing a color, it is important to set all of the related properties. Thi
-## Platform Standards
+## Platform Standards {/* #platform-standards */}
Ionic components adapt their look and behavior based on the platform the app is running on. We call this **Adaptive Styling**. This allows developers to build apps that use the same codebase for multiple platforms, while still looking "native" to those particular platforms.
Ionic has two **modes** that are used to customize the look of components based on the **platform**: `ios` and `md`. Each platform has a default mode, but this can easily be configured. For more information on customizing an application based on the platform, refer to [Platform Styles](platform-styles.mdx).
-## CSS Variables
+## CSS Variables {/* #css-variables */}
The Ionic Framework components are themed using [CSS custom properties (variables)](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables). CSS variables add dynamic values to an otherwise static language. This is something that has traditionally required a CSS preprocessor like Sass. The look of an application can easily be changed by changing the value of any of the [CSS Variables](css-variables.mdx) Ionic Framework provides.
-## CSS Shadow Parts
+## CSS Shadow Parts {/* #css-shadow-parts */}
CSS Shadow Parts were added to make it easier to fully customize Ionic Framework Shadow components. In the past, components that use [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) were unable to have elements inside of their shadow tree styled directly. With the addition of Shadow parts, there is no longer a need for CSS variables for every property on an inner element of a Shadow component. For more information on customizing Ionic Framework components using parts, refer to the [CSS Shadow Parts](css-shadow-parts.mdx) guide.
-## Branding
+## Branding {/* #branding */}
Ionic provides application colors that can be used to theme an application to match a brand or color scheme. The default theme uses a light background, but everything from the background color to the text color is fully customizable. For more information on branding, refer to [Themes](themes.mdx).
diff --git a/docs/theming/colors.mdx b/docs/theming/colors.mdx
index b05f9d1c2a..3c439cddb0 100644
--- a/docs/theming/colors.mdx
+++ b/docs/theming/colors.mdx
@@ -31,13 +31,13 @@ A color can be applied to an Ionic component in order to change the default colo
Dark
```
-## Layered Colors
+## Layered Colors {/* #layered-colors */}
Each color consists of the following properties: a `base`, `contrast`, `shade`, and `tint`. The `base` and `contrast` colors also require a `rgb` property which is the same color, just in [rgb format](https://developer.mozilla.org/en-US/docs/Glossary/RGB). Refer to [The Alpha Problem](advanced.mdx#the-alpha-problem) for an explanation of why the `rgb` property is also needed. Select from the dropdown below to explore each of the default colors Ionic provides and their variations.
-## Modifying Colors
+## Modifying Colors {/* #modifying-colors */}
To change the default values of a color, all of the listed variations for that color should be set. For example, to change the secondary color to #006600, set the following CSS properties:
@@ -62,7 +62,7 @@ Not sure how to get the variation colors from the base color? Try out our [Color
Refer to the [CSS Variables documentation](css-variables.mdx) for more information on CSS variables.
-## Adding Colors
+## Adding Colors {/* #adding-colors */}
Colors can be added for use throughout an application by setting the `color` property on an Ionic component, or by styling with CSS. Read on to learn how to manually add a new color, or use the [New Color Creator](#new-color-creator) below for a quick way to generate the code of a new color to be copy and pasted into an application.
@@ -109,7 +109,7 @@ div {
Refer to the [CSS Variables documentation](css-variables.mdx) for more information on setting and using CSS variables.
-## New Color Creator
+## New Color Creator {/* #new-color-creator */}
Create a new color below by changing the name and value, then copy and paste the code below into your project.
diff --git a/docs/theming/css-shadow-parts.mdx b/docs/theming/css-shadow-parts.mdx
index fb8fc4f959..c9270ba18e 100644
--- a/docs/theming/css-shadow-parts.mdx
+++ b/docs/theming/css-shadow-parts.mdx
@@ -12,7 +12,7 @@ title: CSS Shadow Parts
CSS Shadow Parts allow developers to style CSS properties on an element inside of a shadow tree. This is extremely useful in customizing Ionic Framework [Shadow DOM](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_shadow_DOM) components.
-## Why Shadow Parts?
+## Why Shadow Parts? {/* #why-shadow-parts */}
Ionic Framework is a distributed set of [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components). Web Components follow the [Shadow DOM specification](https://w3c.github.io/webcomponents/spec/shadow/) in order to encapsulate styles and markup.
@@ -45,11 +45,11 @@ ion-select .select-placeholder {
So how do we solve this? [CSS Shadow Parts](#shadow-parts-explained)!
-## Shadow Parts Explained
+## Shadow Parts Explained {/* #shadow-parts-explained */}
Shadow parts allow developers to style inside a shadow tree, from outside of that shadow tree. In order to do so, the [part must be exposed](#exposing-a-part) and then it can be styled by using [::part](#how-part-works).
-### Exposing a part
+### Exposing a part {/* #exposing-a-part */}
When creating a Shadow DOM component, a part can be added to an element inside of a shadow tree by assigning a `part` attribute on the element. This is added to the component in Ionic Framework and requires no action from an end user.
@@ -67,7 +67,7 @@ The above shows two parts: `placeholder` and `icon`. Refer to the [select docume
With these parts exposed, the element can now be styled directly using [::part](#how-part-works).
-### How ::part works
+### How ::part works {/* #how-part-works */}
The [`::part()`](https://developer.mozilla.org/en-US/docs/Web/CSS/::part) pseudo-element allows developers to select elements inside of a shadow tree that have been exposed via a part attribute.
@@ -105,7 +105,7 @@ There are some known limitations with [vendor prefixed pseudo-elements](#vendor-
:::
-## Ionic Framework Parts
+## Ionic Framework Parts {/* #ionic-framework-parts */}
All exposed parts for an Ionic Framework component can be found under the CSS Shadow Parts heading on its API page. To view all components and their API pages, refer to the [Component documentation](../components.mdx).
@@ -121,13 +121,13 @@ We welcome recommendations for additional parts. Please create a [new GitHub iss
:::
-## Known Limitations
+## Known Limitations {/* #known-limitations */}
-### Browser Support
+### Browser Support {/* #browser-support */}
CSS Shadow Parts are supported in the recent versions of all of the major browsers. However, some of the older versions do not support shadow parts. Verify the [browser support](https://caniuse.com/#feat=mdn-css_selectors_part) meets the requirements before implementing parts in an app. If browser support for older versions is required, we recommend continuing to use [CSS Variables](../theming/css-variables.mdx) for styling.
-### Vendor Prefixed Pseudo-Elements
+### Vendor Prefixed Pseudo-Elements {/* #vendor-prefixed-pseudo-elements */}
Pseudo-elements that are [vendor prefixed](https://developer.mozilla.org/en-US/docs/Glossary/Vendor_Prefix) are not supported at this time. An example of this would be any of the `::-webkit-scrollbar` pseudo-elements:
@@ -140,7 +140,7 @@ my-component::part(scroll)::-webkit-scrollbar {
Refer to [this issue on GitHub](https://github.com/w3c/csswg-drafts/issues/4530) for more information.
-### Structural Pseudo-Classes
+### Structural Pseudo-Classes {/* #structural-pseudo-classes */}
Most pseudo-classes are supported with parts, however, [structural pseudo-classes](https://www.w3.org/TR/selectors-4/#structural-pseudos) are not. An example of structural pseudo-classes that do not work is below.
@@ -156,7 +156,7 @@ my-component::part(container):last-child {
}
```
-### Chaining Parts
+### Chaining Parts {/* #chaining-parts */}
The `::part()` pseudo-element can not match additional `::part()`s.
diff --git a/docs/theming/css-variables.mdx b/docs/theming/css-variables.mdx
index 5de7885d85..96ee7e5382 100644
--- a/docs/theming/css-variables.mdx
+++ b/docs/theming/css-variables.mdx
@@ -12,9 +12,9 @@ title: CSS Variables
Ionic components are built with [CSS Variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) for easy customization of an application. CSS variables allow a value to be stored in one place, then referenced in multiple other places. They also make it possible to change CSS dynamically at runtime (which previously required a CSS preprocessor). CSS variables make it easier than ever to override Ionic components to match a brand or theme.
-## Setting Values
+## Setting Values {/* #setting-values */}
-### Global Variables
+### Global Variables {/* #global-variables */}
CSS variables can be set globally in an application in the `:root` selector. They can also be applied only for a specific mode. Refer to [Ionic Variables](#ionic-variables) for more information on the global variables Ionic provides.
@@ -41,7 +41,7 @@ When using the Ionic CLI to start an Angular, React or Vue project, the `src/the
}
```
-### Component Variables
+### Component Variables {/* #component-variables */}
To set a CSS variable for a specific component, add the variable inside of its selector. Refer to [Ionic Variables](#ionic-variables) for more information on the component-level variables Ionic provides.
@@ -57,7 +57,7 @@ ion-button {
}
```
-### Variables set via JavaScript
+### Variables set via JavaScript {/* #variables-set-via-javascript */}
CSS variables can also be changed via JavaScript using [setProperty()](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration/setProperty):
@@ -66,9 +66,9 @@ const el = document.querySelector('.fancy-button');
el.style.setProperty('--background', '#36454f');
```
-## Getting Values
+## Getting Values {/* #getting-values */}
-### Using CSS
+### Using CSS {/* #using-css */}
The [var() CSS function](https://developer.mozilla.org/en-US/docs/Web/CSS/var) can be used to get the value of a CSS variable, along with any number of fallback values, if desired. In the below example, the `--background` property will be set to the value of the `--charcoal` variable, if defined, and if not it will use `#36454f`.
@@ -78,7 +78,7 @@ The [var() CSS function](https://developer.mozilla.org/en-US/docs/Web/CSS/var) c
}
```
-### Using JavaScript
+### Using JavaScript {/* #using-javascript */}
The value of a CSS variable can be read in JavaScript using [getPropertyValue()](https://developer.mozilla.org/en-US/docs/Web/API/CSSStyleDeclaration/getPropertyValue):
@@ -87,12 +87,12 @@ const el = document.querySelector('.fancy-button');
const color = el.style.getPropertyValue('--background');
```
-## Ionic Variables
+## Ionic Variables {/* #ionic-variables */}
-### Component Variables
+### Component Variables {/* #component-variables-1 */}
Ionic provides variables that exist at the component level, such as `--background` and `--color`. For a list of the custom properties a component accepts, view the `CSS Custom Properties` section of its [API reference](../api.mdx). For example, refer to the [Button CSS Custom Properties](../api/button.mdx#css-custom-properties).
-### Global Variables
+### Global Variables {/* #global-variables-1 */}
There are several global variables that Ionic provides in order to make theming an entire application easier. For more information, refer to [Colors](colors.mdx), [Themes](themes.mdx) and [Advanced Theming](advanced.mdx).
diff --git a/docs/theming/dark-mode.mdx b/docs/theming/dark-mode.mdx
index da28604d9e..40bf87e362 100644
--- a/docs/theming/dark-mode.mdx
+++ b/docs/theming/dark-mode.mdx
@@ -15,11 +15,11 @@ import TabItem from '@theme/TabItem';
Ionic makes it easy to change the palettes of your app, including supporting dark color schemes. Dark mode is a display setting that changes all of an app's views to a dark palette. It has system-wide support on iOS and Android, making it highly desirable for developers to add to their apps.
-## Enabling Dark Palette
+## Enabling Dark Palette {/* #enabling-dark-palette */}
There are three provided ways to enable the dark palette in an app: **always**, based on **system** settings, or by using a CSS **class**.
-### Always
+### Always {/* #always */}
The default palette provided with Ionic Framework is a light palette, consisting of a light background and dark text. However, the default palette can be changed to the dark palette by importing the following stylesheet in the appropriate files:
@@ -70,7 +70,7 @@ Avoid targeting the `.ios` or `.md` selectors to override the Ionic dark palette
:::
-### System
+### System {/* #system */}
The system approach to enable dark mode involves checking the system settings for the user's preferred color scheme. This is the default when starting a new Ionic Framework app. Importing the following stylesheet in the appropriate file will automatically retrieve the user's preference from the system settings and apply the dark palette when dark mode is preferred:
@@ -127,7 +127,7 @@ Avoid targeting the `.ios` or `.md` selectors to override the Ionic dark palette
:::
-### CSS Class
+### CSS Class {/* #css-class */}
While the previous approaches are excellent for enabling the dark palette through file imports alone, there are scenarios where you may need more control over its application. In cases where you need to apply the dark palette conditionally, such as through a toggle, or if you want to extend the functionality based on system settings, we provide a dark palette class file. This file applies the dark palette when a specific class is added to an app. Importing the following stylesheet into the appropriate file will provide the necessary styles for using the dark palette with the class:
@@ -184,7 +184,7 @@ The `.ion-palette-dark` class **must** be added to the `html` element in order t
:::
-## Adjusting System UI Components
+## Adjusting System UI Components {/* #adjusting-system-ui-components */}
When developing a dark palette, you may notice that certain system UI components are not adjusting to dark mode properly. To fix this you will need to specify the `color-scheme`. Refer to the [browser compatibility for color-scheme](https://caniuse.com/#feat=mdn-html_elements_meta_name_color-scheme) for details on cross browser support.
@@ -218,7 +218,7 @@ For developers looking to customize the theme color under the status bar in Safa
:::
-## Ionic Dark Palette
+## Ionic Dark Palette {/* #ionic-dark-palette */}
Ionic has a recommended dark palette that can be enabled in three different ways: [always](#always), based on [system](#system) settings, or by using a [CSS class](#css-class). Each of these methods involves importing the dark palette file with the corresponding name.
diff --git a/docs/theming/high-contrast-mode.mdx b/docs/theming/high-contrast-mode.mdx
index 8574ac4de3..4ab7fb8e7a 100644
--- a/docs/theming/high-contrast-mode.mdx
+++ b/docs/theming/high-contrast-mode.mdx
@@ -15,15 +15,15 @@ import TabItem from '@theme/TabItem';
Ionic offers palettes with increased contrast for users with low vision. These palettes work by amplifying the contrast between foreground content, such as text, and background content, such as UI components. Ionic provides both light and dark variants for achieving high contrast.
-## Overview
+## Overview {/* #overview */}
The default palette in Ionic provides [Ionic colors](./colors.mdx) that meet [Level AA color contrast](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) as defined by Web Content Accessibility Guidelines (WCAG) when used with the appropriate contrast color. The [Ionic colors](./colors.mdx) in the high contrast palette have been updated to meet [Level AAA color contrast](https://www.w3.org/WAI/WCAG21/Understanding/contrast-enhanced.html) when used with the appropriate contrast color. Notably, improvements have been made to the contrast of UI components, including border, text, and background colors. However, it's important to note that within the high contrast palette, priority is given to text legibility. This means that if adjusting the contrast of a UI component against the page background would significantly compromise the contrast between the component's text and its background, the contrast of the UI component background will remain unchanged.
-## Enabling High Contrast Theme
+## Enabling High Contrast Theme {/* #enabling-high-contrast-theme */}
There are three provided ways to enable the high contrast palette in an app: **always**, based on **system** settings, or by using a CSS **class**.
-### Always
+### Always {/* #always */}
The high contrast palette can be enabled by importing the following stylesheet in the appropriate files. This approach will enable the high contrast palette regardless of the system settings for contrast preference.
@@ -72,7 +72,7 @@ import AlwaysHighContrastMode from '@site/static/usage/v9/theming/always-high-co
-### System
+### System {/* #system */}
The system approach to enabling high contrast mode involves checking the system settings for the user's preferred contrast. This is the default when starting a new Ionic Framework app. Importing the following stylesheets in the appropriate file will automatically retrieve the user's preference from the system settings and apply the high contrast palette when high contrast is preferred.
@@ -136,7 +136,7 @@ high contrast dark palette must be imported after `dark.system.css`. Otherwise,
:::
-### CSS Class
+### CSS Class {/* #css-class */}
While the previous approaches are excellent for enabling the high contrast palette through file imports alone, there are scenarios where you may need more control over where it is applied. In cases where you need to apply the high contrast palette conditionally, such as through a toggle, or if you want to extend the functionality based on system settings, we provide a high contrast palette class file. This file applies the high contrast palette when a specific class is added to an app. Importing the following stylesheets into the appropriate file will provide the necessary styles for using the high contrast palette with the class:
@@ -205,7 +205,7 @@ The `.ion-palette-high-contrast` class **must** be added to the `html` element i
:::
-## Customizing Ionic High Contrast Theme
+## Customizing Ionic High Contrast Theme {/* #customizing-ionic-high-contrast-theme */}
Ionic has a recommended high contrast palette that can be enabled in three different ways: [always](#always), based on [system](#system) settings, or by using a [CSS class](#css-class). Each of these methods involves importing the high contrast palette file with the corresponding name.
diff --git a/docs/theming/platform-styles.mdx b/docs/theming/platform-styles.mdx
index e58a1be457..c045450608 100644
--- a/docs/theming/platform-styles.mdx
+++ b/docs/theming/platform-styles.mdx
@@ -12,7 +12,7 @@ title: Platform Styles
Ionic provides platform specific styles based on the device the application is running on. Styling the components to match the device guidelines allows the application to be written once but look and feel native to the user depending on where it is accessed.
-## Ionic Modes
+## Ionic Modes {/* #ionic-modes */}
Ionic uses **modes** to customize the look of components. Each **platform** has a default **mode**, but this can be overridden through the global [config](../developing/config.mdx). The following chart displays the default **mode** that is added to each **platform**:
@@ -30,7 +30,7 @@ For example, an app being viewed on an Android platform will use the `md` (Mater
_Note: The **platform** and the **mode** are not the same. The platform can be set to use any mode in the [config](../developing/config.mdx) of an app._
-## Overriding Mode Styles
+## Overriding Mode Styles {/* #overriding-mode-styles */}
Each Ionic component can be styled based on the mode. The `html` element has both a `class` and `mode` attribute with a value equal to the current mode. These can be used to override styles for any component. For example, to style an `ion-badge` to have `uppercase` text only in `ios` mode:
diff --git a/docs/theming/themes.mdx b/docs/theming/themes.mdx
index 4b68041ec9..2f7d141843 100644
--- a/docs/theming/themes.mdx
+++ b/docs/theming/themes.mdx
@@ -15,7 +15,7 @@ import SteppedColorGenerator from '@components/page/theming/SteppedColorGenerato
Ionic provides several global variables that are used throughout components to change the default theme of an entire application. [Application Colors](#application-colors) are useful to change the look of most of the Ionic components, and [Stepped Colors](#stepped-colors) are used as variations in some of the Ionic components.
-## Application Colors
+## Application Colors {/* #application-colors */}
The application colors are used in multiple places in Ionic. These are useful for easily creating dark palettes or themes that match a brand.
@@ -50,7 +50,7 @@ It is important to note that the background and text color variables also requir
| `--ion-item-color` | Color of the components in the Item |
| `--ion-placeholder-color` | Color of the placeholder in Inputs |
-## Stepped Colors
+## Stepped Colors {/* #stepped-colors */}
After exploring different ways to customize the Ionic theme, we found that we couldn't use just one background or text color. In order to imply importance and depth throughout the design, we need to use different shades of the background and text colors. To accommodate this pattern, we created stepped colors.
@@ -62,7 +62,7 @@ Ionic provides separate step colors for text and background colors so they can b
By default, the Ionic text stepped colors start at the default text color value #000000 and mix with the background color value #ffffff using an increasing percentage. The Ionic background stepped colors start at the default background color value #ffffff and mix with the text color value #000000 using an increasing percentage. The full list of stepped colors is shown in the generator below.
-## Stepped Color Generator
+## Stepped Color Generator {/* #stepped-color-generator */}
Create a custom background and text color theme for your app. Update the background or text color’s hex values below, then copy and paste the generated code directly into your Ionic project.
diff --git a/docs/troubleshooting/build.mdx b/docs/troubleshooting/build.mdx
index c7eddca391..434837fac4 100644
--- a/docs/troubleshooting/build.mdx
+++ b/docs/troubleshooting/build.mdx
@@ -10,9 +10,9 @@ title: Build Errors
/>
-## Common mistakes
+## Common mistakes {/* #common-mistakes */}
-### Forgetting Parentheses on a Decorator
+### Forgetting Parentheses on a Decorator {/* #forgetting-parentheses-on-a-decorator */}
Decorators should have parentheses `()` after an annotation. Some examples include: `@Injectable()`, `@Optional()`, `@Input()`, etc.
@@ -27,9 +27,9 @@ class MyDirective {
}
```
-## Common Errors
+## Common Errors {/* #common-errors */}
-### Cannot Resolve all Parameters
+### Cannot Resolve all Parameters {/* #cannot-resolve-all-parameters */}
```shell
Cannot resolve all parameters for 'YourClass'(?). Make sure that all the parameters are decorated with Inject or have valid type annotations and that 'YourClass' is decorated with Injectable.
@@ -77,7 +77,7 @@ class MyIcon {
}
```
-### No provider for ParamType
+### No provider for ParamType {/* #no-provider-for-paramtype */}
```shell
No provider for ParamType! (MyClass -> ParamType)
@@ -168,7 +168,7 @@ class MyDir {
}
```
-### Can't bind to 'propertyName' since it isn't a known property
+### Can't bind to 'propertyName' since it isn't a known property {/* #cant-bind-to-propertyname-since-it-isnt-a-known-property */}
```shell
Can't bind to 'propertyName' since it isn't a known property of the 'elementName' element and there are no matching directives with a corresponding property
@@ -181,7 +181,7 @@ This happens when you try and bind a property on an element that doesn't have th
```
-### No provider for ControlContainer
+### No provider for ControlContainer {/* #no-provider-for-controlcontainer */}
```shell
No provider for ControlContainer! (NgControlName -> ControlContainer)
@@ -198,7 +198,7 @@ This error is a more specific version of the `No provider` error above. It happe
})
```
-### No Component Factory Found
+### No Component Factory Found {/* #no-component-factory-found */}
```shell
No component factory found for
diff --git a/docs/troubleshooting/cors.mdx b/docs/troubleshooting/cors.mdx
index 024f06e04f..60103cab70 100644
--- a/docs/troubleshooting/cors.mdx
+++ b/docs/troubleshooting/cors.mdx
@@ -10,7 +10,7 @@ title: CORS Errors
/>
-## What is CORS?
+## What is CORS? {/* #what-is-cors */}
**Cross-Origin Resource Sharing (CORS)** is a mechanism that browsers and webviews — like the ones powering Capacitor and Cordova — use to restrict HTTP and HTTPS requests made from scripts to resources in a different origin for security reasons, mainly to protect your user's data and prevent attacks that would compromise your app.
@@ -28,9 +28,9 @@ XMLHttpRequest cannot load https://api.example.com. No 'Access-Control-Allow-Ori
:::
-## How does CORS work
+## How does CORS work {/* #how-does-cors-work */}
-### Request with preflight
+### Request with preflight {/* #request-with-preflight */}
By default, when a web app tries to make a cross-origin request the browser sends a **preflight request** before the actual request. This preflight request is needed in order to know if the external resource supports CORS and if the actual request can be sent safely, since it may impact user data.
@@ -86,7 +86,7 @@ If the returned origin and method don't match the ones from the actual request,
In our example, since the API expects JSON, all `POST` requests will have a `Content-Type: application/json` header and always be preflighted.
-### Simple requests
+### Simple requests {/* #simple-requests */}
Some requests are always considered safe to send and don't need a preflight if they meet all of the following conditions:
@@ -112,9 +112,9 @@ Some requests are always considered safe to send and don't need a preflight if t
In our example API, `GET` requests don't need to be preflighted because no JSON data is being sent, and so the app doesn't need to use the `Content-Type: application/json` header. They will always be simple requests.
-## CORS Headers
+## CORS Headers {/* #cors-headers */}
-### Server Headers (Response)
+### Server Headers (Response) {/* #server-headers-response */}
| Header | Value | Description |
| -------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
@@ -125,26 +125,26 @@ In our example API, `GET` requests don't need to be preflighted because no JSON
| Access-Control-Expose-Headers | `headers` | Specifies the headers that the browser is allowed to access. |
| Access-Control-Max-Age | `seconds` | Indicates how long the results of a preflight request can be cached. |
-### Browser Headers (Request)
+### Browser Headers (Request) {/* #browser-headers-request */}
The browser automatically sends the appropriate headers for CORS in every request to the server, including the preflight requests. Please note that the headers below are for reference only, and **should not be set in your app code** (the browser will ignore them).
-#### All Requests
+#### All Requests {/* #all-requests */}
| Header | Value | Description |
| ---------- | -------- | ------------------------------------ |
| **Origin** | `origin` | Indicates the origin of the request. |
-#### Preflight Requests
+#### Preflight Requests {/* #preflight-requests */}
| Header | Value | Description |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------- |
| **Access-Control-Request-Method** | `method` | Used to let the server know what method will be used when the actual request is made. |
| Access-Control-Request-Headers | `headers` | Used to let the server know what non-simple headers will be used when the actual request is made. |
-## Solutions for CORS Errors
+## Solutions for CORS Errors {/* #solutions-for-cors-errors */}
-### A. Enabling CORS in a server you control
+### A. Enabling CORS in a server you control {/* #a-enabling-cors-in-a-server-you-control */}
The correct and easiest solution is to enable CORS by returning the [right response headers](#server-headers-response) from the web server or backend and responding to preflight requests, as it allows to keep using `XMLHttpRequest`, `fetch`, or abstractions like `HttpClient` in Angular.
@@ -154,7 +154,7 @@ Please note that all of the `Access-Control-Allow-*` headers have to be sent fro
Here are some of the origins your Ionic app may be served from:
-#### Capacitor
+#### Capacitor {/* #capacitor */}
| Platform | Origin |
| -------- | ----------------------- |
@@ -163,7 +163,7 @@ Here are some of the origins your Ionic app may be served from:
Replace `localhost` with your own hostname if you have changed the default in the Capacitor config.
-#### Ionic WebView 3.x plugin on Cordova
+#### Ionic WebView 3.x plugin on Cordova {/* #ionic-webview-3x-plugin-on-cordova */}
| Platform | Origin |
| -------- | ------------------- |
@@ -172,7 +172,7 @@ Replace `localhost` with your own hostname if you have changed the default in th
Replace `localhost` with your own hostname if you have changed the default in the plugin config.
-#### Ionic WebView 2.x plugin on Cordova
+#### Ionic WebView 2.x plugin on Cordova {/* #ionic-webview-2x-plugin-on-cordova */}
| Platform | Origin |
| -------- | ----------------------- |
@@ -181,7 +181,7 @@ Replace `localhost` with your own hostname if you have changed the default in th
Replace port `8080` with your own if you have changed the default in the plugin config.
-#### Local development in the browser
+#### Local development in the browser {/* #local-development-in-the-browser */}
| Command | Origin |
| ----------------------------- | -------------------------------------------------------- |
@@ -232,19 +232,19 @@ app.listen(3000, () => {
});
```
-### B. Working around CORS in a server you can't control
+### B. Working around CORS in a server you can't control {/* #b-working-around-cors-in-a-server-you-cant-control */}
-#### Don't leak your keys!
+#### Don't leak your keys! {/* #dont-leak-your-keys */}
If you are trying to connect to a 3rd-party API, first check in its documentation that is safe to use it directly from the app (client-side) and that it won't leak any secret/private keys or credentials, as they can be read in clear text in Javascript code. Many APIs don't support CORS on purpose, in order to force developers to use them in the server and protect important information or keys.
-#### 1. Native-only apps (iOS/Android)
+#### 1. Native-only apps (iOS/Android) {/* #1-native-only-apps-iosandroid */}
-##### Capacitor Applications (Recommended)
+##### Capacitor Applications (Recommended) {/* #capacitor-applications-recommended */}
For Capacitor applications, use the [Capacitor HTTP API](https://capacitorjs.com/docs/apis/http). This API patches `fetch` and `XMLHttpRequest` to use native libraries. Please note that if you also deploy the application to a web-based context such as PWA or the local development server (via `ionic serve` for example) you still need to implement CORS for those scenarios.
-##### Legacy Cordova Applications
+##### Legacy Cordova Applications {/* #legacy-cordova-applications */}
For legacy Cordova applications, use the [HTTP plugin with the Awesome Cordova Plugins wrapper](https://danielsogl.gitbook.io/awesome-cordova-plugins/http). Please note that this plugin doesn't work in the browser, so the development and testing of the app must always be done in a device or simulator going forward.
@@ -280,7 +280,7 @@ export class HomePage {
}
```
-#### 2. Native + PWAs
+#### 2. Native + PWAs {/* #2-native--pwas */}
Send the requests through an HTTP/HTTPS proxy that bypasses them to the external resources and adds the necessary CORS headers to the responses. This proxy must be trusted or under your control, as it will be intercepting most traffic made by the app.
@@ -288,7 +288,7 @@ Also, keep in mind that the browser or webview will not receive the original HTT
Check [cors-anywhere](https://github.com/Rob--W/cors-anywhere/) for a Node.js CORS proxy that can be deployed in your own server. Using free hosted CORS proxies in production is not recommended.
-### C. Disabling CORS or browser web security
+### C. Disabling CORS or browser web security {/* #c-disabling-cors-or-browser-web-security */}
Please be aware that CORS exists for a reason (security of user data and to prevent attacks against your app). **It's not possible or advisable to try to disable CORS**.
@@ -296,7 +296,7 @@ Older webviews like `UIWebView` on iOS don't enforce CORS but are deprecated and
If you are developing a PWA or testing in the browser, using the `--disable-web-security` flag in Google Chrome or an extension to disable CORS is a really bad idea. You will be exposed to all kind of attacks, you can't ask your users to take the risk, and your app won't work once in production.
-##### Sources
+##### Sources {/* #sources */}
- [CORS Errors in Ionic Apps](https://fdezromero.com/cors-errors-in-ionic-apps)
- [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)
diff --git a/docs/troubleshooting/debugging.mdx b/docs/troubleshooting/debugging.mdx
index d10f67d5ef..1ffd36330e 100644
--- a/docs/troubleshooting/debugging.mdx
+++ b/docs/troubleshooting/debugging.mdx
@@ -19,11 +19,11 @@ title: Debugging
allowFullScreen
>
-## Live Reload
+## Live Reload {/* #live-reload */}
Live Reload is useful for debugging native functionality (such as plugins) on device hardware. Rather than deploy a new native binary each time you make a code change, it reloads the browser (or WebView) when changes in the app are detected. Learn more about [Live Reload](../cli/livereload.mdx).
-## iOS and Safari
+## iOS and Safari {/* #ios-and-safari */}
Safari can be used to debug an Ionic app on a connected iOS device or iOS simulator.
@@ -35,7 +35,7 @@ Run the iOS simulator or connect your iOS device to your Mac, then run the Ionic
Within Safari, select **Develop** in the toolbar. The dropdown menu lists the name of your device and app. Hover over the app name and click on **localhost**. This will open a new window with the Safari Developer Tools - use them to inspect and debug the Ionic app running on your device.
-## Android and Chrome
+## Android and Chrome {/* #android-and-chrome */}
Use Google Chrome's DevTools to debug an app when it is running in the browser using the `ionic serve` command, deployed to an emulator, or on a physical device.
@@ -55,7 +55,7 @@ The app preview may not automatically appear when you open Chrome Developer Tool
:::
-## Debugging with Visual Studio locally in Chrome (both Android & iOS)
+## Debugging with Visual Studio locally in Chrome (both Android & iOS) {/* #debugging-with-visual-studio-locally-in-chrome-both-android--ios */}
[Visual Studio Code](https://code.visualstudio.com/) can also be used to debug an Ionic app running in the Chrome web browser.
@@ -67,7 +67,7 @@ Make sure that the port used in the url property of your `launch.json` file matc
In the debug target dropdown menu, select **Launch against Chrome**, then click run. This will open a new instance of the Chrome browser and VS code will attach to it. You can set breakpoints and use the other debugging tools within VS Code while your app is running in Chrome.
-## Debugging with Visual Studio Code in Android
+## Debugging with Visual Studio Code in Android {/* #debugging-with-visual-studio-code-in-android */}
[Visual Studio Code](https://code.visualstudio.com/) has a dedicated plugin for debugging apps that run in an Android WebView.
diff --git a/docs/troubleshooting/native.mdx b/docs/troubleshooting/native.mdx
index cd28845983..073151db8f 100644
--- a/docs/troubleshooting/native.mdx
+++ b/docs/troubleshooting/native.mdx
@@ -10,7 +10,7 @@ title: Native Errors
/>
-## Code Signing errors
+## Code Signing errors {/* #code-signing-errors */}
```shell
Code Signing Error: Failed to create provisioning profile. The app ID "com.csform.ionic.yellow" cannot be registered to your development team. Change your bundle identifier to a unique string to try again. Code Signing Error: No profiles for 'com.csform.ionic.yellow' were found: Xcode couldn't find any iOS App Development provisioning profiles matching 'com.csform.ionic.yellow'. Code Signing Error: Code signing is required for product type 'Application' in SDK 'iOS 11.1'
@@ -42,7 +42,7 @@ Running an app on an iOS device requires a provisioning profile. If a provisioni
-## Xcode build error 65
+## Xcode build error 65 {/* #xcode-build-error-65 */}
```shell
Error: Error code 65 for command: xcodebuild with args: -xcconfig,/Users/ionitron/projects/my-project/platforms/ios/cordova/build-debug.xcconfig,-workspace,SC project.xcworkspace,-scheme,SC project,-configuration,Debug,-sdk,iphonesimulator,-destination,platform=iOS Simulator,name=iPhone X,build,CONFIGURATION_BUILD_DIR=/Users/ionitron/projects/my-project/platforms/ios/build/emulator,SHARED_PRECOMPS_DIR=/Users/ionitron/projects/my-project/platforms/ios/build/sharedpch
@@ -63,7 +63,7 @@ ionic cordova build ios --prod
Once these commands have been ran a fresh build can be done.
-## Clashing Google Play Services versions
+## Clashing Google Play Services versions {/* #clashing-google-play-services-versions */}
```shell
Error: more than one library with package name com.google.android.gms
diff --git a/docs/troubleshooting/runtime.mdx b/docs/troubleshooting/runtime.mdx
index fbcbe8ea14..130e861221 100644
--- a/docs/troubleshooting/runtime.mdx
+++ b/docs/troubleshooting/runtime.mdx
@@ -10,7 +10,7 @@ title: Runtime Issues
/>
-## Blank App
+## Blank App {/* #blank-app */}
:::note
@@ -42,7 +42,7 @@ Alternatively, a project could be updated to use the latest release of the `@ang
This will automatically include the polyfills for older browsers that need them.
-## Directive Not Working
+## Directive Not Working {/* #directive-not-working */}
:::note
@@ -85,7 +85,7 @@ class MyDir {
class MyPage { }
```
-## Click Delays
+## Click Delays {/* #click-delays */}
:::note
@@ -107,7 +107,7 @@ add the `tappable` attribute to your element.
I am clickable!
```
-## Angular Change Detection
+## Angular Change Detection {/* #angular-change-detection */}
:::note
@@ -151,7 +151,7 @@ This flag is automatically included when creating an Ionic app via the Ionic CLI
:::
-## Cordova plugins not working in the browser
+## Cordova plugins not working in the browser {/* #cordova-plugins-not-working-in-the-browser */}
At some point in your development you may, try to call Cordova plugin, but get a
warning:
@@ -175,7 +175,7 @@ EXCEPTION: Error: Uncaught (in promise): TypeError: undefined is not an object
If this happens, test the plugin on a real device or simulator.
-## Multiple instances of a provider
+## Multiple instances of a provider {/* #multiple-instances-of-a-provider */}
If you inject a provider in every component because you want it available to all
of them you will end up with multiple instances of the provider. You should
diff --git a/docs/updating/4-0.mdx b/docs/updating/4-0.mdx
index 01b422e1e1..261e074c30 100644
--- a/docs/updating/4-0.mdx
+++ b/docs/updating/4-0.mdx
@@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem';
# Updating to Ionic 4
-## Updating from Ionic 3 to 4
+## Updating from Ionic 3 to 4 {/* #updating-from-ionic-3-to-4 */}
:::note
@@ -37,7 +37,7 @@ We suggest the following general process when migrating an existing application
In many cases, using the Ionic CLI to generate a new object and then copying the code also works very well. For example: `ionic g service weather` will create a shell `Weather` service and test. The code can then be copied from the older project with minor modifications as needed. This helps to ensure the proper structure is followed. This also generates shells for unit tests.
-### Changes in Package Name
+### Changes in Package Name {/* #changes-in-package-name */}
In Ionic 4, the package name is `@ionic/angular`. Uninstall Ionic 3 and install Ionic 4 using the new package name:
@@ -48,7 +48,7 @@ $ npm install @ionic/angular@v4-lts
While migrating an app, update the imports from `ionic-angular` to `@ionic/angular`.
-### Project structure
+### Project structure {/* #project-structure */}
One of the major changes between an Ionic 3 app and an Ionic 4 app is the overall project layout and structure. In v3, Ionic apps had a custom convention for how an app should be set up and what that folder structure should look like. In v4, this has been changed to follow the recommended setup of each supported framework.
@@ -140,11 +140,11 @@ See the following `ionic.config.json` as an example:
}
```
-### RxJS Changes
+### RxJS Changes {/* #rxjs-changes */}
Between V3 and V4, RxJS was updated to version 6. This changes many of the import paths of operators and core RxJS functions. Please refer to the [RxJS Migration Guide](https://github.com/ReactiveX/rxjs/blob/6.x/docs_app/content/guide/v6/migration.md) for details.
-### Lifecycle Events
+### Lifecycle Events {/* #lifecycle-events */}
With V4, we're now able to utilize the typical events provided by [Angular](https://angular.io/guide/lifecycle-hooks). But for certain cases, you might want to have access to the events fired when a component has finished animating during its route change. In this case, the `ionViewWillEnter`, `ionViewDidEnter`, `ionViewWillLeave`, and `ionViewDidLeave` have been ported over from V3. Use these events to coordinate actions with Ionic's own animations system.
@@ -152,7 +152,7 @@ Older events like `ionViewDidLoad`, `ionViewCanLeave`, and `ionViewCanEnter` hav
For more details, check out the [router-outlet docs](../api/router-outlet.mdx)
-### Overlay Components
+### Overlay Components {/* #overlay-components */}
In prior versions of Ionic, overlay components such as Loading, Toast, or Alert were created synchronously. In Ionic v4, these components are all created asynchronously. As a result of this, the API is now promise-based.
@@ -190,7 +190,7 @@ async showAlert() {
}
```
-### Navigation
+### Navigation {/* #navigation */}
In V4, navigation received the most changes. Now, instead of using Ionic's own `NavController`, we integrate with the official Angular Router. This not only provides a consistent routing experience across apps, but is much more dependable. The Angular team has an [excellent guide](http://angular.io/guide/router) on their docs site that covers the Router in great detail.
@@ -198,7 +198,7 @@ To provide the platform-specific animations that users are used to, we have crea
For a detailed explanation in navigation works in a V4 project, check out the [Angular navigation guide](../angular/navigation.mdx).
-### Lazy Loading
+### Lazy Loading {/* #lazy-loading */}
Since Navigation has changed, the mechanism for lazy loading has also changed in V4.
@@ -248,15 +248,15 @@ export class AppModule {}
For a detailed explanation of lazy loading in V4 project, check out the [Angular navigation guide](../angular/navigation.mdx#lazy-loading-routes).
-### Markup Changes
+### Markup Changes {/* #markup-changes */}
Since v4 moved to Custom Elements, there's been a significant change to the markup for each component. These changes have all been made to follow the Custom Elements spec, and have been documented in a [dedicated file on GitHub](https://github.com/ionic-team/ionic/blob/master/angular/BREAKING.md#breaking-changes).
To help with these markup changes, we've released a TSLint-based [Migration Tool](https://github.com/ionic-team/v4-migration-tslint), which detects issues and can even fix some of them automatically.
-## Updating from Ionic 1 to 4
+## Updating from Ionic 1 to 4 {/* #updating-from-ionic-1-to-4 */}
-### Ionic 1 to Ionic 4: What’s Involved?
+### Ionic 1 to Ionic 4: What’s Involved? {/* #ionic-1-to-ionic-4-whats-involved */}
Migrating from Ionic 1 to Ionic 4 involves moving from AngularJS (aka Angular 1) to Angular 7+. There are many architectural differences between these versions, so some of the app code will have to be rewritten. The amount of work involved depends on the complexity and size of your app.
@@ -268,7 +268,7 @@ Here are some considerations to review before beginning the upgrade:
- **Framework support**: In 2019, Ionic will release full support for React. You can also use Ionic Framework components [without a framework](../intro/cdn.mdx). Since these are not production-ready yet, we recommend sticking with Angular or waiting until the other framework support is available.
- **Budget and team makeup**: The length of a migration project will vary based on the size of your team, the complexity of the app, and the amount of time allotted to make the transition.
-### Suggested Strategy
+### Suggested Strategy {/* #suggested-strategy */}
Once your development team has identified a good time frame for beginning the migration, Ionic recommends feature-freezing the Ionic 1 application and getting the code in order: Fix any major bugs, eliminate tech debt, and reorganize as you see fit. Then, identify which features to migrate over and which to abandon.
@@ -276,14 +276,14 @@ Once the Ionic 1 app is stable, create a new Ionic 4 project. The majority of th
Once the team is comfortable that the Ionic 4 app has become stable and has fulfilled a core set of features, you can then shut down the Ionic 1 app.
-### Moving From AngularJS to Angular
+### Moving From AngularJS to Angular {/* #moving-from-angularjs-to-angular */}
Please reference official [Angular upgrade guide](https://angular.io/guide/upgrade) information.
-### Ionic Changes
+### Ionic Changes {/* #ionic-changes */}
Our Ionic 3 to Ionic 4 migration sections above may prove to be a useful reference. Generate a new Ionic 4 project using the blank starter (refer to [Starting an App](../developing/starting.mdx)). Spend time getting familiar with Ionic 4 components. Happy building!
-### Need Assistance?
+### Need Assistance? {/* #need-assistance */}
If your team would like assistance with the migration, please [reach out to us](https://ionicframework.com/enterprise-engine)! Ionic offers Advisory Services, which includes Ionic 4 training, architecture reviews, and migration assistance.
diff --git a/docs/updating/5-0.mdx b/docs/updating/5-0.mdx
index a844b2dacf..4d771961d6 100644
--- a/docs/updating/5-0.mdx
+++ b/docs/updating/5-0.mdx
@@ -18,7 +18,7 @@ For a **complete list of breaking changes** from Ionic 4 to Ionic 5, please refe
:::
-### Packages and Dependencies
+### Packages and Dependencies {/* #packages-and-dependencies */}
For Angular based projects, you can simply run:
diff --git a/docs/updating/6-0.mdx b/docs/updating/6-0.mdx
index ed4e01f9a4..812c6b1fa9 100644
--- a/docs/updating/6-0.mdx
+++ b/docs/updating/6-0.mdx
@@ -16,9 +16,9 @@ For a **complete list of breaking changes** from Ionic 5 to Ionic 6, please refe
:::
-## Getting Started
+## Getting Started {/* #getting-started */}
-### Angular
+### Angular {/* #angular */}
1. Ionic 6 supports Angular 12+. Update to the latest version of Angular by following the [Angular Update Guide](https://update.angular.io/).
2. Update to the latest version of Ionic 6:
@@ -36,7 +36,7 @@ npm install @ionic/angular@6 @ionic/angular-server@6
3. Remove any usage of `Config.set()`. Instead, set your config in `IonicModule.forRoot()`. Refer to the [Angular Config Documentation](../developing/config) for more examples.
4. Remove any usage of the `setupConfig` function previously exported from `@ionic/angular`. Set your config in `IonicModule.forRoot()` instead.
-### React
+### React {/* #react */}
1. Ionic 6 supports React 17+. Update to the latest version of React:
@@ -107,7 +107,7 @@ import { menuController } from '@ionic/core';
import { menuController } from '@ionic/core/components';
```
-### Vue
+### Vue {/* #vue */}
1. Ionic 6 supports Vue 3.0.6+. Update to the latest version of Vue:
@@ -300,7 +300,7 @@ const routes: Array = [
];
```
-### Core
+### Core {/* #core */}
1. Update to the latest version of Ionic 6:
@@ -308,9 +308,9 @@ const routes: Array = [
npm install @ionic/core@6
```
-## Updating Your Code
+## Updating Your Code {/* #updating-your-code */}
-### Datetime
+### Datetime {/* #datetime */}
1. Remove any usages of the `placeholder`, `pickerOptions`, `pickerFormat`, `monthNames`, `monthShortNames`, `dayNames`, and `dayShortNames` properties. `ion-datetime` now automatically formats the month names, day names, and time displayed inside of the component according to the language and region set on the device. Refer to the [ion-datetime Localization Documentation](../api/datetime#localization) for more information.
@@ -328,15 +328,15 @@ Refer to the [Datetime Migration Sample Application](https://github.com/ionic-te
:::
-### Icon
+### Icon {/* #icon */}
Ionic 6 now ships with Ionicons 6. Review the [Ionicons 6 Breaking Changes Guide](https://github.com/ionic-team/ionicons/releases/tag/v6.0.0) and make any necessary changes.
-### Input
+### Input {/* #input */}
Ensure `null` is not passed in as a value to the `placeholder` property. We recommend using `undefined` instead.
-### Modal
+### Modal {/* #modal */}
`ion-modal` now uses the Shadow DOM. Update any styles targeting the internals of `ion-modal` to use either the [ion-modal CSS Variables](../api/modal#css-custom-properties) or the [ion-modal CSS Shadow Parts](../api/modal#css-shadow-parts):
@@ -364,7 +364,7 @@ ion-modal::part(backdrop) {
}
```
-### Popover
+### Popover {/* #popover */}
`ion-popover` now uses the Shadow DOM. Update any styles targeting the internals of `ion-popover` to use either [ion-popover CSS Variables](../api/popover#css-custom-properties) or the [ion-popover CSS Shadow Parts](../api/popover#css-shadow-parts):
@@ -400,19 +400,19 @@ ion-popover::part(content) {
}
```
-### Radio
+### Radio {/* #radio */}
Remove any usage of the `RadioChangeEventDetail` interface.
-### Select
+### Select {/* #select */}
Ensure `null` is not passed in as a value to the `placeholder` property. We recommend using `undefined` instead.
-### Textarea
+### Textarea {/* #textarea */}
Ensure `null` is not passed in as a value to the `placeholder` property. We recommend using `undefined` instead.
-### Browser Support
+### Browser Support {/* #browser-support */}
The list of browsers that Ionic supports has changed. Review the [Browser Support Guide](../reference/browser-support) to ensure you are deploying apps to supported browsers.
@@ -426,7 +426,7 @@ Safari >=13
iOS >=13
```
-### Testing
+### Testing {/* #testing */}
Ionic 6 now ships as ES Modules. ES Modules are supported in all major browsers and bring developer experience and code maintenance improvements. Developers testing with Jest will need to update their Jest configuration as Jest does not have full support for ES Modules as of Jest 27.
@@ -473,7 +473,7 @@ If you are still running into issues, here are a couple things to try:
2. If you have a `browserslist/test` field in `package.json` file, make sure it is set to `current node`.
-## Need Help Upgrading?
+## Need Help Upgrading? {/* #need-help-upgrading */}
Be sure to review the [Ionic 6 Breaking Changes Guide](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING_ARCHIVE/v6.md). There were several changes to default property and CSS Variable values that developers may need to be aware of. Only the breaking changes that required user action are listed on this page.
diff --git a/docs/updating/7-0.mdx b/docs/updating/7-0.mdx
index 2c4ae234f9..df7ab8f045 100644
--- a/docs/updating/7-0.mdx
+++ b/docs/updating/7-0.mdx
@@ -16,9 +16,9 @@ For a **complete list of breaking changes** from Ionic 6 to Ionic 7, please refe
:::
-## Getting Started
+## Getting Started {/* #getting-started */}
-### Angular
+### Angular {/* #angular */}
1. Ionic 7 supports Angular 14+. Update to the latest version of Angular by following the [Angular Update Guide](https://update.angular.io/).
2. If your project is using rxjs, Ionic 7 requires a minimum rxjs version of 7.5.0:
@@ -41,7 +41,7 @@ npm install @ionic/angular@7 @ionic/angular-server@7 @ionic/angular-toolkit@9
> Note: `@ionic/angular-toolkit@9` requires a minimum of Angular 15. If you are still on Angular 14, then you can skip updating to `@ionic/angular-toolkit@9`.
-### React
+### React {/* #react */}
1. Ionic 7 supports React 17+. Update to the latest version of React:
@@ -55,7 +55,7 @@ npm install react@latest react-dom@latest
npm install @ionic/react@7 @ionic/react-router@7
```
-### Vue
+### Vue {/* #vue */}
1. Ionic 7 supports Vue 3.0.6+. Update to the latest version of Vue:
@@ -69,7 +69,7 @@ npm install vue@latest vue-router@latest
npm install @ionic/vue@7 @ionic/vue-router@7
```
-### Core
+### Core {/* #core */}
1. Update to the latest version of Ionic 7:
@@ -77,9 +77,9 @@ npm install @ionic/vue@7 @ionic/vue-router@7
npm install @ionic/core@7
```
-## Updating Your Code
+## Updating Your Code {/* #updating-your-code */}
-### Browser Support
+### Browser Support {/* #browser-support */}
The list of browsers that Ionic supports has changed. Review the [Browser Support Guide](../reference/browser-support) to ensure you are deploying apps to supported browsers.
@@ -94,41 +94,41 @@ Safari >=14
iOS >=14
```
-### Types
+### Types {/* #types */}
1. `ActionSheetAttributes`, `AlertAttributes`, `AlertTextareaAttributes`, `AlertInputAttributes`, `LoadingAttributes`, `ModalAttributes`, `PickerAttributes`, `PopoverAttributes`, and `ToastAttributes` have been removed. Developers should use `{ [key: string]: any }` instead.
-### Checkbox
+### Checkbox {/* #checkbox */}
1. Rename any usages of the `--background` and `--background-checked` CSS Variables to `--checkbox-background` and `--checkbox-background-checked`, respectively.
-### Datetime
+### Datetime {/* #datetime */}
1. Remove any code that sets the `value` property to the empty string (`''`).
2. Remove any code that accesses the time zone information on the `value` property. Datetime does not manage time zones, so any time zone information provided is ignored.
-### Input
+### Input {/* #input */}
1. Update any code that accesses the `detail` payload for the `ionInput` event from `event.detail` to `event.detail.value` as the detail payload is now an object containing a value and an event.
-### Modal
+### Modal {/* #modal */}
1. Remove any usage of the `swipeToClose` property. Card modals are swipeable by default, so you can remove `swipeToClose` if you want your card modal to remain swipeable. Use the [canDismiss](https://ionicframework.com/docs/api/modal#preventing-a-modal-from-dismissing) property if you want to prevent a modal from dismissing.
2. Remove any code that sets the `canDismiss` property to `undefined`. The `canDismiss` property now defaults to `true`, so this code is no longer needed.
-### Picker
+### Picker {/* #picker */}
1. Remove any code that accesses `refresh` on `ion-picker-column`. Developers should use the `columns` property on `ion-picker` to refresh the view instead.
-### Searchbar
+### Searchbar {/* #searchbar */}
1. Update any code that accesses the `detail` payload for the `ionInput` event from `event.detail` to `event.detail.value` as the detail payload is now an object containing a value and an event.
-### Segment
+### Segment {/* #segment */}
1. Remove any code that sets the `value` property to `null`. Developers should use either `''` or `undefined` instead.
-### Slides
+### Slides {/* #slides */}
1. Remove `ion-slides`, `ion-slide`, and any associated types. These components have been removed in favor of using Swiper.js directly. The guides below contain more information about this migration:
@@ -136,15 +136,15 @@ iOS >=14
[React Migration Guide](https://ionicframework.com/docs/react/slides)
[Vue Migration Guide](https://ionicframework.com/docs/vue/slides)
-### Textarea
+### Textarea {/* #textarea */}
1. Update any code that accesses the `detail` payload for the `ionInput` event from `event.detail` to `event.detail.value` as the detail payload is now an object containing a value and an event.
-### Toggle
+### Toggle {/* #toggle */}
1. Rename any usages of the `--background` and `--background-checked` CSS Variables to `--track-background` and `--track-background-checked`, respectively.
-### Virtual Scroll
+### Virtual Scroll {/* #virtual-scroll */}
1. Remove `ion-virtual-scroll` and any associated types. This component has been removed in favor of using virtual scroll solutions provided by JavaScript Frameworks. The guides below contain more information about this migration:
@@ -152,7 +152,7 @@ iOS >=14
[React Migration Guide](https://ionicframework.com/docs/react/virtual-scroll)
[Vue Migration Guide](https://ionicframework.com/docs/vue/virtual-scroll)
-## Need Help Upgrading?
+## Need Help Upgrading? {/* #need-help-upgrading */}
Be sure to review the [Ionic 7 Breaking Changes Guide](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-7x). There were several changes to default property and CSS Variable values that developers may need to be aware of. Only the breaking changes that require user action are listed on this page.
diff --git a/docs/updating/8-0.mdx b/docs/updating/8-0.mdx
index f501b609e2..634da530d9 100644
--- a/docs/updating/8-0.mdx
+++ b/docs/updating/8-0.mdx
@@ -16,9 +16,9 @@ For a **complete list of breaking changes** from Ionic 7 to Ionic 8, please refe
:::
-## Getting Started
+## Getting Started {/* #getting-started */}
-### Angular
+### Angular {/* #angular */}
1. Ionic 8 supports Angular 16+. Update to the latest version of Angular by following the [Angular Update Guide](https://update.angular.io/).
@@ -38,7 +38,7 @@ npm install @ionic/angular@latest @ionic/angular-server@latest @ionic/angular-to
3. Update any `IonBackButtonDelegate` imports from `@ionic/angular` to import `IonBackButton` from `@ionic/angular` instead.
-### React
+### React {/* #react */}
1. Ionic 8 supports React 17+. Update to the latest version of React:
@@ -52,7 +52,7 @@ npm install react@17 react-dom@17
npm install @ionic/react@8 @ionic/react-router@8
```
-### Vue
+### Vue {/* #vue */}
1. Ionic 8 supports Vue 3.0.6+. Update to the latest version of Vue:
@@ -66,7 +66,7 @@ npm install vue@^3.0.6 vue-router@^3.0.6
npm install @ionic/vue@8 @ionic/vue-router@8
```
-### Core
+### Core {/* #core */}
1. Update to the latest version of Ionic 8:
@@ -74,11 +74,11 @@ npm install @ionic/vue@8 @ionic/vue-router@8
npm install @ionic/core@8
```
-## Recommended Changes
+## Recommended Changes {/* #recommended-changes */}
The following changes are not required to update to Ionic 8 as your application will continue to work. However, we recommend making the following changes to ensure you can use the new features in Ionic 8.
-### Light Palette
+### Light Palette {/* #light-palette */}
Previous versions defined a set of default color variables for the light palette in `theme/variables.scss`:
@@ -100,7 +100,7 @@ Developers who are customizing this color palette can continue to keep the custo
You can read more about the new color palette in the [Ionic v8 announcement](https://ionic.io/blog/announcing-the-ionic-8-beta).
-### Dark Palette
+### Dark Palette {/* #dark-palette */}
In previous versions, it was recommended to define the dark palette in the following way:
@@ -134,7 +134,7 @@ While migrating to include the new dark palette files is unlikely to cause break
For more information on the new dark palette files, refer to the [Dark Mode documentation](../theming/dark-mode).
-### Step Color Tokens
+### Step Color Tokens {/* #step-color-tokens */}
To better support the high contrast palette in Ionic 8, separate step colors tokens have been introduced for text and background color. Previously both text and background color were controlled by a single set of `--ion-color-step-[number]` tokens.
@@ -170,7 +170,7 @@ button { color: var(--ion-text-color-step-600); /* 1000 - 400 = 600 */ }
The [stepped color generator](../theming/themes#stepped-color-generator) has been updated to generate text and background color stepped variables.
-### Dynamic Font
+### Dynamic Font {/* #dynamic-font */}
The `core.css` file has been updated to enable dynamic font scaling by default.
@@ -182,7 +182,7 @@ Developers who want to disable dynamic font scaling can set `--ion-dynamic-font:
For more information on the dynamic font, refer to the [Dynamic Font Scaling documentation](../layout/dynamic-font-scaling).
-### (Angular Only) `angular.json` CSS import order
+### (Angular Only) `angular.json` CSS import order {/* #angular-only-angularjson-css-import-order */}
The `angular.json` file currently imports `src/theme/variables.scss` before importing `src/global.scss`. This may cause the incorrect styles to be applied when customizing the new [Dark Palette](#dark-palette) changes.
@@ -200,9 +200,9 @@ We recommend importing the `src/global.scss` file first instead:
"styles": ["src/global.scss", "src/theme/variables.scss"],
```
-## Required Changes
+## Required Changes {/* #required-changes */}
-### Browser Support
+### Browser Support {/* #browser-support */}
The list of browsers that Ionic supports has changed. Review the [Browser Support Guide](../reference/browser-support) to ensure you are deploying apps to supported browsers.
@@ -217,51 +217,51 @@ Safari >=15
iOS >=15
```
-### Checkbox
+### Checkbox {/* #checkbox */}
1. Migrate any remaining instances of Checkbox to use the [modern form control syntax](https://ionic-docs-mt82qcyb0-ionic1.vercel.app/docs/v7/api/checkbox#migrating-from-legacy-checkbox-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
-### Input
+### Input {/* #input */}
1. Remove any usages of the `size` property. CSS should be used to specify the visible width of the input instead.
2. Remove any usages of the `accept` property.
3. Migrate any remaining instances of Input to use the [modern form control syntax](https://ionic-docs-mt82qcyb0-ionic1.vercel.app/docs/v7/api/input#migrating-from-legacy-input-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
-### Item
+### Item {/* #item */}
1. Remove any usages of the `counter` or `counterFormatter` properties. Use the properties of the same names on `ion-input` and `ion-textarea` instead.
2. Remove any usages of the `helper` or `error` slots. Use the `helperText` and `errorText` properties on `ion-input` and `ion-textarea` instead.
3. Remove any usages of the `fill` or `shape` properties. Use the properties of the same names on `ion-input`, `ion-textarea`, and `ion-select` instead.
-### Nav
+### Nav {/* #nav */}
1. Update any usages of `getLength` to `await` the call before accessing the returned value as this method now returns `Promise` instead of `number`.
-### Picker
+### Picker {/* #picker */}
1. Ionic 8 now ships with an inline `ion-picker` component. Developers who wish to continue using the legacy picker should update any `ion-picker` usages to `ion-picker-legacy`. The `pickerController` import remains unchanged. Note that the `ion-picker-legacy` component will be removed in an upcoming major release of Ionic. Refer to the [Picker documentation](../api/picker) for usage information.
-### Toast
+### Toast {/* #toast */}
1. Remove any usages of the `cssClass` property from `ToastButton`. The `button` CSS Shadow Part should be used instead.
-### Radio
+### Radio {/* #radio */}
1. Migrate any remaining instances of Radio to use the [modern form control syntax](https://ionic-docs-mt82qcyb0-ionic1.vercel.app/docs/v7/api/radio#migrating-from-legacy-radio-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
-### Select
+### Select {/* #select */}
1. Migrate any remaining instances of Select to use the [modern form control syntax](https://ionic-docs-mt82qcyb0-ionic1.vercel.app/docs/v7/api/select#migrating-from-legacy-select-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
-### Textarea
+### Textarea {/* #textarea */}
1. Migrate any remaining instances of Textarea to use the [modern form control syntax](https://ionic-docs-mt82qcyb0-ionic1.vercel.app/docs/v7/api/textarea#migrating-from-legacy-textarea-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
-### Toggle
+### Toggle {/* #toggle */}
1. Migrate any remaining instances of Toggle to use the [modern form control syntax](https://ionic-docs-mt82qcyb0-ionic1.vercel.app/docs/v7/api/toggle#migrating-from-legacy-toggle-syntax). Additionally, remove any usages of the `legacy` property as the legacy form control syntax has been removed.
-## Need Help Upgrading?
+## Need Help Upgrading? {/* #need-help-upgrading */}
Be sure to review the [Ionic 8 Breaking Changes Guide](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-8x). There were several changes to default property and CSS Variable values that developers may need to be aware of. Only the breaking changes that require user action are listed on this page.
diff --git a/docs/updating/9-0.mdx b/docs/updating/9-0.mdx
index 88a4a542c4..d70fbb75c0 100644
--- a/docs/updating/9-0.mdx
+++ b/docs/updating/9-0.mdx
@@ -16,7 +16,7 @@ For a **complete list of breaking changes** from Ionic 8 to Ionic 9, please refe
:::
-## Automated Migration
+## Automated Migration {/* #automated-migration */}
Before manually working through the changes below, you can run the Ionic migration tool. It scans your app, automatically applies the breaking changes that can be safely migrated, and prints a checklist of the remaining updates that require manual work. Each item includes the affected file, line number, and a link to the corresponding section of this guide. Because the tool reads your framework and version from `package.json`, it only applies migrations that are relevant to your app.
@@ -45,9 +45,9 @@ Run `npx @ionic/migrate --help` for the full list.
The tool is single-shot. Once it bumps your `@ionic/*` version, a re-run detects the new major and does nothing, so run it once per major upgrade and review the diff before committing.
-## Getting Started
+## Getting Started {/* #getting-started */}
-### Angular
+### Angular {/* #angular */}
1. Ionic 9 supports Angular 18 through 22. Angular 16 and 17 are no longer supported. Update to a supported version of Angular by following the [Angular Update Guide](https://update.angular.io/).
@@ -63,7 +63,7 @@ If you are using Ionic Angular Server and Ionic Angular Toolkit, be sure to upda
npm install @ionic/angular@latest @ionic/angular-server@latest @ionic/angular-toolkit@latest
```
-#### Zoneless Change Detection
+#### Zoneless Change Detection {/* #zoneless-change-detection */}
Ionic 9 supports zoneless change detection. Angular 21 made zoneless the default, so a new Ionic 9 app on Angular 21 or later runs without Zone.js out of the box and no change-detection provider is required.
@@ -75,7 +75,7 @@ On Angular 18 through 20, Zone.js remains Angular's default, so those versions a
:::
-##### Keeping Zone.js
+##### Keeping Zone.js {/* #keeping-zonejs */}
If you prefer to keep using Zone.js on Angular 21 or later, opt back in with `provideZoneChangeDetection()`.
@@ -121,7 +121,7 @@ If your project uses a polyfills file instead (for example, Ionic starters set `
import 'zone.js';
```
-#### OnPush Change Detection on Angular 22
+#### OnPush Change Detection on Angular 22 {/* #onpush-change-detection-on-angular-22 */}
Angular 22 changes the default change detection strategy to `OnPush` for components that don't declare one. Combined with the zoneless default above, component state you mutate as a plain field from an Ionic lifecycle hook (`ionViewWillEnter`, and so on) no longer re-renders on its own.
@@ -148,23 +148,23 @@ Ionic's own Angular components already declare `OnPush`, so they are unaffected.
:::
-#### TypeScript
+#### TypeScript {/* #typescript */}
Ionic 9 supports TypeScript 5.4 or later, matching the minimum for Angular 18. Angular 21 requires TypeScript 5.9 or later, and Angular 22 requires TypeScript 6.0 or later.
-#### Node.js
+#### Node.js {/* #nodejs */}
Angular 22 raises the minimum Node.js version to `^22.22.3 || ^24.15.0 || ^26.0.0`. Angular 18 through 21 are unaffected.
-#### Component Imports
+#### Component Imports {/* #component-imports */}
Ionic 9 makes standalone components the default import path. Change lazy-loaded component imports from `@ionic/angular` to `@ionic/angular/lazy`. Change standalone component imports from `@ionic/angular/standalone` to `@ionic/angular`.
-#### IonicModule Deprecation
+#### IonicModule Deprecation {/* #ionicmodule-deprecation */}
`IonicModule` is deprecated in Ionic 9 and will be removed in a future major version. It remains fully functional, so no immediate action is required. When you are ready, migrate to `provideIonicAngular()`, which works in both standalone and NgModule-based apps. Refer to [Migrating from Modules to Standalone](/angular/build-options.mdx#migrating-from-modules-to-standalone).
-#### CSS Imports
+#### CSS Imports {/* #css-imports */}
Remove the `~` prefix from `@ionic/angular` CSS imports. Angular's current build pipeline no longer supports the webpack-loader prefix:
@@ -173,11 +173,11 @@ Remove the `~` prefix from `@ionic/angular` CSS imports. Angular's current build
+ @import '@ionic/angular/css/core.css';
```
-#### Module Resolution
+#### Module Resolution {/* #module-resolution */}
If your app uses TypeScript `moduleResolution: "node"` (classic), imports from subpaths such as `@ionic/angular/lazy` can fail to resolve. Set `moduleResolution` to `"bundler"` in your `tsconfig.json`. Apps created with `ng new` on Angular 17 or later already use this.
-### React
+### React {/* #react */}
1. Ionic 9 supports React 18+. Update to the latest version of React:
@@ -195,7 +195,7 @@ npm install @ionic/react@latest @ionic/react-router@latest
The `@ionic/react` package requires TypeScript 5.4 or later. Its type definitions use `NoInfer`, which TypeScript added in 5.4.
-#### Typed Overlay Hook Props
+#### Typed Overlay Hook Props {/* #typed-overlay-hook-props */}
The `useIonModal` and `useIonPopover` hooks now type `componentProps` against the component they are given, instead of accepting `any`. Passing props that do not match the component is a compile error, and `componentProps` is required when the component declares required props:
@@ -227,7 +227,7 @@ Running the [migration tool](#automated-migration) with `npx @ionic/migrate --ex
Passing a JSX element rather than a component behaves as before: props are bound to the element and `componentProps` is not type checked.
-### React Router
+### React Router {/* #react-router */}
1. Ionic 9 supports React Router 6. Update to version 6 of React Router:
@@ -243,7 +243,7 @@ npm uninstall @types/react-router @types/react-router-dom
Ionic React now requires React Router v6, which has a different API from v5. Below are the key changes you'll need to make.
-#### Route Definition Changes
+#### Route Definition Changes {/* #route-definition-changes */}
The `component` and `render` props have been replaced with the `element` prop, which accepts JSX:
@@ -261,7 +261,7 @@ Routes can no longer render content via nested children. All route content must
+ } />
```
-#### Redirect Changes
+#### Redirect Changes {/* #redirect-changes */}
The `` component has been replaced with ``:
@@ -273,7 +273,7 @@ The `` component has been replaced with ``:
+
```
-#### Nested Route Paths
+#### Nested Route Paths {/* #nested-route-paths */}
Routes that contain nested routes or child `IonRouterOutlet` components need a `/*` suffix to match sub-paths:
@@ -282,7 +282,7 @@ Routes that contain nested routes or child `IonRouterOutlet` components need a `
+ } />
```
-#### Accessing Route Parameters
+#### Accessing Route Parameters {/* #accessing-route-parameters */}
Route parameters are now accessed via the `useParams` hook instead of props:
@@ -296,7 +296,7 @@ Route parameters are now accessed via the `useParams` hook instead of props:
+ const { id } = useParams<{ id: string }>();
```
-#### RouteComponentProps Removed
+#### RouteComponentProps Removed {/* #routecomponentprops-removed */}
The `RouteComponentProps` type and its `history`, `location`, and `match` props are no longer available in React Router v6. Use the equivalent hooks instead:
@@ -325,7 +325,7 @@ The `RouteComponentProps` type and its `history`, `location`, and `match` props
+ console.log(location.pathname);
```
-#### Exact Prop Removed
+#### Exact Prop Removed {/* #exact-prop-removed */}
The `exact` prop is no longer needed. React Router v6 routes match exactly by default. To match sub-paths, use a `/*` suffix on the path:
@@ -334,7 +334,7 @@ The `exact` prop is no longer needed. React Router v6 routes match exactly by de
+
```
-#### Render Prop Removed
+#### Render Prop Removed {/* #render-prop-removed */}
The `render` prop has been replaced with the `element` prop:
@@ -343,7 +343,7 @@ The `render` prop has been replaced with the `element` prop:
+ } />
```
-#### Programmatic Navigation
+#### Programmatic Navigation {/* #programmatic-navigation */}
The `useHistory` hook has been replaced with `useNavigate`:
@@ -366,7 +366,7 @@ The `useHistory` hook has been replaced with `useNavigate`:
+ router.goBack();
```
-#### Custom History Prop Removed
+#### Custom History Prop Removed {/* #custom-history-prop-removed */}
The `history` prop has been removed from `IonReactRouter`, `IonReactHashRouter`, and `IonReactMemoryRouter`. React Router v6 routers no longer accept custom `history` objects.
@@ -386,7 +386,7 @@ For `IonReactMemoryRouter` (commonly used in tests), use `initialEntries` instea
+
```
-#### IonRedirect Removed
+#### IonRedirect Removed {/* #ionredirect-removed */}
The `IonRedirect` component has been removed. Use React Router's `` component instead:
@@ -397,7 +397,7 @@ The `IonRedirect` component has been removed. Use React Router's `` co
+ } />
```
-#### Path Regex Constraints Removed
+#### Path Regex Constraints Removed {/* #path-regex-constraints-removed */}
React Router v6 no longer supports regex constraints in path parameters (e.g., `/:tab(sessions)`). Use literal paths instead:
@@ -408,7 +408,7 @@ React Router v6 no longer supports regex constraints in path parameters (e.g., `
+ } />
```
-#### IonRoute API Changes
+#### IonRoute API Changes {/* #ionroute-api-changes */}
The `IonRoute` component follows the same API changes as React Router's ``. The `render` prop has been replaced with `element`, and the `exact` prop has been removed:
@@ -419,7 +419,7 @@ The `IonRoute` component follows the same API changes as React Router's `
For more information on migrating from React Router v5 to v6, refer to the [React Router v6 Upgrade Guide](https://reactrouter.com/6.28.0/upgrading/v5).
-### Vue
+### Vue {/* #vue */}
1. Ionic 9 supports Vue 3.5+. Update to the latest version of Vue:
@@ -433,7 +433,7 @@ npm install vue@latest
npm install @ionic/vue@latest @ionic/vue-router@latest
```
-### Vue Router
+### Vue Router {/* #vue-router */}
1. Ionic 9 supports Vue Router 5. Update to the latest version of Vue Router:
@@ -445,7 +445,7 @@ npm install vue-router@5
Vue Router v5 is a transition release that ships no runtime breaking changes for Vue Router v4 consumers, so no application code changes are required for routes, navigation guards, or `IonRouterOutlet`.
-#### Deprecation Warning for `next()` in Navigation Guards
+#### Deprecation Warning for `next()` in Navigation Guards {/* #deprecation-warning-for-next-in-navigation-guards */}
Vue Router v5 prints a deprecation warning when `next()` is called inside `beforeRouteLeave`, `beforeRouteEnter`, `beforeRouteUpdate`, or `router.beforeEach`. The callback form still works, but Vue Router v6 will remove it. Migrate to the return-value pattern:
@@ -472,7 +472,7 @@ Vue Router v5 prints a deprecation warning when `next()` is called inside `befor
For more information on migrating from Vue Router v4 to v5, refer to the [Vue Router v4-to-v5 migration guide](https://router.vuejs.org/guide/migration/v4-to-v5.html).
-### Core
+### Core {/* #core */}
1. Update to the latest version of Ionic 9:
@@ -480,7 +480,7 @@ For more information on migrating from Vue Router v4 to v5, refer to the [Vue Ro
npm install @ionic/core@latest
```
-#### Package Exports
+#### Package Exports {/* #package-exports */}
`@ionic/core`'s `package.json` now declares an `exports` field. This fixes subpaths like `@ionic/core/components` and `@ionic/core/loader` failing under Node ESM with `ERR_UNSUPPORTED_DIR_IMPORT`. The strict ESM resolver doesn't read the nested `package.json` files the package previously relied on, and the `exports` field replaces them. This affects toolchains such as Angular 21's default Vitest builder and raw Node.
@@ -497,9 +497,9 @@ The `exports` field defines the supported public entry points, and imports of pa
Apps on `moduleResolution: "node"` (classic) and webpack 4 keep resolving through the legacy fields and need no changes.
-## Required Changes
+## Required Changes {/* #required-changes */}
-### Browser Support
+### Browser Support {/* #browser-support */}
The list of browsers that Ionic supports has changed. Review the [Browser Support Guide](../reference/browser-support) to ensure you are deploying apps to supported browsers.
@@ -514,13 +514,13 @@ Safari >=16
iOS >=16
```
-### Capacitor
+### Capacitor {/* #capacitor */}
Ionic 9 officially supports Capacitor 7 and later. Native platform detection no longer falls back to the Capacitor 2 `isNative` flag; `isCapacitorNative` now relies solely on `Capacitor.isNativePlatform()`, which was added in Capacitor 3.
If your app is still on Capacitor 2, it will no longer be detected as running on a native platform, so `isPlatform('capacitor')`, `isPlatform('hybrid')`, and `getPlatforms()` will report `web` instead of native. Upgrade to Capacitor 7 or later by following the [Capacitor updating guides](https://capacitorjs.com/docs/updating/7-0).
-### Img
+### Img {/* #img */}
`ion-img` is deprecated and will be removed in Ionic 10. The component was created to lazy-load images before browsers supported lazy loading natively. Modern browsers now support the [`loading="lazy"`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/img#loading) attribute on the native `![]()
` element, so the component is no longer needed.
@@ -531,7 +531,7 @@ Replace `ion-img` with a native `![]()
` tag. Add `loading="lazy"` for lazy loadi
+ 
```
-#### Events
+#### Events {/* #events */}
The native `![]()
` element does not emit Ionic's custom events. Use the standard DOM events instead:
@@ -543,7 +543,7 @@ The native `![]()
` element does not emit Ionic's custom events. Use the standard
¹ Native `load` and `error` do not bubble, while the Ionic events did. If you used event delegation (one listener on a parent), listen on each `![]()
` instead, or use the capture phase: `parent.addEventListener('load', handler, true)`.
-#### Styling
+#### Styling {/* #styling */}
`ion-img` exposed an `image` CSS shadow part for styling the inner image. With a native `![]()
`, style the element directly instead:
@@ -556,7 +556,7 @@ The native `![]()
` element does not emit Ionic's custom events. Use the standard
+ }
```
-### Input
+### Input {/* #input */}
#### `autocorrect` Property Type Changed to Boolean {/* #input-autocorrect-property-type-changed-to-boolean */}
@@ -604,7 +604,7 @@ Update your selectors to account for these structural changes:
+ion-input .input-end [slot="end"] { }
```
-### Legacy Picker
+### Legacy Picker {/* #legacy-picker */}
The `ion-picker-legacy` and `ion-picker-legacy-column` components have been removed.
@@ -612,9 +612,9 @@ The `ion-picker-legacy` and `ion-picker-legacy-column` components have been remo
- Remove any usages of `pickerController`. If using React, remove any usages of the `useIonPicker` hook. These controller-based APIs have been removed. Use the [Picker](../api/picker.mdx) component instead.
- Remove any usages of the `PickerOptions`, `PickerButton`, `PickerColumn`, and `PickerColumnOption` type exports. These types were associated with the legacy picker and have been removed.
-### Modal
+### Modal {/* #modal */}
-#### `handleBehavior` Default Changed
+#### `handleBehavior` Default Changed {/* #handlebehavior-default-changed */}
The `handleBehavior` property on `ion-modal` now defaults to `"cycle"` instead of `"none"`. For sheet modals that display a handle, this means the handle is now focusable and activating it (by click, keyboard, or screen reader) cycles the sheet through its available breakpoints. This matches the native iOS sheet behavior and keeps sheet modals operable for assistive technology users by default.
@@ -624,9 +624,9 @@ Sheet modals that relied on the handle being inert should set `handleBehavior="n
```
-### Nav
+### Nav {/* #nav */}
-#### Router Integration Removed
+#### Router Integration Removed {/* #router-integration-removed */}
`ion-nav` no longer integrates with `ion-router`. It is now a standalone imperative stack navigation component, driven only through its own API (`root`, `push`, `pop`, `setRoot`, and so on) and `ion-nav-link`.
@@ -652,11 +652,11 @@ If you relied on `ion-nav` to update the URL, use `ion-router-outlet` for URL-ba
An `ion-nav` can still be nested inside a routed page for local, URL-less stack navigation. It manages its own stack via `root` and `ion-nav-link`, and the URL never changes as you push and pop. For a complete, working example, refer to [Using ion-nav within a Routed Page](../api/router.mdx#using-ion-nav-within-a-routed-page).
-### Router Outlet
+### Router Outlet {/* #router-outlet */}
`ion-router-outlet` now exposes a `swipeGesture` property that controls the swipe-to-go-back gesture per outlet. This property defaults to `true` in `"ios"` mode and `false` in `"md"` mode.
-#### `swipeBackEnabled` Config Behavior Change
+#### `swipeBackEnabled` Config Behavior Change {/* #swipebackenabled-config-behavior-change */}
In React and Vue, the `swipeBackEnabled` config option is now read once when the outlet mounts. Apps that dynamically toggle this config value at runtime should migrate to the `swipeGesture` property instead.
@@ -674,7 +674,7 @@ In React and Vue, the `swipeBackEnabled` config option is now read once when the
+
```
-#### Disabling Swipe-to-Go-Back
+#### Disabling Swipe-to-Go-Back {/* #disabling-swipe-to-go-back */}
To disable the gesture on a specific outlet, set `swipeGesture` to `false`:
@@ -684,7 +684,7 @@ To disable the gesture on a specific outlet, set `swipeGesture` to `false`:
The `swipeBackEnabled` config option is still respected as the initial default and does not need to change for apps that set it once at startup.
-### Searchbar
+### Searchbar {/* #searchbar */}
#### `autocorrect` Property Type Changed to Boolean {/* #searchbar-autocorrect-property-type-changed-to-boolean */}
@@ -693,15 +693,15 @@ The `autocorrect` property on `ion-searchbar` is now a `boolean` (default `false
- Remove the attribute to keep autocorrect disabled (the default).
- Use a property binding to enable it: `[autocorrect]="true"` (Angular), `autocorrect={true}` (React), or `:autocorrect="true"` (Vue).
-### Select
+### Select {/* #select */}
-#### `ionChange` Only Fires When the Value Changes
+#### `ionChange` Only Fires When the Value Changes {/* #ionchange-only-fires-when-the-value-changes */}
The `ionChange` event on `ion-select` now only fires when the selected value actually changes. Previously, the `alert` and `action-sheet` interfaces emitted `ionChange` every time the overlay was confirmed, even when the user chose the option that was already selected. This aligns the `alert` and `action-sheet` interfaces with the existing behavior of the `popover` and `modal` interfaces, and with the documented contract of `ionChange`.
Apps that relied on `ionChange` firing on every confirmation (for example, to detect overlay dismissal without a value change) should listen for `ionDismiss` instead, or use the `didDismiss` event on the underlying alert or action sheet.
-#### Action Sheet Interface `selected` Role Removed
+#### Action Sheet Interface `selected` Role Removed {/* #action-sheet-interface-selected-role-removed */}
When using `interface="action-sheet"`, `ion-select` no longer assigns the `selected` role to the action sheet button for the currently selected option. This aligns the `action-sheet` interface with the `alert`, `popover`, and `modal` interfaces, none of which assign this role. This does not change the selected option's styling.
@@ -743,7 +743,7 @@ If you target `part="label"`, `part="container"`, or `part="icon"`, the part nam
Use the new `part="start"`, `part="control"`, and `part="end"` parts to target the new structural wrappers.
-### Textarea
+### Textarea {/* #textarea */}
#### Floating Label Behavior {/* #textarea-floating-label-behavior */}
@@ -782,7 +782,7 @@ Update your selectors to account for these structural changes:
+ion-textarea .textarea-end [slot="end"] { }
```
-#### Minimum Height Change
+#### Minimum Height Change {/* #minimum-height-change */}
The minimum height of textarea in Material Design (`md` mode) is now `72px`. At the default number of rows this makes textareas the same height regardless of the `fill` property or `labelPlacement`. Previously the minimum height was:
@@ -805,7 +805,7 @@ ion-textarea.custom {
}
```
-## Need Help Upgrading?
+## Need Help Upgrading? {/* #need-help-upgrading */}
Be sure to look at the [Ionic 9 Breaking Changes Guide](https://github.com/ionic-team/ionic-framework/blob/main/BREAKING.md#version-9x) for the complete list of breaking changes. This upgrade guide only covers changes that require action from developers.
diff --git a/docs/utilities/animations.mdx b/docs/utilities/animations.mdx
index 427e7528a3..1bce09671a 100644
--- a/docs/utilities/animations.mdx
+++ b/docs/utilities/animations.mdx
@@ -14,7 +14,7 @@ import TabItem from '@theme/TabItem';
/>
-## Overview
+## Overview {/* #overview */}
Ionic Animations is a tool that enables developers to create complex animations in a platform-agnostic manner, without requiring a specific framework or an Ionic app.
@@ -22,7 +22,7 @@ Creating efficient animations can be challenging, as developers are limited by t
Ionic Animations, on the other hand, uses the [Web Animations API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API), which offloads all the computation and running of animations to the browser. This approach allows the browser to optimize the animations and ensure their smooth execution. In cases where Web Animations are not supported, Ionic Animations will fall back to [CSS Animations](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Animations/Using_CSS_animations), which should have a negligible difference in performance.
-## Installation
+## Installation {/* #installation */}
````mdx-code-block
````
-## Basic Animations
+## Basic Animations {/* #basic-animations */}
In the example below, an animation that changes the opacity on the `ion-card` element and moves it from left to right along the X axis has been created. This animation will run an infinite number of times, and each iteration of the animation will last 1500ms.
@@ -166,7 +166,7 @@ import Basic from '@site/static/usage/v9/animations/basic/index.mdx';
-## Keyframe Animations
+## Keyframe Animations {/* #keyframe-animations */}
Ionic Animations allows you to control the intermediate steps in an animation using keyframes. Any valid CSS property can be used here, and you can even use CSS Variables as values.
@@ -180,7 +180,7 @@ In the example above, the card element will transition from its initial width, t
Each keyframe object contains an `offset` property. `offset` is a value between 0 and 1 that defines the keyframe step. Offset values must go in ascending order and cannot repeat.
-## Grouped Animations
+## Grouped Animations {/* #grouped-animations */}
Multiple elements can be animated at the same time and controlled via a single parent animation object. Child animations inherit properties such as duration, easing, and iterations unless otherwise specified. A parent animation's `onFinish` callback will not be called until all child animations have completed.
@@ -190,7 +190,7 @@ import Group from '@site/static/usage/v9/animations/group/index.mdx';
-## Before and After Hooks
+## Before and After Hooks {/* #before-and-after-hooks */}
Ionic Animations provides hooks that let you alter an element before an animation runs and after an animation completes. These hooks can be used to perform DOM reads and writes as well as add or remove classes and inline styles.
@@ -202,7 +202,7 @@ import BeforeAndAfterHooks from '@site/static/usage/v9/animations/before-and-aft
-## Chained Animations
+## Chained Animations {/* #chained-animations */}
Animations can be chained to run one after the other. The `play` method returns a Promise that resolves when the animation has completed.
@@ -210,7 +210,7 @@ import Chain from '@site/static/usage/v9/animations/chain/index.mdx';
-## Gesture Animations
+## Gesture Animations {/* #gesture-animations */}
Ionic Animations gives developers the ability to create powerful gesture-based animations by integrating seamlessly with [Ionic Gestures](gestures.mdx).
@@ -220,7 +220,7 @@ import Gesture from '@site/static/usage/v9/animations/gesture/index.mdx';
-## Preference-Based Animations
+## Preference-Based Animations {/* #preference-based-animations */}
Developers can also tailor their animations to user preferences such as `prefers-reduced-motion` and `prefers-color-scheme` using CSS Variables.
@@ -232,17 +232,17 @@ import PreferenceBased from '@site/static/usage/v9/animations/preference-based/i
-## Overriding Ionic Component Animations
+## Overriding Ionic Component Animations {/* #overriding-ionic-component-animations */}
Certain Ionic components allow developers to provide custom animations. All animations are provided as either properties on the component or are set via a global config.
-### Modals
+### Modals {/* #modals */}
import ModalOverride from '@site/static/usage/v9/animations/modal-override/index.mdx';
-## Performance Considerations
+## Performance Considerations {/* #performance-considerations */}
CSS and Web Animations are usually handled on the compositor thread. This is different than the main thread where layout, painting, styling, and your JavaScript is executed. It is recommended that you prefer using properties that can be handled on the compositor thread for optimal animation performance.
@@ -250,7 +250,7 @@ Animating properties such as `height` and `width` cause additional layouts and p
For information on which CSS properties cause layouts or paints to occur, refer to [CSS Triggers](https://csstriggers.com/).
-## Debugging
+## Debugging {/* #debugging */}
For debugging animations in Chrome, there is a great blog post about inspecting animations using the Chrome DevTools: https://developers.google.com/web/tools/chrome-devtools/inspect-styles/animations.
@@ -267,25 +267,25 @@ const animation = createAnimation('my-animation-identifier')
.fromTo('opacity', '1', '0');
```
-## API
+## API {/* #api */}
This section provides a list of all the methods and properties available on the `Animation` class.
-### Interfaces
+### Interfaces {/* #interfaces */}
-#### AnimationDirection
+#### AnimationDirection {/* #animationdirection */}
```tsx
type AnimationDirection = 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
```
-#### AnimationFill
+#### AnimationFill {/* #animationfill */}
```tsx
type AnimationFill = 'auto' | 'none' | 'forwards' | 'backwards' | 'both';
```
-#### AnimationBuilder
+#### AnimationBuilder {/* #animationbuilder */}
```tsx
type AnimationBuilder = (baseEl: any, opts?: any) => Animation;
@@ -297,7 +297,7 @@ type AnimationBuilder = (baseEl: any, opts?: any) => Animation;
:::
-#### AnimationCallbackOptions
+#### AnimationCallbackOptions {/* #animationcallbackoptions */}
```tsx
interface AnimationCallbackOptions {
@@ -308,7 +308,7 @@ interface AnimationCallbackOptions {
}
```
-#### AnimationPlayOptions
+#### AnimationPlayOptions {/* #animationplayoptions */}
```tsx
interface AnimationPlayOptions {
@@ -321,7 +321,7 @@ interface AnimationPlayOptions {
}
```
-### Properties
+### Properties {/* #properties */}
| Name | Description |
| ------------------------------ | ------------------------------------------------- |
@@ -329,7 +329,7 @@ interface AnimationPlayOptions {
| `elements: HTMLElement[]` | All elements attached to an animation. |
| `parentAnimation?: Animation` | The parent animation of a given animation object. |
-### Methods
+### Methods {/* #methods */}
| Name | Description |
| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
diff --git a/docs/utilities/gestures.mdx b/docs/utilities/gestures.mdx
index 10ade49d77..a5955acc66 100644
--- a/docs/utilities/gestures.mdx
+++ b/docs/utilities/gestures.mdx
@@ -14,13 +14,13 @@ import TabItem from '@theme/TabItem';
/>
-## Overview
+## Overview {/* #overview */}
Ionic Gestures is a utility that allows developers to build custom gestures and interactions for their application in a platform agnostic manner. Developers do not need to be using a particular framework such as React or Angular, nor do they even need to be building an Ionic app! As long as developers have access to v5.0 or greater of Ionic Framework, they will have access to all of Ionic Gestures.
Building complex gestures can be time consuming. Other libraries that provide custom gestures are often times too heavy handed and end up capturing mouse or touch events and not letting them propagate. This can result in other elements no longer being scrollable or clickable.
-## Installation
+## Installation {/* #installation */}
````mdx-code-block
````
-## Basic Gestures
+## Basic Gestures {/* #basic-gestures */}
import Basic from '@site/static/usage/v9/gestures/basic/index.mdx';
@@ -168,7 +168,7 @@ In this example, our app listens for gestures on the `ion-content` element. When
-## Double Click Gesture
+## Double Click Gesture {/* #double-click-gesture */}
import DoubleClick from '@site/static/usage/v9/gestures/double-click/index.mdx';
@@ -176,19 +176,19 @@ In the example below, we want to be able to detect double clicks on an element.
-## Gesture Animations
+## Gesture Animations {/* #gesture-animations */}
See our guide on implementing gesture animations: [Gesture Animations with Ionic Animations](animations.mdx#gesture-animations)
-## Types
+## Types {/* #types */}
| Name | Value |
| ----------------- | -------------------------------------------- |
| `GestureCallback` | `(detail: GestureDetail) => boolean \| void` |
-## Interfaces
+## Interfaces {/* #interfaces */}
-### GestureConfig
+### GestureConfig {/* #gestureconfig */}
| Property | Type | Default | Description |
| --------------- | ------------------------------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -208,7 +208,7 @@ See our guide on implementing gesture animations: [Gesture Animations with Ionic
| onEnd | `GestureCallback \| undefined` | `undefined` | A callback that fires when a gesture has ended. This is usually when a pointer has been released. |
| notCaptured | `GestureCallback \| undefined` | `undefined` | A callback that fires when a gesture has not been captured. This usually happens when there is a conflicting gesture with a higher priority. |
-### GestureDetail
+### GestureDetail {/* #gesturedetail */}
| Property | Type | Description |
| -------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -226,12 +226,12 @@ See our guide on implementing gesture animations: [Gesture Animations with Ionic
| event | `UIEvent` | The native event dispatched by the browser. Refer to [UIEvent](https://developer.mozilla.org/en-US/docs/Web/API/UIEvent) for more information. |
| data | `any \| undefined` | Any data specified by the user. This can be set and read in any of the callbacks. |
-## Methods
+## Methods {/* #methods */}
-#### `enable(enable: boolean = true) => void`
+#### `enable(enable: boolean = true) => void` {/* #enableenable-boolean--true--void */}
Enable or disable the gesture.
-#### `destroy() => void`
+#### `destroy() => void` {/* #destroy--void */}
Destroy the gesture instance and stop listening on the target element.
diff --git a/docs/vue/add-to-existing.mdx b/docs/vue/add-to-existing.mdx
index d47b18d21d..863fdd2358 100644
--- a/docs/vue/add-to-existing.mdx
+++ b/docs/vue/add-to-existing.mdx
@@ -22,7 +22,7 @@ This guide uses JavaScript examples. If you're using TypeScript, the setup proce
:::
-## Setup
+## Setup {/* #setup */}
:::info
@@ -32,13 +32,13 @@ This guide follows the structure of a Vue app created with `create-vue` (which u
Follow these steps to add Ionic Vue to your existing Vue project:
-#### 1. Install the Packages
+#### 1. Install the Packages {/* #1-install-the-packages */}
```bash
npm install @ionic/vue @ionic/vue-router vue-router
```
-#### 2. Configure Ionic Vue
+#### 2. Configure Ionic Vue {/* #2-configure-ionic-vue */}
Update `src/main.js` to include `IonicVue` and import the required Ionic Framework stylesheets:
@@ -65,7 +65,7 @@ While `core.css` is required, `normalize.css`, `structure.css`, and `typography.
:::
-## Using Individual Components
+## Using Individual Components {/* #using-individual-components */}
After completing the setup above, you can start using Ionic components in your existing Vue app. Here's an example of how to use them:
@@ -84,11 +84,11 @@ import { IonButton, IonDatetime } from '@ionic/vue';
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 */}
Update the imported stylesheets in `src/main.js`:
@@ -112,7 +112,7 @@ import '@ionic/vue/css/display.css';
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:
@@ -164,7 +164,7 @@ createApp(App).use(IonicVue).mount('#app');
The `variables.css` file can be used to create custom Ionic Framework themes. The `dark.system.css` import enables [dark mode support](/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 to `theme/variables.css`.
-#### 3. Update the App Component
+#### 3. Update the App Component {/* #3-update-the-app-component */}
Update `src/App.vue` to the following:
@@ -180,7 +180,7 @@ import { IonApp, IonRouterOutlet } from '@ionic/vue';
```
-#### 4. Create a Home Page
+#### 4. Create a Home Page {/* #4-create-a-home-page */}
Create a new file at `src/views/HomePage.vue` with the following:
@@ -248,7 +248,7 @@ import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/vue
```
-#### 5. Set up Routing
+#### 5. Set up Routing {/* #5-set-up-routing */}
Add a file at `src/router/index.js` defining the routes:
@@ -324,7 +324,7 @@ router.isReady().then(() => {
You're all set! Your Ionic Vue app is now configured with full Ionic page support. Run `npm run dev` to start your development server and view your app.
-## Next Steps
+## Next Steps {/* #next-steps */}
Now that you have Ionic Vue integrated into your project, check out:
diff --git a/docs/vue/build-options.mdx b/docs/vue/build-options.mdx
index ef4a6eb018..327936877e 100644
--- a/docs/vue/build-options.mdx
+++ b/docs/vue/build-options.mdx
@@ -16,9 +16,9 @@ import DocsCards from '@components/global/DocsCards';
Vue gives you several tools to fine tune your application. This guide covers the build options that are most relevant to Ionic Framework.
-## Component Registration Strategies
+## Component Registration Strategies {/* #component-registration-strategies */}
-### Local Component Registration (Recommended)
+### Local Component Registration (Recommended) {/* #local-component-registration-recommended */}
By default, Ionic Framework components are registered locally. With local registration, these components are imported and provided to each Vue component you want to use them in. This is the recommended approach as it allows lazy loading and treeshaking to work properly with Ionic Framework components.
@@ -49,7 +49,7 @@ Note that since we are registering these components locally, neither `IonPage` n
For more information, refer to the [Local Registration Vue Documentation](https://v3.vuejs.org/guide/component-registration.html#local-registration).
-### Global Component Registration
+### Global Component Registration {/* #global-component-registration */}
The other option for registering components is to use global registration. Global registration involves importing the components you want to use in `main.ts` and calling the `component` method on your Vue app instance.
@@ -88,9 +88,9 @@ In the example above, we are using the `IonPage` and `IonContent` components. To
For more information, refer to the [Global Registration Vue Documentation](https://v3.vuejs.org/guide/component-registration.html#global-registration).
-## Build Optimization
+## Build Optimization {/* #build-optimization */}
-### Prefetching Application JavaScript
+### Prefetching Application JavaScript {/* #prefetching-application-javascript */}
By default, the Vue CLI will automatically generate prefetch hints for the JavaScript in your application. Prefetching utilizes the browser idle time to download documents that the user might visit in the near future. When the user visits a page that requires the prefetched document, it can be served quickly from the browser's cache.
diff --git a/docs/vue/lifecycle.mdx b/docs/vue/lifecycle.mdx
index 3b701321ea..1b84568b3e 100644
--- a/docs/vue/lifecycle.mdx
+++ b/docs/vue/lifecycle.mdx
@@ -6,7 +6,7 @@ sidebar_label: Lifecycle
This guide discusses how to use the Ionic Framework Lifecycle events in an Ionic Vue application.
-## Ionic Framework Lifecycle Methods
+## Ionic Framework Lifecycle Methods {/* #ionic-framework-lifecycle-methods */}
Ionic Framework provides a few lifecycle methods that you can use in your apps:
@@ -43,7 +43,7 @@ const ionViewWillLeave = () => {
```
-### Composition API Hooks
+### Composition API Hooks {/* #composition-api-hooks */}
These lifecycles can also be expressed using Vue 3's Composition API:
@@ -75,7 +75,7 @@ Pages in your app need to be using the `IonPage` component in order for lifecycl
:::
-## How Ionic Framework Handles the Life of a Page
+## How Ionic Framework Handles the Life of a Page {/* #how-ionic-framework-handles-the-life-of-a-page */}
Ionic Framework has its router outlet, called ``. This outlet extends Vue Router's `` with some additional functionality to enable better experiences for mobile devices.
@@ -90,7 +90,7 @@ Because of this special handling, certain Vue Router components such as ` = [
In our redirect, we look for the index path of our app. Then if we load that, we redirect to the `home` route.
-## Navigating to Different Routes
+## Navigating to Different Routes {/* #navigating-to-different-routes */}
This is all great, but how does one actually navigate to a route? For this, we can use the `router-link` property. Let's create a new routing setup:
@@ -122,7 +122,7 @@ const router = useRouter();
Both options provide the same navigation mechanism, just fitting different use cases.
-### Navigating using `router-link`
+### Navigating using `router-link` {/* #navigating-using-router-link */}
The `router-link` attribute can be set on any Ionic Vue component, and the router will navigate to the route specified when the component is clicked. The `router-link` attribute accepts string values as well as named routes, just like `router.push` from Vue Router. For additional control, the `router-direction` and `router-animation` attributes can be set as well.
@@ -134,7 +134,7 @@ The `router-animation` attribute accepts an `AnimationBuilder` function and is u
Click Me
```
-### Navigating using `useIonRouter`
+### Navigating using `useIonRouter` {/* #navigating-using-useionrouter */}
One downside of using `router-link` is that you cannot run custom code prior to navigating. This makes tasks such as firing off a network request prior to navigation difficult. You could use Vue Router directly, but then you lose the ability to control the page transition. This is where the `useIonRouter` utility is helpful.
@@ -170,7 +170,7 @@ The example above has the app navigate to `/page2` with a custom animation that
Refer to the [useIonRouter documentation](./utility-functions#router) for more details as well as type information.
-### Navigating using `router.go`
+### Navigating using `router.go` {/* #navigating-using-routergo */}
Vue Router has a [router.go](https://router.vuejs.org/api/#go) method that allows developers to move forward or backward through the application history. Let's walk through an example.
@@ -182,7 +182,7 @@ If you were to call `router.go(-2)` on `/pageC`, you would be brought back to `/
A key characteristic of `router.go()` is that it expects your application history to be linear. This means that `router.go()` 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 */}
The current way our routes are setup makes it so they are included in the same initial chunk when loading the app, which is not always ideal. Instead, we can set up our routes so that components are loaded as they are needed:
@@ -207,9 +207,9 @@ const routes: Array = [
Here, we have the same setup as before only this time `DetailPage` has been replaced with an import call. This will result in the `DetailPage` component no longer being part of the chunk that is requested on application load.
-## 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.
@@ -233,7 +233,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.
@@ -261,7 +261,7 @@ If tapping the back button simply called `router.go(-1)` from the `Ted Lasso` vi
Non-linear routing allows for sophisticated user flows that linear routing cannot handle. However, certain linear routing APIs such as `router.go()` cannot be used in this non-linear environment. This means that `router.go()` 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.
@@ -271,11 +271,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:
@@ -294,7 +294,7 @@ const routes: Array = [
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:
@@ -319,7 +319,7 @@ const routes: Array = [
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.
@@ -327,7 +327,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 */}
When working with tabs, Ionic Vue needs a way to know which view belongs to which tab. The `IonTabs` component comes in handy here, but let's examine the routing setup for this:
@@ -399,7 +399,7 @@ import { ellipse, square, triangle } from 'ionicons/icons';
If you have worked with Ionic Framework before, this should feel familiar. We create an `ion-tabs` component and provide an `ion-tab-bar`. The `ion-tab-bar` provides `ion-tab-button` components, each with a `tab` property that is associated with its corresponding tab in the router config. We also provide an `ion-router-outlet` to give `ion-tabs` an outlet to render the different tab views in.
-### 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).
@@ -407,7 +407,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`.
@@ -446,7 +446,7 @@ const routes: Array = [
];
```
-### 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.
@@ -484,15 +484,15 @@ The example below shows how the Spotify app reuses the same album component to s
| :-------------------------------------------------: | :---------------------------------------------------: |
| | |
-## Components
+## Components {/* #components */}
-### IonRouterOutlet
+### IonRouterOutlet {/* #ionrouteroutlet */}
The `IonRouterOutlet` component provides a container to render your views in. It is similar to the `RouterView` component found in other Vue applications except that `IonRouterOutlet` can render multiple pages in the DOM in the same outlet. When a component is rendered in `IonRouterOutlet` we consider this to be an Ionic Framework "page". The router outlet container controls the transition animation between the pages as well as controls when a page is created and destroyed. This helps maintain the state between the views when switching back and forth between them.
Nothing should be provided inside of `IonRouterOutlet` when setting it up in your template. While `IonRouterOutlet` can be nested in child components, we caution against it as it typically makes navigation in apps confusing. Refer to [Shared URLs versus Nested Routes](#shared-urls-versus-nested-routes) for more information.
-### IonPage
+### IonPage {/* #ionpage */}
The `IonPage` component wraps each view in an Ionic Vue app and allows page transitions and stack navigation to work properly. Each view that is navigated to using the router must include an `IonPage` component.
@@ -517,9 +517,9 @@ import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/vue
Components presented via `IonModal` or `IonPopover` do not typically need an `IonPage` component unless you need a wrapper element. In that case, we recommend using `IonPage` so that the component dimensions are still computed properly.
-## Functions
+## Functions {/* #functions */}
-### useIonRouter
+### useIonRouter {/* #useionrouter */}
▸ **useIonRouter**(): [`UseIonRouterResult`](utility-functions#useionrouterresult)
@@ -527,7 +527,7 @@ Returns the Ionic router instance, containing API methods for navigating, custom
For example usages, please refer to our [Utility Functions](utility-functions#useionrouter).
-## URL Parameters
+## URL Parameters {/* #url-parameters */}
Let's expand upon our original routing example to show how we can use URL parameters. We recommend [passing URL parameters as props](https://router.vuejs.org/guide/essentials/passing-props.html) so that the component does not need a direct reference to the router, which makes it easier to reuse and test in isolation.
@@ -577,7 +577,7 @@ defineProps<{ id: string }>();
The `id` parameter from the URL is received as a prop and rendered on the screen. The component has no dependency on the router itself.
-## Router History
+## Router History {/* #router-history */}
Vue Router ships with a configurable history mode. Let's go over the different options and why you might want to use each one.
@@ -587,6 +587,6 @@ Vue Router ships with a configurable history mode. Let's go over the different o
- `createMemoryHistory`: This option creates an in-memory based history. This is mainly used to handle server-side rendering (SSR).
-## More Information
+## More Information {/* #more-information */}
For more info on routing in Vue using Vue Router, check out the [Vue Router documentation](https://router.vuejs.org/).
diff --git a/docs/vue/overview.mdx b/docs/vue/overview.mdx
index 06bbb5624a..f04a8cb412 100644
--- a/docs/vue/overview.mdx
+++ b/docs/vue/overview.mdx
@@ -16,21 +16,21 @@ import DocsCards from '@components/global/DocsCards';
`@ionic/vue` brings the full power of the Ionic Framework to Vue developers. It offers seamless integration with the Vue ecosystem, so you can build high-quality cross-platform apps using familiar Vue tools, components, and best practices. You also get access to Ionic's extensive UI library and native capabilities.
-## Vue Version Support
+## Vue Version Support {/* #vue-version-support */}
Ionic Vue v9 supports Vue 3.5 and later. For detailed information on supported versions and our support policy, refer to the [Ionic Vue Support Policy](/reference/support.mdx#ionic-vue).
-## Vue Tooling
+## Vue Tooling {/* #vue-tooling */}
Ionic Vue projects use the same tooling as standard Vue CLI projects, so you can take advantage of the full Vue CLI feature set for building, testing, and deploying your apps. Starter projects come with useful features enabled by default, such as Vue Router for navigation and TypeScript support for type safety and improved developer experience.
-## Native Tooling
+## Native Tooling {/* #native-tooling */}
[Capacitor](https://capacitorjs.com) is the official cross-platform runtime for Ionic Vue, enabling your apps to run natively on iOS, Android, and the web with a single codebase.
While you can use many [Cordova](https://cordova.apache.org/) plugins with Ionic Vue, Capacitor is the recommended and fully supported solution. The [Ionic CLI](../cli.mdx) does not provide official Cordova integration for Ionic Vue projects. For more information on using Cordova plugins with Capacitor, refer to the [Capacitor documentation](https://capacitorjs.com/docs/cordova).
-## Installation
+## Installation {/* #installation */}
```shell-session
$ npm install -g @ionic/cli
@@ -40,7 +40,7 @@ $ cd myApp
$ ionic serve █
```
-## Resources
+## Resources {/* #resources */}
diff --git a/docs/vue/performance.mdx b/docs/vue/performance.mdx
index ecbc734424..1fd79c268e 100644
--- a/docs/vue/performance.mdx
+++ b/docs/vue/performance.mdx
@@ -5,7 +5,7 @@ sidebar_label: Performance
# Vue Performance
-## v-for with Ionic Components
+## v-for with Ionic Components {/* #v-for-with-ionic-components */}
When using `v-for` with Ionic components, we recommend using Vue's `key` attribute. This allows Vue to re-render loop elements in an efficient way by only updating the content inside of the component rather than re-creating the component altogether.
diff --git a/docs/vue/platform.mdx b/docs/vue/platform.mdx
index d1fc625812..0b401cbce8 100644
--- a/docs/vue/platform.mdx
+++ b/docs/vue/platform.mdx
@@ -5,7 +5,7 @@ sidebar_label: Platform
# Platform
-## isPlatform
+## isPlatform {/* #isplatform */}
The `isPlatform` method can be used to test if your app is running on a certain platform:
@@ -17,7 +17,7 @@ isPlatform('ios'); // returns true when running on a iOS device
Depending on the platform the user is on, isPlatform(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.
-## getPlatforms
+## getPlatforms {/* #getplatforms */}
The `getPlatforms` method can be used to determine which platforms your app is currently running on.
@@ -29,7 +29,7 @@ getPlatforms(); // returns ["iphone", "ios", "mobile", "mobileweb"] from an iPho
Depending on what device you are on, `getPlatforms` can return multiple values. Each possible value is a hierarchy of platforms. For example, on an iPhone, it would return mobile, ios, and iphone.
-## Platforms
+## Platforms {/* #platforms */}
Below is a table listing all the possible platform values along with corresponding descriptions.
@@ -50,7 +50,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.
diff --git a/docs/vue/pwa.mdx b/docs/vue/pwa.mdx
index 5f82dc39eb..777f79d8f9 100644
--- a/docs/vue/pwa.mdx
+++ b/docs/vue/pwa.mdx
@@ -11,7 +11,7 @@ sidebar_label: Progressive Web Apps
/>
-## Making your Vue app a PWA with Vite
+## Making your Vue app a PWA with Vite {/* #making-your-vue-app-a-pwa-with-vite */}
The two main requirements of a PWA are a [Service Worker](https://developers.google.com/web/fundamentals/primers/service-workers/) and a [Web Application Manifest](https://developers.google.com/web/fundamentals/web-app-manifest/). While it's possible to add both of these to an app manually, we recommend using the [Vite PWA Plugin](https://vite-pwa-org.netlify.app/) instead.
@@ -39,7 +39,7 @@ For more information on configuring the Vite PWA Plugin, refer to the [Vite PWA
Refer to the [Vite PWA "Deploy" Guide](https://vite-pwa-org.netlify.app/deployment/) for information on how to deploy your PWA.
-## Making your Vue app a PWA with Vue CLI
+## Making your Vue app a PWA with Vue CLI {/* #making-your-vue-app-a-pwa-with-vue-cli */}
:::note
@@ -111,7 +111,7 @@ The service worker that is generated is based on [Workbox's webpack plugin](http
If you want to configure this and change the default behavior, checkout the [PWA plugin docs](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-pwa#configuration) on GitHub.
-### Manifest
+### Manifest {/* #manifest */}
In addition to the service worker, the Vue PWA plugin also is responsible for creating a manifest file for your app as well. By default, the CLI will generate a manifest that contains the following entries.
@@ -152,11 +152,11 @@ In addition to the service worker, the Vue PWA plugin also is responsible for cr
Be sure to update the icons in `public/img/icons` to match your own brand. If you wanted to customize the theme color or name, be sure to read the [PWA plugin docs](https://github.com/vuejs/vue-cli/tree/dev/packages/%40vue/cli-plugin-pwa#configuration) on GitHub.
-### Deploying
+### Deploying {/* #deploying */}
You can use various hosts like Firebase, Vercel, Netlify, or even Azure Static Web Apps. All will have similar setup processes that need to be completed. For this guide, Firebase will be used as the hosting example. In addition to this guide, the [Vue CLI docs](https://cli.vuejs.org/guide/deployment.html) also have a guide on how to deploy to various providers.
-#### 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/vue/quickstart.mdx b/docs/vue/quickstart.mdx
index 662f393d58..9be48c4edb 100644
--- a/docs/vue/quickstart.mdx
+++ b/docs/vue/quickstart.mdx
@@ -18,7 +18,7 @@ Welcome! This guide will walk you through the basics of Ionic Vue development. Y
If you're looking for a high-level overview of what Ionic Vue is and how it fits into the Vue ecosystem, refer to the [Ionic Vue 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):
@@ -51,7 +51,7 @@ After running `ionic serve`, your project will open in the browser.
-## Explore the Project Structure
+## Explore the Project Structure {/* #explore-the-project-structure */}
Your new app's directory will look like this:
@@ -73,7 +73,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.vue`:
@@ -91,7 +91,7 @@ import { IonApp, IonRouterOutlet } from '@ionic/vue';
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 `router/index.ts`:
@@ -122,7 +122,7 @@ export default router;
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 `HomePage.vue`, imports the Ionic components and defines the page template:
@@ -170,7 +170,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`:
@@ -190,7 +190,7 @@ import { IonButton, IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from
```
-## Add a New Page
+## Add a New Page {/* #add-a-new-page */}
Create a new page at `NewPage.vue`:
@@ -229,7 +229,7 @@ When creating your own pages, always use `ion-page` as the root component. This
:::
-## Navigate to the New Page
+## Navigate to the New Page {/* #navigate-to-the-new-page */}
To navigate to the new page, create a route for it by first importing it at the top of `router/index.ts` after the `HomePage` import:
@@ -270,7 +270,7 @@ Navigating can also be performed programmatically using Vue Router, and routes c
:::
-## Add Icons to the New Page
+## Add Icons to the New Page {/* #add-icons-to-the-new-page */}
Ionic Vue comes with [Ionicons](https://ionic.io/ionicons/) pre-installed. You can use any icon by setting the `icon` property of the `ion-icon` component.
@@ -294,7 +294,7 @@ Note that we are passing the imported SVG reference, **not** the icon name as a
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.
@@ -349,7 +349,7 @@ This pattern is necessary because Ionic components are built as Web 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):
@@ -368,7 +368,7 @@ ionic cap open android
Refer to [Capacitor's Getting Started guide](https://capacitorjs.com/docs/getting-started/with-ionic) for more.
-## Build with TypeScript or JavaScript
+## Build with TypeScript or JavaScript {/* #build-with-typescript-or-javascript */}
Ionic Vue projects are created with TypeScript by default, but you can easily convert to JavaScript if you prefer. After generating a blank Ionic Vue app, follow these steps:
@@ -394,7 +394,7 @@ npm uninstall --save typescript @types/jest @typescript-eslint/eslint-plugin @ty
9. Install terser `npm i -D terser`.
-## Explore More
+## Explore More {/* #explore-more */}
This guide covered the basics of creating an Ionic Vue app, adding navigation, and introducing Capacitor for native builds. To dive deeper, check out:
diff --git a/docs/vue/slides.mdx b/docs/vue/slides.mdx
index 926a2f1215..d1f46dc27e 100644
--- a/docs/vue/slides.mdx
+++ b/docs/vue/slides.mdx
@@ -26,7 +26,7 @@ Using Swiper's Vue component is **not** required to use Swiper.js with Ionic Fra
:::
-## Getting Started
+## Getting Started {/* #getting-started */}
First, update to the latest version of Ionic:
@@ -46,7 +46,7 @@ Once that is done, install the Swiper dependency in your project:
npm install swiper@latest
```
-## Swiping with Style
+## Swiping with Style {/* #swiping-with-style */}
Next, we need to import the base Swiper styles. We are also going to import the styles that Ionic provides which will let us customize the Swiper styles using the same CSS Variables that we used with `ion-slides`.
@@ -65,7 +65,7 @@ Importing `@ionic/vue/css/ionic-swiper.css` is **not** required to use Swiper.js
:::
-### Updating Selectors
+### Updating Selectors {/* #updating-selectors */}
Previously, we were able to target `ion-slides` and `ion-slide` to apply any custom styling. The contents of those style blocks remain the same, but we need to update the selectors. Below is a list of selector changes when going from `ion-slides` to Swiper Vue:
@@ -74,7 +74,7 @@ Previously, we were able to target `ion-slides` and `ion-slide` to apply any cus
| `ion-slides` | `.swiper` |
| `ion-slide` | `.swiper-slide` |
-### Pre-processors (optional)
+### Pre-processors (optional) {/* #pre-processors-optional */}
For developers using SCSS or Less styles, Swiper also provides imports for those files.
@@ -92,7 +92,7 @@ import 'swiper/scss';
import '@ionic/vue/css/ionic-swiper.css';
```
-## Using Components
+## Using Components {/* #using-components */}
Swiper exports two components: `Swiper` and `SwiperSlide`. The `Swiper` component is the equivalent of `IonSlides`, and `SwiperSlide` is the equivalent of `IonSlide`.
@@ -120,7 +120,7 @@ import '@ionic/vue/css/ionic-swiper.css';
```
-## Using Modules
+## Using Modules {/* #using-modules */}
By default, Swiper for Vue does not import any additional modules. To use modules such as Navigation or Pagination, you need to import them first.
@@ -223,7 +223,7 @@ Refer to [Swiper's Vue usage documentation](https://swiperjs.com/vue#usage) for
:::
-## 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.
@@ -266,7 +266,7 @@ The `IonicSlides` module must be the last module in the array. This will let it
:::
-## Properties
+## Properties {/* #properties */}
Swiper options are provided as props directly on the `` component rather than via the `options` object in `ion-slides`.
@@ -309,7 +309,7 @@ All properties available in Swiper Vue can be found in the [Swiper Vue props doc
:::
-## Events
+## Events {/* #events */}
Since the `Swiper` component is not provided by Ionic Framework, event names will not have an `ionSlide` prefix to them.
@@ -364,7 +364,7 @@ All events available in Swiper Vue can be found in the [Swiper Vue events docume
:::
-## Methods
+## Methods {/* #methods */}
Most methods have been removed in favor of accessing the `` props directly. Additionally, you no longer need to access `$el` first when calling methods.
@@ -403,7 +403,7 @@ Below is a full list of method changes when going from `ion-slides` to Swiper Vu
| `startAutoplay()` | Use the `autoplay` property instead. |
| `stopAutoplay()` | Use the `autoplay` property instead. |
-## Effects
+## Effects {/* #effects */}
If you are using effects such as Cube or Fade, you can install them just like we did with the other modules. In this example, we will use the fade effect. To start, we will import `EffectFade` from `swiper` and provide it in the `modules` array:
@@ -491,21 +491,21 @@ For more information on effects in Swiper, please refer to the [Swiper Vue effec
:::
-## 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 Vue Introduction](https://swiperjs.com/vue) 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/vue/storage.mdx b/docs/vue/storage.mdx
index 5a0b18e959..f75fade9a1 100644
--- a/docs/vue/storage.mdx
+++ b/docs/vue/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-vue/blob/main/demos/sqlcipher-kv-pair/src/composables/mobile-kv-store.ts)
- [Web Service](https://github.com/ionic-enterprise/tutorials-and-demos-vue/blob/main/demos/sqlcipher-kv-pair/src/composables/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/vue/testing.mdx b/docs/vue/testing.mdx
index f285dce721..25e870fc28 100644
--- a/docs/vue/testing.mdx
+++ b/docs/vue/testing.mdx
@@ -12,9 +12,9 @@ title: Testing
This document provides an overview of how to test an application built with `@ionic/vue`. Applications generated with the Ionic CLI are set up for unit testing with [Vitest](https://vitest.dev) and [Vue Test Utils](https://test-utils.vuejs.org), and for end-to-end testing with [Cypress](https://www.cypress.io).
-## Unit Testing
+## Unit Testing {/* #unit-testing */}
-### Waiting for Components
+### Waiting for Components {/* #waiting-for-components */}
When you need to wait for an Ionic component to render before asserting against its DOM, use the `componentOnReady` helper exported from `@ionic/core`. Do not call `el.componentOnReady()` directly. `@ionic/vue` uses Stencil's custom elements build, where that method does not exist on the element. The helper waits one animation frame instead, giving the component's inner contents a chance to render.
diff --git a/docs/vue/troubleshooting.mdx b/docs/vue/troubleshooting.mdx
index 9e38bc58bb..cfd789eb78 100644
--- a/docs/vue/troubleshooting.mdx
+++ b/docs/vue/troubleshooting.mdx
@@ -14,7 +14,7 @@ This guide covers some of the more common issues you may run into when developin
Have an issue that you think should be covered here? [Let us know!](https://github.com/ionic-team/ionic-docs/issues/new?assignees=&labels=content&template=content-issue.md&title=)
-## Failed to resolve component
+## Failed to resolve component {/* #failed-to-resolve-component */}
```shell
[Vue warn]: Failed to resolve component: ion-button
@@ -38,7 +38,7 @@ import { IonButton } from '@ionic/vue';
Prefer to register your components globally once? We have you covered. Our [Build Options Guide](/vue/build-options.mdx#global-component-registration) shows you how to register Ionic Vue components globally as well as the potential downsides to be aware of when using this approach.
-## Slot attributes are deprecated
+## Slot attributes are deprecated {/* #slot-attributes-are-deprecated */}
```shell
`slot` attributes are deprecated vue/no-deprecated-slot-attribute
@@ -60,7 +60,7 @@ If you are using VSCode and have the Vetur plugin installed, you are likely gett
To resolve this issue, you will need to turn off Vetur's template validation with `vetur.validation.template: false`. Refer to the [Vetur Linting Guide](https://vuejs.github.io/vetur/guide/linting-error.html#linting) for more information.
-## Method on component is not a function
+## Method on component is not a function {/* #method-on-component-is-not-a-function */}
In order to access a method on an Ionic Framework component in Vue, you will need to access the underlying Web Component instance first:
@@ -76,7 +76,7 @@ In other framework integrations such as Ionic React, this is not needed as any `
Refer to the [Quickstart Guide](/vue/quickstart.mdx#call-component-methods) for more information.
-## Page transitions are not working
+## Page transitions are not working {/* #page-transitions-are-not-working */}
In order for page transitions to work correctly, each page must have an `ion-page` component at the root:
@@ -99,7 +99,7 @@ import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar } from '@ionic/vue
Refer to the [IonPage documentation](navigation.mdx#ionpage) for more information.
-## Ionic events bound in JavaScript are not firing
+## Ionic events bound in JavaScript are not firing {/* #ionic-events-bound-in-javascript-are-not-firing */}
When creating event listeners in JavaScript (i.e. `addEventListener`), event names should be written as kebab-case:
@@ -117,7 +117,7 @@ await modal.present();
This is done to align with how developers bind events in their Vue templates by using kebab-case: https://vuejs.org/guide/essentials/component-basics.html#case-insensitivity
-## Blank white screen in Capacitor native build
+## Blank white screen in Capacitor native build {/* #blank-white-screen-in-capacitor-native-build */}
If your app runs correctly in the browser but shows a blank white screen when launched in a Capacitor iOS or Android build, the most common cause is a non-default `base` in `vite.config.js` (or `publicPath` in `vue.config.js` for legacy Vue CLI projects).
diff --git a/docs/vue/utility-functions.mdx b/docs/vue/utility-functions.mdx
index 60004dfd99..6993064013 100644
--- a/docs/vue/utility-functions.mdx
+++ b/docs/vue/utility-functions.mdx
@@ -13,17 +13,17 @@ sidebar_label: Utility Functions
Ionic Vue ships with several utility functions that you can use in your application to make certain tasks easier such as managing the on-screen keyboard and the hardware back button.
-## Router
+## Router {/* #router */}
-### Functions
+### Functions {/* #functions */}
-#### useIonRouter
+#### useIonRouter {/* #useionrouter */}
▸ **useIonRouter**(): [`UseIonRouterResult`](#useionrouterresult)
Returns the Ionic router instance, containing API methods for navigating, customizing page transitions and routing context for native features. This function can be used in combination with the [`useRouter`](https://router.vuejs.org/api/index.html#userouter) from Vue.
-##### Customizing Page Transitions
+##### Customizing Page Transitions {/* #customizing-page-transitions */}
```js
import { IonPage, useIonRouter } from '@ionic/vue';
@@ -38,7 +38,7 @@ const back = () => {
};
```
-##### Back Navigation
+##### Back Navigation {/* #back-navigation */}
You may want to know if you are at the root page of the application when a user presses the hardware back button on Android.
@@ -53,9 +53,9 @@ if (ionRouter.canGoBack()) {
For additional APIs with Vue routing, please refer to the [Vue Router documentation](https://router.vuejs.org/api/index.html).
-### Interfaces
+### Interfaces {/* #interfaces */}
-#### UseIonRouterResult
+#### UseIonRouterResult {/* #useionrouterresult */}
```ts
import { AnimationBuilder } from '@ionic/vue';
@@ -84,7 +84,7 @@ useIonRouter(): UseIonRouterResult;
Refer to the [Vue Navigation Documentation](./navigation#navigating-using-useionrouter) for more usage examples.
-## Hardware Back Button
+## Hardware Back Button {/* #hardware-back-button */}
The `useBackButton` function can be used to register a callback function to fire whenever the hardware back button on Android is pressed. Additionally it accepts a priority parameter, allowing developers to customize which handler fires first if multiple handlers are registered.
@@ -98,7 +98,7 @@ useBackButton(10, () => {
});
```
-### Interfaces
+### Interfaces {/* #interfaces-1 */}
```ts
type Handler = (processNextHandler: () => void) => Promise | void | null;
@@ -117,7 +117,7 @@ The `useBackButton` callback will only fire when your app is running in Capacito
:::
-## Keyboard
+## Keyboard {/* #keyboard */}
The `useKeyboard` function returns an object that contains the state of the on-screen keyboard. This object provides information such as whether or not the on-screen keyboard is presented and what the height of the keyboard is in pixels. This information is provided in a Vue `ref` so it will be reactive in your application.
@@ -132,7 +132,7 @@ watch(keyboardHeight, () => {
});
```
-### Interfaces
+### Interfaces {/* #interfaces-2 */}
```ts
interface UseKeyboardResult {
@@ -146,7 +146,7 @@ useKeyboard(): UseKeyboardResult;
Refer to the [Keyboard Documentation](../developing/keyboard) for more information and usage examples.
-## Ionic Lifecycles
+## Ionic Lifecycles {/* #ionic-lifecycles */}
Ionic Vue provides several lifecycle hooks for the `setup()` function to tap into the Ionic Framework page lifecycle.
diff --git a/docs/vue/virtual-scroll.mdx b/docs/vue/virtual-scroll.mdx
index e38a7a7470..1dac1b6895 100644
--- a/docs/vue/virtual-scroll.mdx
+++ b/docs/vue/virtual-scroll.mdx
@@ -6,7 +6,7 @@
:::
-## Installation
+## Installation {/* #installation */}
To setup the virtual scroller, first install `vue-virtual-scroller`:
@@ -25,11 +25,11 @@ From here, we need to import the virtual scroller's CSS into our app. In `main.t
import 'vue-virtual-scroller/dist/vue-virtual-scroller.css';
```
-## Registering Virtual Scroll Components
+## Registering Virtual Scroll Components {/* #registering-virtual-scroll-components */}
Now that we have the package installed and the CSS imported, we can either import all virtual scroll components or only import the components we want to use. This guide will show how to do both.
-### Installing all Components
+### Installing all Components {/* #installing-all-components */}
To install all virtual scroll components for use your app, add the following import to `main.ts`:
@@ -51,7 +51,7 @@ Installing all components may result in unused virtual scroll components being a
:::
-### Installing Specific Components
+### Installing Specific Components {/* #installing-specific-components */}
To install specific virtual scroll components for use in your app, import the component you want to use in `main.ts`. In this example, we will be using the `RecycleScroller` component:
@@ -67,7 +67,7 @@ app.component('RecycleScroller', RecycleScroller);
After doing this, we will be able to use the `RecycleScroller` component in our app.
-## Usage
+## Usage {/* #usage */}
This example will use the `RecycleScroller` component which only renders the visible items in your list. Other components such as `DynamicScroller` can be used when you do not know the size of the items in advance.
@@ -111,7 +111,7 @@ Now that our template is setup, we need to add some CSS to size the virtual scro
}
```
-## 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.
@@ -129,6 +129,6 @@ For example:
```
-## Further Reading
+## Further Reading {/* #further-reading */}
This guide only covers a small portion of what `vue-virtual-scroller` is capable of. For more details, please refer to the [vue-virtual-scroller documentation](https://github.com/Akryum/vue-virtual-scroller/blob/next/packages/vue-virtual-scroller/README.md).
diff --git a/docs/vue/your-first-app.mdx b/docs/vue/your-first-app.mdx
index 0cc59b68e5..9bccc51235 100644
--- a/docs/vue/your-first-app.mdx
+++ b/docs/vue/your-first-app.mdx
@@ -24,7 +24,7 @@ Here’s the finished app running on all 3 platforms:
allowFullScreen
>
-## 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.
@@ -36,7 +36,7 @@ Highlights include:
Find the [complete app code](https://github.com/ionic-team/tutorial-photo-gallery-vue) 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:
@@ -46,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:
@@ -68,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 Vue app that uses the "Tabs" starter template and adds Capacitor for native functionality:
@@ -90,7 +90,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).
@@ -128,7 +128,7 @@ router.isReady().then(() => {
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:
@@ -138,7 +138,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/vue/your-first-app/2-taking-photos.mdx b/docs/vue/your-first-app/2-taking-photos.mdx
index 051055075c..4aafcf8da8 100644
--- a/docs/vue/your-first-app/2-taking-photos.mdx
+++ b/docs/vue/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 Gallery Composable
+## Photo Gallery Composable {/* #photo-gallery-composable */}
We will create a standalone composition method paired with [Vue's Composition API](https://v3.vuejs.org/guide/composition-api-introduction.html#why-composition-api) to manage the photos for the gallery.
@@ -89,7 +89,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 `usePhotoGallery.ts` file, immediately after the `usePhotoGallery()` method definition.
diff --git a/docs/vue/your-first-app/3-saving-photos.mdx b/docs/vue/your-first-app/3-saving-photos.mdx
index 1d8e539c26..b8a7855d17 100644
--- a/docs/vue/your-first-app/3-saving-photos.mdx
+++ b/docs/vue/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 `usePhotoGallery()` method in `usePhotoGallery.ts`.
diff --git a/docs/vue/your-first-app/4-loading-photos.mdx b/docs/vue/your-first-app/4-loading-photos.mdx
index 9884db3c6f..42888976f1 100644
--- a/docs/vue/your-first-app/4-loading-photos.mdx
+++ b/docs/vue/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 `usePhotoGallery.ts` and begin by defining a constant variable that will act as the key for the store.
diff --git a/docs/vue/your-first-app/5-adding-mobile.mdx b/docs/vue/your-first-app/5-adding-mobile.mdx
index 99c283cb9f..ee5e2a966f 100644
--- a/docs/vue/your-first-app/5-adding-mobile.mdx
+++ b/docs/vue/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.
@@ -33,7 +33,7 @@ import { isPlatform } from '@ionic/vue';
// ...existing code...
```
-## 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/vue/your-first-app/6-deploying-mobile.mdx b/docs/vue/your-first-app/6-deploying-mobile.mdx
index e5656eab56..4128b26e3e 100644
--- a/docs/vue/your-first-app/6-deploying-mobile.mdx
+++ b/docs/vue/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
-## 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/vue/your-first-app/7-live-reload.mdx b/docs/vue/your-first-app/7-live-reload.mdx
index d3448c34b2..214a6735b2 100644
--- a/docs/vue/your-first-app/7-live-reload.mdx
+++ b/docs/vue/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/vue/your-first-app/8-distribute.mdx b/docs/vue/your-first-app/8-distribute.mdx
index 85361db62e..80bfed67fe 100644
--- a/docs/vue/your-first-app/8-distribute.mdx
+++ b/docs/vue/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/package-lock.json b/package-lock.json
index 50aaa18c9a..1626038a55 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -12,6 +12,7 @@
"@docusaurus/core": "^3.10.2",
"@docusaurus/faster": "^3.10.2",
"@docusaurus/preset-classic": "^3.10.2",
+ "@docusaurus/utils": "^3.10.2",
"@floating-ui/react": "^0.27.20",
"@ionic-internal/ionic-ds": "^8.0.0",
"@mdx-js/react": "^3.1.1",
diff --git a/package.json b/package.json
index eeae038389..afec9cf311 100644
--- a/package.json
+++ b/package.json
@@ -43,6 +43,7 @@
"@docusaurus/core": "^3.10.2",
"@docusaurus/faster": "^3.10.2",
"@docusaurus/preset-classic": "^3.10.2",
+ "@docusaurus/utils": "^3.10.2",
"@floating-ui/react": "^0.27.20",
"@ionic-internal/ionic-ds": "^8.0.0",
"@mdx-js/react": "^3.1.1",
diff --git a/scripts/cli.mjs b/scripts/cli.mjs
index 83f1f29018..e74aca181a 100644
--- a/scripts/cli.mjs
+++ b/scripts/cli.mjs
@@ -1,4 +1,5 @@
import { writeFileSync } from 'fs';
+import { writeMarkdownHeadingId } from '@docusaurus/utils';
import * as utils from './utils.mjs';
import cliJSON from './data/cli.json' with { type: 'json' };
import cliOverrides from './data/meta-override.json' with { type: 'json' };
@@ -28,8 +29,9 @@ function writePage(page) {
].join('');
const path = `cli/commands/${commandToKebab(page.name)}.mdx`;
- writeFileSync(`docs/${path}`, data);
- writeFileSync(`versioned_docs/version-v8/${path}`, data);
+ const content = writeMarkdownHeadingId(data, { syntax: 'mdx-comment' });
+ writeFileSync(`docs/${path}`, content);
+ writeFileSync(`versioned_docs/version-v8/${path}`, content);
}
function renderFrontmatter({ name, groups }) {
diff --git a/scripts/native.mjs b/scripts/native.mjs
index 1ed5c009d2..fad838bcc4 100644
--- a/scripts/native.mjs
+++ b/scripts/native.mjs
@@ -1,4 +1,5 @@
import { writeFileSync } from 'fs';
+import { writeMarkdownHeadingId } from '@docusaurus/utils';
const tag = 'latest';
@@ -32,7 +33,9 @@ const pluginApis = [
async function buildPluginApiDocs(pluginId) {
const [readme, pkgJson] = await Promise.all([getReadme(pluginId), getPkgJsonData(pluginId)]);
- const apiContent = createApiPage(pluginId, readme, pkgJson);
+ const apiContent = writeMarkdownHeadingId(createApiPage(pluginId, readme, pkgJson), {
+ syntax: 'mdx-comment',
+ });
const fileName = `${pluginId}.mdx`;
writeFileSync(`docs/native/${fileName}`, apiContent);