diff --git a/core/package-lock.json b/core/package-lock.json index 1d22447d8f..e6e2ea0381 100644 --- a/core/package-lock.json +++ b/core/package-lock.json @@ -6,10 +6,10 @@ "packages": { "": { "name": "@ionic/core", - "version": "6.0.5", + "version": "6.0.10", "license": "MIT", "dependencies": { - "@stencil/core": "~2.13.0", + "@stencil/core": "^2.14.1", "ionicons": "^6.0.0", "tslib": "^2.1.0" }, @@ -1366,9 +1366,9 @@ } }, "node_modules/@stencil/core": { - "version": "2.13.0", - "resolved": "https://registry.npmjs.org/@stencil/core/-/core-2.13.0.tgz", - "integrity": "sha512-EEKHOHgYpg3/iFUKMXTZJjUayRul7sXDwNw0OGgkEOe4t7JWiibDkzUHuruvpbqEydX+z1+ez5K2bMMY76c2wA==", + "version": "2.14.1", + "resolved": "https://registry.npmjs.org/@stencil/core/-/core-2.14.1.tgz", + "integrity": "sha512-G58fJeDbi58+7uQnyaGInnehfub9tJikFZ4PkT/FuelMV9wGq2FKB0fxKctKQ3mhhHAiFDuGNzRD1isZZQvUCg==", "bin": { "stencil": "bin/stencil" }, @@ -15055,9 +15055,9 @@ "dev": true }, "@stencil/core": { - "version": "2.13.0", - "resolved": "https://registry.npmjs.org/@stencil/core/-/core-2.13.0.tgz", - "integrity": "sha512-EEKHOHgYpg3/iFUKMXTZJjUayRul7sXDwNw0OGgkEOe4t7JWiibDkzUHuruvpbqEydX+z1+ez5K2bMMY76c2wA==" + "version": "2.14.1", + "resolved": "https://registry.npmjs.org/@stencil/core/-/core-2.14.1.tgz", + "integrity": "sha512-G58fJeDbi58+7uQnyaGInnehfub9tJikFZ4PkT/FuelMV9wGq2FKB0fxKctKQ3mhhHAiFDuGNzRD1isZZQvUCg==" }, "@stencil/react-output-target": { "version": "0.2.1", diff --git a/core/package.json b/core/package.json index 6d35676426..a22b65966c 100644 --- a/core/package.json +++ b/core/package.json @@ -31,7 +31,7 @@ "loader/" ], "dependencies": { - "@stencil/core": "~2.13.0", + "@stencil/core": "^2.14.1", "ionicons": "^6.0.0", "tslib": "^2.1.0" }, diff --git a/docs/core.json b/docs/core.json index ce0b753af9..298925c883 100644 --- a/docs/core.json +++ b/docs/core.json @@ -1,9 +1,9 @@ { - "timestamp": "2022-02-25T14:31:38", + "timestamp": "2022-03-08T15:06:29", "compiler": { "name": "@stencil/core", - "version": "2.13.0", - "typescriptVersion": "4.3.5" + "version": "2.14.1", + "typescriptVersion": "4.5.4" }, "components": [ { @@ -2426,7 +2426,7 @@ "filePath": "./src/components/button/button.tsx", "encapsulation": "shadow", "tag": "ion-button", - "readme": "# ion-button\n\nButtons provide a clickable element, which can be used in forms, or anywhere that needs simple, standard button functionality. They may display text, icons, or both. Buttons can be styled with several attributes to look a specific way.\n\n## Expand\n\nThis attribute lets you specify how wide the button should be. By default, buttons are inline blocks, but setting this attribute will change the button to a full-width block element.\n\n| Value | Details |\n|----------------|------------------------------------------------------------------------------|\n| `block` | Full-width button with rounded corners. |\n| `full` | Full-width button with square corners and no border on the left or right. |\n\n## Fill\n\nThis attributes determines the background and border color of the button. By default, buttons have a solid background unless the button is inside of a toolbar, in which case it has a transparent background.\n\n| Value | Details |\n|----------------|------------------------------------------------------------------------------|\n| `clear` | Button with a transparent background that resembles a flat button. |\n| `outline` | Button with a transparent background and a visible border. |\n| `solid` | Button with a filled background. Useful for buttons in a toolbar. |\n\n## Size\n\nThis attribute specifies the size of the button. Setting this attribute will change the height and padding of a button.\n\n| Value | Details |\n|----------------|------------------------------------------------------------------------------|\n| `small` | Button with less height and padding. Default for buttons in an item. |\n| `default` | Button with the default height and padding. Useful for buttons in an item. |\n| `large` | Button with more height and padding. |\n\n", + "readme": "# ion-button\n\nButtons provide a clickable element, which can be used in forms, or anywhere that needs simple, standard button functionality. They may display text, icons, or both. Buttons can be styled with several attributes to look a specific way.\n\n## Expand\n\nThis attribute lets you specify how wide the button should be. By default, buttons are inline blocks, but setting this attribute will change the button to a full-width block element.\n\n| Value | Details |\n|----------------|------------------------------------------------------------------------------|\n| `block` | Full-width button with rounded corners. |\n| `full` | Full-width button with square corners and no border on the left or right. |\n\n## Fill\n\nThis attribute determines the background and border color of the button. By default, buttons have a solid background unless the button is inside of a toolbar, in which case it has a transparent background.\n\n| Value | Details |\n|----------------|------------------------------------------------------------------------------|\n| `clear` | Button with a transparent background that resembles a flat button. |\n| `outline` | Button with a transparent background and a visible border. |\n| `solid` | Button with a filled background. Useful for buttons in a toolbar. |\n\n## Size\n\nThis attribute specifies the size of the button. Setting this attribute will change the height and padding of a button.\n\n| Value | Details |\n|----------------|------------------------------------------------------------------------------|\n| `small` | Button with less height and padding. Default for buttons in an item. |\n| `default` | Button with the default height and padding. Useful for buttons in an item. |\n| `large` | Button with more height and padding. |\n\n", "docs": "Buttons provide a clickable element, which can be used in forms, or anywhere that needs simple, standard button functionality. They may display text, icons, or both. Buttons can be styled with several attributes to look a specific way.", "docsTags": [ { @@ -4826,7 +4826,7 @@ "filePath": "./src/components/datetime/datetime.tsx", "encapsulation": "shadow", "tag": "ion-datetime", - "readme": "# ion-datetime\n\nDatetimes present a calendar interface and time wheel, making it easy for users to select dates and times. Datetimes are similar to the native `input` elements of `datetime-local`, however, Ionic Framework's Datetime component makes it easy to display the date and time in the preferred format, and manage the datetime values.\n\n### Datetime Data\n\nHistorically, handling datetime values within JavaScript, or even within HTML\ninputs, has always been a challenge. Specifically, JavaScript's `Date` object is\nnotoriously difficult to correctly parse apart datetime strings or to format\ndatetime values. Even worse is how different browsers and JavaScript versions\nparse various datetime strings differently, especially per locale.\n\nFortunately, Ionic Framework's datetime input has been designed so developers can avoid\nthe common pitfalls, allowing developers to easily manipulate datetime values and give the user a simple datetime picker for a great user experience.\n\n##### ISO 8601 Datetime Format: YYYY-MM-DDTHH:mmZ\n\nIonic Framework uses the [ISO 8601 datetime format](https://www.w3.org/TR/NOTE-datetime)\nfor its value. The value is simply a string, rather than using JavaScript's\n`Date` object. Using the ISO datetime format makes it easy to serialize\nand parse within JSON objects and databases.\n\nAn ISO format can be used as a simple year, or just the hour and minute, or get\nmore detailed down to the millisecond and time zone. Any of the ISO formats below\ncan be used, and after a user selects a new value, Ionic Framework will continue to use\nthe same ISO format which datetime value was originally given as.\n\n| Description | Format | Datetime Value Example |\n| -------------------- | ---------------------- | ---------------------------- |\n| Year | YYYY | 1994 |\n| Year and Month | YYYY-MM | 1994-12 |\n| Complete Date | YYYY-MM-DD | 1994-12-15 |\n| Date and Time | YYYY-MM-DDTHH:mm | 1994-12-15T13:47 |\n| UTC Timezone | YYYY-MM-DDTHH:mm:ssZ | 1994-12-15T13:47:20Z |\n| Timezone Offset | YYYY-MM-DDTHH:mm:ssTZD | 1994-12-15T13:47:20+05:00 |\n| Hour and Minute | HH:mm | 13:47 |\n| Hour, Minute, Second | HH:mm:ss | 13:47:20 |\n\nNote that the year is always four-digits, milliseconds (if it's added) is always\nthree-digits, and all others are always two-digits. So the number representing\nJanuary always has a leading zero, such as `01`. Additionally, the hour is\nalways in the 24-hour format, so `00` is `12am` on a 12-hour clock, `13` means\n`1pm`, and `23` means `11pm`.\n\n## Min and Max Datetimes\n\nDates are infinite in either direction, so for a user's selection there should be at least some form of restricting the dates that can be selected. By default, the maximum date is to the end of the current year, and the minimum date is from the beginning of the year that was 100 years ago.\n\nTo customize the minimum and maximum datetime values, the `min` and `max` component properties can be provided which may make more sense for the app's use-case. Following the same IS0 8601 format listed in the table above, each component can restrict which dates can be selected by the user. By passing `2016` to the `min` property and `2020-10-31` to the `max` property, the datetime will restrict the date selection between the beginning of `2016`, and `October 31st of 2020`.\n\n## Selecting Specific Values\n\nWhile the `min` and `max` properties allow you to restrict date selection to a certain range, the `monthValues`, `dayValues`, `yearValues`, `hourValues`, and `minuteValues` properties allow you choose specific days and times that you to have enabled.\n\nFor example, if we wanted users to only select minutes in increments of 15, we could pass `\"0,15,30,45\"` to the `minuteValues` property.\n\nAs another example, if we wanted users to only select from the month of October, we could pass `\"10\"` to the `monthValues` property.\n\n## Customizing Date and Time Presentation\n\nSome use cases may call for only date selection or only time selection. The `presentation` property allows you to specify which pickers to show and the order to show them in. For example, `presentation=\"time\"` would only show the time picker. `presentation=\"time-date\"` would show the time picker first and the date picker second, but `presentation=\"date-time\"` would show the date picker first and the time picker second.\n\n## Reset and Cancel Buttons\n\n`ion-datetime` provides `cancel` and `reset` methods that you can call when clicking on custom buttons that you have provided in the `buttons` slot. The `reset` method also allows you to provide a date to reset the datetime to.\n\n## Confirming Selected Values\n\nBy default, `ionChange` is emitted with the new datetime value whenever a new date is selected. To require user confirmation before emitting `ionChange`, you can either set the `showDefaultButtons` property to `true` or use the `buttons` slot to pass in a custom confirmation button. When passing in custom buttons, the confirm button must call the `confirm` method on `ion-datetime` for `ionChange` to be emitted.\n\n## Localization\n\nIonic Framework makes use of the [Intl.DatetimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DatetimeFormat) Web API which allows us to automatically localize the month and day names according to the language and region set on the user's device.\n\nFor instances where you need a specific locale, you can use the `locale` property to set it. The following example sets the language to \"French\" and the region to \"France\":\n\n```html\n\n```\n\n### Controlling the Hour Cycle\n\n`ion-datetime` will use the hour cycle that is specified by the `locale` property by default. For example, if `locale` is set to `en-US`, then `ion-datetime` will use a 12 hour cycle.\n\nThere are 4 primary hour cycle types:\n\n| Hour cycle type | Description |\n| --------------- | ------------------------------------------------------------ |\n| `'h12` | Hour system using 1–12; corresponds to 'h' in patterns. The 12 hour clock, with midnight starting at 12:00 am. |\n| `'h23'` | Hour system using 0–23; corresponds to 'H' in patterns. The 24 hour clock, with midnight starting at 0:00. |\n| `'h11'` | Hour system using 0–11; corresponds to 'K' in patterns. The 12 hour clock, with midnight starting at 0:00 am. |\n| `'h24'` | Hour system using 1–24; corresponds to 'k' in pattern. The 24 hour clock, with midnight starting at 24:00. |\n\n> Source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/hourCycle\n\nThere may be scenarios where you need to have more control over which hour cycle is used. This is where the `hourCycle` property can help.\n\nIn the following example, we can use the `hourCycle` property to force `ion-datetime` to use the 12 hour cycle even though the locale is `en-GB`, which uses a 24 hour cycle by default:\n\n```html\n\n```\n\n`ion-datetime` also supports [locale extension tags](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale). These tags let you encode information about the locale in the locale string itself. Developers may prefer to use the extension tag approach if they are using the [Intl.Locale API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) in their apps.\n\nFor example, if you wanted to use a 12 hour cycle with the `en-GB` locale, you could alternatively do:\n\n```html\n\n```\n\n`ion-datetime` currently supports the `h12` and `h23` hour cycle types. Interested in seeing support for `h11` and `h24` added to `ion-datetime`? [Let us know!](https://github.com/ionic-team/ionic-framework/issues/23750)\n\n### Setting the First Day of the Week\n\nFor `ion-datetime`, the default first day of the week is Sunday. As of 2021, there is no browser API that lets Ionic automatically determine the first day of the week based on a device's locale, though there is on-going work regarding this (see: [TC39 GitHub](https://github.com/tc39/ecma402/issues/6)).\n\nTo customize the first day of the week, developers can use the `firstDayOfWeek` property. This property takes in a number between `0` and `6` where `0` represents Sunday and `6` represents Saturday.\n\nFor example, if you wanted to have the first day of the week be Monday, you could set `firstDayOfWeek` to `1`:\n\n```html\n\n```\n\n## Time Zones\n\nIonic's `ion-datetime` follows the [datetime-local](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local) behavior of not manipulating or setting the time zone inside of a datetime control. In other words, a time value of \"07:00\" will not be adjusted according to different time zones.\n\nWe recommend using a library such as [date-fns-tz](https://github.com/marnusw/date-fns-tz) to convert a datetime value to the desired time zone.\n\nBelow is an example of formatting an ISO-8601 string to display in the time zone set on a user's device:\n\n```typescript\nimport { format, utcToZonedTime } from 'date-fns-tz';\n\n// Get the time zone set on the user's device\nconst userTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;\n\n// Create a date object from a UTC date string\nconst date = new Date('2014-10-25T10:46:20Z');\n\n// Use date-fns-tz to convert from UTC to a zoned time\nconst zonedTime = dateFnsTz.utcToZonedTime(date, userTimeZone);\n\n// Create a formatted string from the zoned time\nformat(zonedTime, 'yyyy-MM-dd HH:mm:ssXXX', { timeZone: userTimeZone });\n```\n\n## Timezones\n\n### Assigning Date Values\n\n`ion-datetime` does not manipulate or read timezones. Developers will need to pass in a valid ISO-8601 string that is already configured for the user's timezone when assigning a value. If no value is provided, `ion-datetime` will default to the time specified on the user's machine (which will already be in the user's timezone). We recommend using [date-fns](https://date-fns.org) to format the date to ISO-8601.\n\n```typescript\nimport { formatISO } from 'date-fns';\n\nconst dateString = '2021-01-14T15:00:00.000Z';\nconst formattedDateValue = formatISO(new Date(dateString));\n\n// Assign `formattedDateValue` to your `ion-datetime` value.\n\n```\n\n### Parsing Date Values\n\nThe `ionChange` event will emit the date value as an ISO-8601 string in the event payload. It is the developer's responsibility to format it based on their application needs. We recommend using [date-fns](https://date-fns.org) to format the date value.\n\nBelow is an example of formatting an ISO-8601 string to display the month, date and year:\n\n```typescript\nimport { format, parseISO } from 'date-fns';\n\n/**\n * This is provided in the event\n * payload from the `ionChange` event.\n * \n * The value is an ISO-8601 date string.\n */\nconst dateFromIonDatetime = '2021-06-04T14:23:00-04:00';\nconst formattedString = format(parseISO(dateFromIonDatetime), 'MMM d, yyyy');\n\nconsole.log(formattedString); // Jun 4, 2021\n```\n\nSee https://date-fns.org/docs/format for a list of all the valid format tokens.\n\n## Advanced Datetime Validation and Manipulation\n\nThe datetime picker provides the simplicity of selecting an exact format, and\npersists the datetime values as a string using the standardized [ISO 8601\ndatetime format](https://www.w3.org/TR/NOTE-datetime). However, it's important\nto note that `ion-datetime` does not attempt to solve all situations when\nvalidating and manipulating datetime values. If datetime values need to be\nparsed from a certain format, or manipulated (such as adding 5 days to a date,\nsubtracting 30 minutes, etc.), or even formatting data to a specific locale,\nthen we highly recommend using [date-fns](https://date-fns.org) to work with\ndates in JavaScript.\n\n## Accessibility\n\n### Keyboard Navigation\n\n`ion-datetime` has full keyboard support for navigating between focusable elements inside of the component. The following table details what each key does:\n\n| Key | Function |\n| ------------------ | ------------------------------------------------------------ |\n| `Tab` | Moves focus to the next focusable element. |\n| `Shift` + `Tab` | Moves focus to the previous focusable element. |\n| `Space` or `Enter` | Clicks the focusable element. |\n\n#### Date Grid\n\n| Key | Function |\n| ------------------ | ------------------------------------------------------------ |\n| `ArrowUp` | Moves focus to the same day of the previous week. |\n| `ArrowDown` | Moves focus to the same day of the next week. |\n| `ArrowRight` | Moves focus to the next day. |\n| `ArrowLeft` | Moves focus to the previous day. |\n| `Home` | Moves focus to the first day of the current week. |\n| `End` | Moves focus to the last day of the current week. |\n| `PageUp` | Changes the grid of dates to the previous month. |\n| `PageDown` | Changes the grid of dates to the next month. |\n| `Shift` + `PageUp` | Changes the grid of dates to the previous year. |\n| `Shift` + `PageDown` | Changes the grid of dates to the next year. |\n\n#### Time, Month, and Year Wheels\n\nWhen using the time wheel picker, you can use the number keys to select hour and minute values when the columns are focused.\n\n| Key | Function |\n| ------------------ | ------------------------------------------------------------ |\n| `ArrowUp` | Scroll to the previous item. |\n| `ArrowDown` | Scroll to the next item. |\n| `Home` | Scroll to the first item. |\n| `End` | Scroll to the last item. |\n\n## Interfaces\n\n### DatetimeChangeEventDetail\n\n```typescript\ninterface DatetimeChangeEventDetail {\n value?: string | null;\n}\n```\n\n### DatetimeCustomEvent\n\nWhile not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.\n\n```typescript\ninterface DatetimeCustomEvent extends CustomEvent {\n detail: DatetimeChangeEventDetail;\n target: HTMLIonDatetimeElement;\n}\n```\n", + "readme": "# ion-datetime\n\nDatetimes present a calendar interface and time wheel, making it easy for users to select dates and times. Datetimes are similar to the native `input` elements of `datetime-local`, however, Ionic Framework's Datetime component makes it easy to display the date and time in the preferred format, and manage the datetime values.\n\n### Datetime Data\n\nHistorically, handling datetime values within JavaScript, or even within HTML\ninputs, has always been a challenge. Specifically, JavaScript's `Date` object is\nnotoriously difficult to correctly parse apart datetime strings or to format\ndatetime values. Even worse is how different browsers and JavaScript versions\nparse various datetime strings differently, especially per locale.\n\nFortunately, Ionic Framework's datetime input has been designed so developers can avoid\nthe common pitfalls, allowing developers to easily manipulate datetime values and give the user a simple datetime picker for a great user experience.\n\n##### ISO 8601 Datetime Format: YYYY-MM-DDTHH:mmZ\n\nIonic Framework uses the [ISO 8601 datetime format](https://www.w3.org/TR/NOTE-datetime)\nfor its value. The value is simply a string, rather than using JavaScript's\n`Date` object. Using the ISO datetime format makes it easy to serialize\nand parse within JSON objects and databases.\n\nAn ISO format can be used as a simple year, or just the hour and minute, or get\nmore detailed down to the millisecond and time zone. Any of the ISO formats below\ncan be used, and after a user selects a new value, Ionic Framework will continue to use\nthe same ISO format which datetime value was originally given as.\n\n| Description | Format | Datetime Value Example |\n| -------------------- | ---------------------- | ---------------------------- |\n| Year | YYYY | 1994 |\n| Year and Month | YYYY-MM | 1994-12 |\n| Complete Date | YYYY-MM-DD | 1994-12-15 |\n| Date and Time | YYYY-MM-DDTHH:mm | 1994-12-15T13:47 |\n| UTC Timezone | YYYY-MM-DDTHH:mm:ssZ | 1994-12-15T13:47:20Z |\n| Timezone Offset | YYYY-MM-DDTHH:mm:ssTZD | 1994-12-15T13:47:20+05:00 |\n| Hour and Minute | HH:mm | 13:47 |\n| Hour, Minute, Second | HH:mm:ss | 13:47:20 |\n\nNote that the year is always four-digits, milliseconds (if it's added) is always\nthree-digits, and all others are always two-digits. So the number representing\nJanuary always has a leading zero, such as `01`. Additionally, the hour is\nalways in the 24-hour format, so `00` is `12am` on a 12-hour clock, `13` means\n`1pm`, and `23` means `11pm`.\n\n## Min and Max Datetimes\n\nDates are infinite in either direction, so for a user's selection there should be at least some form of restricting the dates that can be selected. By default, the maximum date is to the end of the current year, and the minimum date is from the beginning of the year that was 100 years ago.\n\nTo customize the minimum and maximum datetime values, the `min` and `max` component properties can be provided which may make more sense for the app's use-case. Following the same IS0 8601 format listed in the table above, each component can restrict which dates can be selected by the user. By passing `2016` to the `min` property and `2020-10-31` to the `max` property, the datetime will restrict the date selection between the beginning of `2016`, and `October 31st of 2020`.\n\n## Selecting Specific Values\n\nWhile the `min` and `max` properties allow you to restrict date selection to a certain range, the `monthValues`, `dayValues`, `yearValues`, `hourValues`, and `minuteValues` properties allow you choose specific days and times that you to have enabled.\n\nFor example, if we wanted users to only select minutes in increments of 15, we could pass `\"0,15,30,45\"` to the `minuteValues` property.\n\nAs another example, if we wanted users to only select from the month of October, we could pass `\"10\"` to the `monthValues` property.\n\n## Customizing Date and Time Presentation\n\nSome use cases may call for only date selection or only time selection. The `presentation` property allows you to specify which pickers to show and the order to show them in. For example, `presentation=\"time\"` would only show the time picker. `presentation=\"time-date\"` would show the time picker first and the date picker second, but `presentation=\"date-time\"` would show the date picker first and the time picker second.\n\n## Reset and Cancel Buttons\n\n`ion-datetime` provides `cancel` and `reset` methods that you can call when clicking on custom buttons that you have provided in the `buttons` slot. The `reset` method also allows you to provide a date to reset the datetime to.\n\n## Confirming Selected Values\n\nBy default, `ionChange` is emitted with the new datetime value whenever a new date is selected. To require user confirmation before emitting `ionChange`, you can either set the `showDefaultButtons` property to `true` or use the `buttons` slot to pass in a custom confirmation button. When passing in custom buttons, the confirm button must call the `confirm` method on `ion-datetime` for `ionChange` to be emitted.\n\n## Localization\n\nIonic Framework makes use of the [Intl.DatetimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DatetimeFormat) Web API which allows us to automatically localize the month and day names according to the language and region set on the user's device.\n\nFor instances where you need a specific locale, you can use the `locale` property to set it. The following example sets the language to \"French\" and the region to \"France\":\n\n```html\n\n```\n\n### Controlling the Hour Cycle\n\n`ion-datetime` will use the hour cycle that is specified by the `locale` property by default. For example, if `locale` is set to `en-US`, then `ion-datetime` will use a 12 hour cycle.\n\nThere are 4 primary hour cycle types:\n\n| Hour cycle type | Description |\n| --------------- | ------------------------------------------------------------ |\n| `'h12` | Hour system using 1–12; corresponds to 'h' in patterns. The 12 hour clock, with midnight starting at 12:00 am. |\n| `'h23'` | Hour system using 0–23; corresponds to 'H' in patterns. The 24 hour clock, with midnight starting at 0:00. |\n| `'h11'` | Hour system using 0–11; corresponds to 'K' in patterns. The 12 hour clock, with midnight starting at 0:00 am. |\n| `'h24'` | Hour system using 1–24; corresponds to 'k' in pattern. The 24 hour clock, with midnight starting at 24:00. |\n\n> Source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/hourCycle\n\nThere may be scenarios where you need to have more control over which hour cycle is used. This is where the `hourCycle` property can help.\n\nIn the following example, we can use the `hourCycle` property to force `ion-datetime` to use the 12 hour cycle even though the locale is `en-GB`, which uses a 24 hour cycle by default:\n\n```html\n\n```\n\n`ion-datetime` also supports [locale extension tags](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale). These tags let you encode information about the locale in the locale string itself. Developers may prefer to use the extension tag approach if they are using the [Intl.Locale API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale) in their apps.\n\nFor example, if you wanted to use a 12 hour cycle with the `en-GB` locale, you could alternatively do:\n\n```html\n\n```\n\n`ion-datetime` currently supports the `h12` and `h23` hour cycle types. Interested in seeing support for `h11` and `h24` added to `ion-datetime`? [Let us know!](https://github.com/ionic-team/ionic-framework/issues/23750)\n\n### Setting the First Day of the Week\n\nFor `ion-datetime`, the default first day of the week is Sunday. As of 2021, there is no browser API that lets Ionic automatically determine the first day of the week based on a device's locale, though there is on-going work regarding this (see: [TC39 GitHub](https://github.com/tc39/ecma402/issues/6)).\n\nTo customize the first day of the week, developers can use the `firstDayOfWeek` property. This property takes in a number between `0` and `6` where `0` represents Sunday and `6` represents Saturday.\n\nFor example, if you wanted to have the first day of the week be Monday, you could set `firstDayOfWeek` to `1`:\n\n```html\n\n```\n\n## Time Zones\n\nIonic's `ion-datetime` follows the [datetime-local](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/datetime-local) behavior of not manipulating or setting the time zone inside of a datetime control. In other words, a time value of \"07:00\" will not be adjusted according to different time zones.\n\nWe recommend using a library such as [date-fns-tz](https://github.com/marnusw/date-fns-tz) to convert a datetime value to the desired time zone.\n\nBelow is an example of formatting an ISO-8601 string to display in the time zone set on a user's device:\n\n```typescript\nimport { format, utcToZonedTime } from 'date-fns-tz';\n\n// Get the time zone set on the user's device\nconst userTimeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;\n\n// Create a date object from a UTC date string\nconst date = new Date('2014-10-25T10:46:20Z');\n\n// Use date-fns-tz to convert from UTC to a zoned time\nconst zonedTime = dateFnsTz.utcToZonedTime(date, userTimeZone);\n\n// Create a formatted string from the zoned time\nformat(zonedTime, 'yyyy-MM-dd HH:mm:ssXXX', { timeZone: userTimeZone });\n```\n\n### Parsing Date Values\n\nThe `ionChange` event will emit the date value as an ISO-8601 string in the event payload. It is the developer's responsibility to format it based on their application needs. We recommend using [date-fns](https://date-fns.org) to format the date value.\n\nBelow is an example of formatting an ISO-8601 string to display the month, date and year:\n\n```typescript\nimport { format, parseISO } from 'date-fns';\n\n/**\n * This is provided in the event\n * payload from the `ionChange` event.\n * \n * The value is an ISO-8601 date string.\n */\nconst dateFromIonDatetime = '2021-06-04T14:23:00-04:00';\nconst formattedString = format(parseISO(dateFromIonDatetime), 'MMM d, yyyy');\n\nconsole.log(formattedString); // Jun 4, 2021\n```\n\nSee https://date-fns.org/docs/format for a list of all the valid format tokens.\n\n## Advanced Datetime Validation and Manipulation\n\nThe datetime picker provides the simplicity of selecting an exact format, and\npersists the datetime values as a string using the standardized [ISO 8601\ndatetime format](https://www.w3.org/TR/NOTE-datetime). However, it's important\nto note that `ion-datetime` does not attempt to solve all situations when\nvalidating and manipulating datetime values. If datetime values need to be\nparsed from a certain format, or manipulated (such as adding 5 days to a date,\nsubtracting 30 minutes, etc.), or even formatting data to a specific locale,\nthen we highly recommend using [date-fns](https://date-fns.org) to work with\ndates in JavaScript.\n\n## Accessibility\n\n### Keyboard Navigation\n\n`ion-datetime` has full keyboard support for navigating between focusable elements inside of the component. The following table details what each key does:\n\n| Key | Function |\n| ------------------ | ------------------------------------------------------------ |\n| `Tab` | Moves focus to the next focusable element. |\n| `Shift` + `Tab` | Moves focus to the previous focusable element. |\n| `Space` or `Enter` | Clicks the focusable element. |\n\n#### Date Grid\n\n| Key | Function |\n| ------------------ | ------------------------------------------------------------ |\n| `ArrowUp` | Moves focus to the same day of the previous week. |\n| `ArrowDown` | Moves focus to the same day of the next week. |\n| `ArrowRight` | Moves focus to the next day. |\n| `ArrowLeft` | Moves focus to the previous day. |\n| `Home` | Moves focus to the first day of the current week. |\n| `End` | Moves focus to the last day of the current week. |\n| `PageUp` | Changes the grid of dates to the previous month. |\n| `PageDown` | Changes the grid of dates to the next month. |\n| `Shift` + `PageUp` | Changes the grid of dates to the previous year. |\n| `Shift` + `PageDown` | Changes the grid of dates to the next year. |\n\n#### Time, Month, and Year Wheels\n\nWhen using the time wheel picker, you can use the number keys to select hour and minute values when the columns are focused.\n\n| Key | Function |\n| ------------------ | ------------------------------------------------------------ |\n| `ArrowUp` | Scroll to the previous item. |\n| `ArrowDown` | Scroll to the next item. |\n| `Home` | Scroll to the first item. |\n| `End` | Scroll to the last item. |\n\n## Interfaces\n\n### DatetimeChangeEventDetail\n\n```typescript\ninterface DatetimeChangeEventDetail {\n value?: string | null;\n}\n```\n\n### DatetimeCustomEvent\n\nWhile not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.\n\n```typescript\ninterface DatetimeCustomEvent extends CustomEvent {\n detail: DatetimeChangeEventDetail;\n target: HTMLIonDatetimeElement;\n}\n```\n", "docs": "Datetimes present a calendar interface and time wheel, making it easy for users to select dates and times. Datetimes are similar to the native `input` elements of `datetime-local`, however, Ionic Framework's Datetime component makes it easy to display the date and time in the preferred format, and manage the datetime values.", "docsTags": [ { @@ -6596,7 +6596,7 @@ "javascript": "```html\n\n \n Toggle Infinite Scroll\n \n\n \n\n \n \n \n \n\n```\n\n```javascript\nconst infiniteScroll = document.getElementById('infinite-scroll');\n\ninfiniteScroll.addEventListener('ionInfinite', function(event) {\n setTimeout(function() {\n console.log('Done');\n event.target.complete();\n\n // App logic to determine if all data is loaded\n // and disable the infinite scroll\n if (data.length === 1000) {\n event.target.disabled = true;\n }\n }, 500);\n});\n\nfunction toggleInfiniteScroll() {\n infiniteScroll.disabled = !infiniteScroll.disabled;\n}\n```\n", "react": "```tsx\nimport { \n IonButton,\n IonContent, \n IonHeader,\n IonInfiniteScroll, \n IonInfiniteScrollContent, \n IonItem,\n IonLabel,\n IonList, \n IonPage, \n IonTitle, \n IonToolbar,\n useIonViewWillEnter\n} from '@ionic/react';\nimport { useState } from 'react';\n\nconst InfiniteScrollExample: React.FC = () => {\n const [data, setData] = useState([]);\n const [isInfiniteDisabled, setInfiniteDisabled] = useState(false);\n \n const pushData = () => {\n const max = data.length + 20;\n const min = max - 20;\n const newData = [];\n for (let i = min; i < max; i++) {\n newData.push('Item' + i);\n }\n \n setData([\n ...data,\n ...newData\n ]);\n }\n const loadData = (ev: any) => {\n setTimeout(() => {\n pushData();\n console.log('Loaded data');\n ev.target.complete();\n if (data.length === 1000) {\n setInfiniteDisabled(true);\n }\n }, 500);\n } \n \n useIonViewWillEnter(() => {\n pushData();\n });\n \n return (\n \n \n \n Blank\n \n \n \n \n \n Blank\n \n \n \n setInfiniteDisabled(!isInfiniteDisabled)} expand=\"block\">\n Toggle Infinite Scroll\n \n \n \n {data.map((item, index) => {\n return (\n \n {item}\n \n )\n })}\n \n \n \n \n \n \n \n );\n};\n\nexport default InfiniteScrollExample;\n```", "stencil": "```tsx\nimport { Component, State, h } from '@stencil/core';\n\n@Component({\n tag: 'infinite-scroll-example',\n styleUrl: 'infinite-scroll-example.css'\n})\nexport class InfiniteScrollExample {\n private infiniteScroll: HTMLIonInfiniteScrollElement;\n\n @State() data = [];\n\n componentWillLoad() {\n this.pushData();\n }\n\n pushData() {\n const max = this.data.length + 20;\n const min = max - 20;\n\n for (var i = min; i < max; i++) {\n this.data.push('Item ' + i);\n }\n\n // Stencil does not re-render when pushing to an array\n // so create a new copy of the array\n // https://stenciljs.com/docs/reactive-data#handling-arrays-and-objects\n this.data = [\n ...this.data\n ];\n }\n\n loadData(ev) {\n setTimeout(() => {\n this.pushData();\n console.log('Loaded data');\n ev.target.complete();\n\n // App logic to determine if all data is loaded\n // and disable the infinite scroll\n if (this.data.length === 1000) {\n ev.target.disabled = true;\n }\n }, 500);\n }\n\n toggleInfiniteScroll() {\n this.infiniteScroll.disabled = !this.infiniteScroll.disabled;\n }\n\n render() {\n return [\n \n this.toggleInfiniteScroll()} expand=\"block\">\n Toggle Infinite Scroll\n \n\n \n {this.data.map(item =>\n \n {item}\n \n )}\n \n\n this.infiniteScroll = el}\n onIonInfinite={(ev) => this.loadData(ev)}>\n \n \n \n \n ];\n }\n}\n```", - "vue": "```html\n\n\n\n```" + "vue": "```html\n\n\n\n```" }, "props": [ { @@ -7822,7 +7822,7 @@ "usage": { "angular": "```html\n\n\n \n Item\n \n\n\n\n\n \n Button Item\n \n\n\n\n\n \n Anchor Item\n \n\n\n\n \n Secondary Color Item\n \n\n```\n\n### Detail Arrows\n\n```html\n\n \n Standard Item with Detail Arrow\n \n\n\n\n \n Button Item with Detail Arrow\n \n\n\n\n \n Anchor Item with no Detail Arrow\n \n\n```\n\n### List Items\n\n```html\n\n \n \n Item\n \n \n\n \n \n No Lines Item\n \n \n\n \n \n Multiline text that should wrap when it is too long\n to fit on one line in the item.\n \n \n\n \n \n \n

H3 Primary Title

\n \n

Paragraph line 1

\n \n

Paragraph line 2 secondary

\n \n \n \n\n \n \n Item with Full Lines\n \n \n\n\n```\n\n### Item Lines\n\n```html\n\n\n Item Lines Inset\n\n\n\n\n Item Lines Full\n\n\n\n\n Item Lines None\n\n\n\n\n \n Full Lines Item 1\n \n\n \n Full Lines Item 2\n \n\n\n\n\n \n Inset Lines Item 1\n \n\n \n Inset Lines Item 2\n \n\n\n\n\n \n No lines Item 1\n \n\n \n No lines Item 2\n \n\n \n No lines Item 3\n \n\n```\n\n\n### Media Items\n\n```html\n\n \n \n \n \n Avatar Start, Button Item\n \n\n\n\n \n Thumbnail End, Anchor Item\n \n \n \n \n\n\n\n \n \n \n \n

H2 Title Text

\n

Button on right

\n \n View\n\n\n\n \n \n \n \n

H3 Title Text

\n

Icon on right

\n \n \n\n```\n\n### Buttons in Items\n\n```html\n\n \n Start\n \n Button Start/End\n \n End\n \n\n\n\n \n Start Icon\n \n \n Buttons with Icons\n \n \n End Icon\n \n\n\n\n \n \n \n Icon only Buttons\n \n \n \n\n```\n\n### Icons in Items\n\n```html\n\n \n Icon End\n \n \n\n\n\n \n Large Icon End\n \n \n\n\n\n \n Small Icon End\n \n \n\n\n\n \n \n Icon Start\n \n\n\n\n \n Two Icons End\n \n \n \n\n```\n\n### Item Inputs\n\n```html\n\n Datetime\n \n\n\n\n Select\n \n No Game Console\n NES\n Nintendo64\n PlayStation\n Sega Genesis\n Sega Saturn\n SNES\n \n\n\n\n Toggle\n \n\n\n\n Floating Input\n \n\n\n\n Input (placeholder)\n \n\n\n\n Input (Fill: Solid)\n \n\n\n\n Input (Fill: Outline)\n \n\n\n\n Helper and Error Text\n \n Helper Text\n Error Text\n\n\n\n Checkbox\n \n\n\n\n Range\n \n\n```\n", "javascript": "```html\n\n\n \n Item\n \n\n\n\n\n \n Button Item\n \n\n\n\n\n \n Anchor Item\n \n\n\n\n \n Secondary Color Item\n \n\n```\n\n### Detail Arrows\n\n```html\n\n \n Standard Item with Detail Arrow\n \n\n\n\n \n Button Item with Detail Arrow\n \n\n\n\n \n Anchor Item with no Detail Arrow\n \n\n```\n\n### List Items\n\n```html\n\n \n \n Item\n \n \n\n \n \n No Lines Item\n \n \n\n \n \n Multiline text that should wrap when it is too long\n to fit on one line in the item.\n \n \n\n \n \n \n

H3 Primary Title

\n \n

Paragraph line 1

\n \n

Paragraph line 2 secondary

\n \n \n \n\n \n \n Item with Full Lines\n \n \n\n\n```\n\n### Item Lines\n\n```html\n\n\n Item Lines Inset\n\n\n\n\n Item Lines Full\n\n\n\n\n Item Lines None\n\n\n\n\n \n Full Lines Item 1\n \n\n \n Full Lines Item 2\n \n\n\n\n\n \n Inset Lines Item 1\n \n\n \n Inset Lines Item 2\n \n\n\n\n\n \n No lines Item 1\n \n\n \n No lines Item 2\n \n\n \n No lines Item 3\n \n\n```\n\n\n### Media Items\n\n```html\n\n \n \n \n \n Avatar Start, Button Item\n \n\n\n\n \n Thumbnail End, Anchor Item\n \n \n \n \n\n\n\n \n \n \n \n

H2 Title Text

\n

Button on right

\n \n View\n\n\n\n \n \n \n \n

H3 Title Text

\n

Icon on right

\n \n \n\n```\n\n### Buttons in Items\n\n```html\n\n \n Start\n \n Button Start/End\n \n End\n \n\n\n\n \n Start Icon\n \n \n Buttons with Icons\n \n \n End Icon\n \n\n\n\n \n \n \n Icon only Buttons\n \n \n \n\n```\n\n### Icons in Items\n\n```html\n\n \n Icon End\n \n \n\n\n\n \n Large Icon End\n \n \n\n\n\n \n Small Icon End\n \n \n\n\n\n \n \n Icon Start\n \n\n\n\n \n Two Icons End\n \n \n \n\n```\n\n### Item Inputs\n\n```html\n\n Datetime\n \n\n\n\n Select\n \n No Game Console\n NES\n Nintendo64\n PlayStation\n Sega Genesis\n Sega Saturn\n SNES\n \n\n\n\n Toggle\n \n\n\n\n Floating Input\n \n\n\n\n Input (placeholder)\n \n\n\n\n Input (Fill: Solid)\n \n\n\n\n Input (Fill: Outline)\n \n\n\n\n Helper and Error Text\n \n Helper Text\n Error Text\n\n\n\n Checkbox\n \n\n\n\n Range\n \n\n```\n", - "react": "```tsx\nimport React from 'react';\nimport { IonContent, IonHeader, IonPage, IonTitle, IonToolbar, IonItem, IonLabel, IonList, IonText, IonAvatar, IonThumbnail, IonButton, IonIcon, IonDatetime, IonSelect, IonSelectOption, IonToggle, IonInput, IonCheckbox, IonRange, IonNote } from '@ionic/react';\nimport { closeCircle, home, star, navigate, informationCircle, checkmarkCircle, shuffle } from 'ionicons/icons';\n\nexport const ItemExamples: React.FC = () => {\n return (\n \n \n \n ItemExamples\n \n \n \n {/*-- Default Item --*/}\n \n \n Item\n \n \n\n {/*-- Item as a Button --*/}\n { }}>\n \n Button Item\n \n \n\n {/*-- Item as an Anchor --*/}\n \n \n Anchor Item\n \n \n\n \n \n Secondary Color Item\n \n \n\n {/*-- Detail Arrows --*/}\n \n \n Standard Item with Detail Arrow\n \n \n\n { }} detail>\n \n Button Item with Detail Arrow\n \n \n\n \n \n Anchor Item with no Detail Arrow\n \n \n\n \n \n \n Item\n \n \n\n \n \n No Lines Item\n \n \n\n \n \n Multiline text that should wrap when it is too long\n to fit on one line in the item.\n \n \n\n \n \n \n

H3 Primary Title

\n \n

Paragraph line 1

\n \n

Paragraph line 2 secondary

\n \n \n \n\n \n \n Item with Full Lines\n \n \n \n\n {/*-- Item Inset Lines --*/}\n \n Item Lines Inset\n \n\n {/*-- Item Full Lines --*/}\n \n Item Lines Full\n \n\n {/*-- Item None Lines --*/}\n \n Item Lines None\n \n\n {/*-- List Full Lines --*/}\n \n \n Full Lines Item 1\n \n\n \n Full Lines Item 2\n \n \n\n {/*-- List Inset Lines --*/}\n \n \n Inset Lines Item 1\n \n\n \n Inset Lines Item 2\n \n \n\n {/*-- List No Lines --*/}\n \n \n No lines Item 1\n \n\n \n No lines Item 2\n \n\n \n No lines Item 3\n \n \n\n { }}>\n \n \n \n \n Avatar Start, Button Item\n \n \n\n \n \n Thumbnail End, Anchor Item\n \n \n \n \n \n\n \n \n \n \n \n

H2 Title Text

\n

Button on right

\n \n View\n \n\n { }}>\n \n \n \n \n

H3 Title Text

\n

Icon on right

\n \n \n \n\n {/*-- Buttons in Items --*/}\n \n \n Start\n \n Button Start/End\n \n End\n \n \n\n \n \n Start Icon\n >\n \n Buttons with Icons\n \n \n End Icon\n \n \n\n \n \n \n \n Icon only Buttons\n \n \n \n \n\n \n \n Icon End\n \n \n \n\n \n \n Large Icon End\n \n \n \n\n \n \n Small Icon End\n \n \n \n\n \n \n \n Icon Start\n \n \n\n \n \n Two Icons End\n \n \n \n \n\n \n Datetime\n \n \n\n \n Select\n \n No Game Console\n NES\n Nintendo64\n PlayStation\n Sega Genesis\n Sega Saturn\n SNES\n \n \n\n \n Toggle\n \n \n\n \n Floating Input\n \n \n\n \n Input (placeholder)\n \n \n\n \n Input (Fill: Solid)\n \n \n\n \n Input (Fill: Outline)\n \n \n\n \n Helper and Error Text\n \n Helper Text\n Error Text\n \n\n \n Checkbox\n \n \n\n \n Range\n \n \n \n \n );\n};\n```\n", + "react": "```tsx\nimport React from 'react';\nimport { IonContent, IonHeader, IonPage, IonTitle, IonToolbar, IonItem, IonLabel, IonList, IonText, IonAvatar, IonThumbnail, IonButton, IonIcon, IonDatetime, IonSelect, IonSelectOption, IonToggle, IonInput, IonCheckbox, IonRange, IonNote } from '@ionic/react';\nimport { closeCircle, home, star, navigate, informationCircle, checkmarkCircle, shuffle } from 'ionicons/icons';\n\nexport const ItemExamples: React.FC = () => {\n return (\n \n \n \n ItemExamples\n \n \n \n {/*-- Default Item --*/}\n \n \n Item\n \n \n\n {/*-- Item as a Button --*/}\n { }}>\n \n Button Item\n \n \n\n {/*-- Item as an Anchor --*/}\n \n \n Anchor Item\n \n \n\n \n \n Secondary Color Item\n \n \n\n {/*-- Detail Arrows --*/}\n \n \n Standard Item with Detail Arrow\n \n \n\n { }} detail>\n \n Button Item with Detail Arrow\n \n \n\n \n \n Anchor Item with no Detail Arrow\n \n \n\n \n \n \n Item\n \n \n\n \n \n No Lines Item\n \n \n\n \n \n Multiline text that should wrap when it is too long\n to fit on one line in the item.\n \n \n\n \n \n \n

H3 Primary Title

\n \n

Paragraph line 1

\n \n

Paragraph line 2 secondary

\n \n \n \n\n \n \n Item with Full Lines\n \n \n \n\n {/*-- Item Inset Lines --*/}\n \n Item Lines Inset\n \n\n {/*-- Item Full Lines --*/}\n \n Item Lines Full\n \n\n {/*-- Item None Lines --*/}\n \n Item Lines None\n \n\n {/*-- List Full Lines --*/}\n \n \n Full Lines Item 1\n \n\n \n Full Lines Item 2\n \n \n\n {/*-- List Inset Lines --*/}\n \n \n Inset Lines Item 1\n \n\n \n Inset Lines Item 2\n \n \n\n {/*-- List No Lines --*/}\n \n \n No lines Item 1\n \n\n \n No lines Item 2\n \n\n \n No lines Item 3\n \n \n\n { }}>\n \n \n \n \n Avatar Start, Button Item\n \n \n\n \n \n Thumbnail End, Anchor Item\n \n \n \n \n \n\n \n \n \n \n \n

H2 Title Text

\n

Button on right

\n \n View\n \n\n { }}>\n \n \n \n \n

H3 Title Text

\n

Icon on right

\n \n \n \n\n {/*-- Buttons in Items --*/}\n \n \n Start\n \n Button Start/End\n \n End\n \n \n\n \n \n Start Icon\n \n \n Buttons with Icons\n \n \n End Icon\n \n \n\n \n \n \n \n Icon only Buttons\n \n \n \n \n\n \n \n Icon End\n \n \n \n\n \n \n Large Icon End\n \n \n \n\n \n \n Small Icon End\n \n \n \n\n \n \n \n Icon Start\n \n \n\n \n \n Two Icons End\n \n \n \n \n\n \n Datetime\n \n \n\n \n Select\n \n No Game Console\n NES\n Nintendo64\n PlayStation\n Sega Genesis\n Sega Saturn\n SNES\n \n \n\n \n Toggle\n \n \n\n \n Floating Input\n \n \n\n \n Input (placeholder)\n \n \n\n \n Input (Fill: Solid)\n \n \n\n \n Input (Fill: Outline)\n \n \n\n \n Helper and Error Text\n \n Helper Text\n Error Text\n \n\n \n Checkbox\n \n \n\n \n Range\n \n \n \n \n );\n};\n```\n", "stencil": "```tsx\nimport { Component, h } from '@stencil/core';\n\n@Component({\n tag: 'item-example',\n styleUrl: 'item-example.css'\n})\nexport class ItemExample {\n buttonClick() {\n console.log('Clicked button');\n }\n\n render() {\n return [\n // Default Item\n \n \n Item\n \n ,\n\n // Item as a Button\n this.buttonClick()}>\n \n Button Item\n \n ,\n\n // Item as an Anchor\n \n \n Anchor Item\n \n ,\n\n \n \n Secondary Color Item\n \n \n ];\n }\n}\n```\n\n### Detail Arrows\n\n```tsx\nimport { Component, h } from '@stencil/core';\n\n@Component({\n tag: 'item-example',\n styleUrl: 'item-example.css'\n})\nexport class ItemExample {\n buttonClick() {\n console.log('Clicked button');\n }\n\n render() {\n return [\n \n \n Standard Item with Detail Arrow\n \n ,\n\n this.buttonClick()} detail>\n \n Button Item with Detail Arrow\n \n ,\n\n \n \n Anchor Item with no Detail Arrow\n \n \n ];\n }\n}\n```\n\n### List Items\n\n```tsx\nimport { Component, h } from '@stencil/core';\n\n@Component({\n tag: 'item-example',\n styleUrl: 'item-example.css'\n})\nexport class ItemExample {\n render() {\n return [\n \n \n \n Item\n \n ,\n\n \n \n No Lines Item\n \n ,\n\n \n \n Multiline text that should wrap when it is too long\n to fit on one line in the item.\n \n ,\n\n \n \n \n

H3 Primary Title

\n \n

Paragraph line 1

\n \n

Paragraph line 2 secondary

\n \n \n ,\n\n \n \n Item with Full Lines\n \n \n \n ];\n }\n}\n```\n\n### Item Lines\n\n```tsx\nimport { Component, h } from '@stencil/core';\n\n@Component({\n tag: 'item-example',\n styleUrl: 'item-example.css'\n})\nexport class ItemExample {\n render() {\n return [\n // Item Inset Lines\n \n Item Lines Inset\n ,\n\n // Item Full Lines\n \n Item Lines Full\n ,\n\n // Item None Lines\n \n Item Lines None\n ,\n\n // List Full Lines\n \n \n Full Lines Item 1\n \n\n \n Full Lines Item 2\n \n ,\n\n // List Inset Lines\n \n \n Inset Lines Item 1\n \n\n \n Inset Lines Item 2\n \n ,\n\n // List No Lines\n \n \n No lines Item 1\n \n\n \n No lines Item 2\n \n\n \n No lines Item 3\n \n \n ];\n }\n}\n```\n\n### Media Items\n\n```tsx\nimport { Component, h } from '@stencil/core';\n\n@Component({\n tag: 'item-example',\n styleUrl: 'item-example.css'\n})\nexport class ItemExample {\n testClick() {\n console.log('Test click');\n }\n\n render() {\n return [\n this.testClick()}>\n \n \n \n \n Avatar Start, Button Item\n \n ,\n\n \n \n Thumbnail End, Anchor Item\n \n \n \n \n ,\n\n \n \n \n \n \n

H2 Title Text

\n

Button on right

\n \n View\n ,\n\n this.testClick()}>\n \n \n \n \n

H3 Title Text

\n

Icon on right

\n \n \n \n ];\n }\n}\n```\n\n### Buttons in Items\n\n```tsx\nimport { Component, h } from '@stencil/core';\n\n@Component({\n tag: 'item-example',\n styleUrl: 'item-example.css'\n})\nexport class ItemExample {\n render() {\n return [\n \n \n Start\n \n Button Start/End\n \n End\n \n ,\n\n \n \n Start Icon\n \n \n Buttons with Icons\n \n \n End Icon\n \n ,\n\n \n \n \n \n Icon only Buttons\n \n \n \n \n ];\n }\n}\n```\n\n### Icons in Items\n\n```tsx\nimport { Component, h } from '@stencil/core';\n\n@Component({\n tag: 'item-example',\n styleUrl: 'item-example.css'\n})\nexport class ItemExample {\n render() {\n return [\n \n \n Icon End\n \n \n ,\n\n \n \n Large Icon End\n \n \n ,\n\n \n \n Small Icon End\n \n \n ,\n\n \n \n \n Icon Start\n \n ,\n\n \n \n Two Icons End\n \n \n \n \n ];\n }\n}\n```\n\n### Item Inputs\n\n```tsx\nimport { Component, h } from '@stencil/core';\n\n@Component({\n tag: 'item-example',\n styleUrl: 'item-example.css'\n})\nexport class ItemExample {\n render() {\n return [\n \n Datetime\n \n ,\n\n \n Select\n \n No Game Console\n NES\n Nintendo64\n PlayStation\n Sega Genesis\n Sega Saturn\n SNES\n \n ,\n\n \n Toggle\n \n ,\n\n \n Floating Input\n \n ,\n\n \n Input (placeholder)\n \n ,\n\n \n Input (Fill: Solid)\n \n ,\n\n \n Input (Fill: Outline)\n \n ,\n\n \n Helper and Error Text\n \n Helper Text\n Error Text\n ,\n\n \n Checkbox\n \n ,\n\n \n Range\n \n \n ];\n }\n}\n```", "vue": "```html\n\n```\n\n### Detail Arrows\n\n```html\n\n```\n\n### List Items\n\n```html\n\n```\n\n### Item Lines\n\n```html\n\n```\n\n\n### Media Items\n\n```html\n\n```\n\n### Buttons in Items\n\n```html\n\n```\n\n### Icons in Items\n\n```html\n\n```\n\n### Item Inputs\n\n```html\n\n\n\n```\n" }, @@ -9438,7 +9438,7 @@ "javascript": "```javascript\nasync function presentLoading() {\n const loading = document.createElement('ion-loading');\n\n loading.cssClass = 'my-custom-class';\n loading.message = 'Please wait...';\n loading.duration = 2000;\n\n document.body.appendChild(loading);\n await loading.present();\n\n const { role, data } = await loading.onDidDismiss();\n console.log('Loading dismissed!');\n}\n\nasync function presentLoadingWithOptions() {\n const loading = document.createElement('ion-loading');\n\n loading.spinner = null;\n loading.duration = 5000;\n loading.message = 'Click the backdrop to dismiss early...';\n loading.translucent = true;\n loading.cssClass = 'custom-class custom-loading';\n loading.backdropDismiss = true;\n\n document.body.appendChild(loading);\n await loading.present();\n\n const { role, data } = await loading.onDidDismiss();\n console.log('Loading dismissed with role:', role);\n}\n```\n", "react": "```tsx\n/* Using with useIonLoading Hook */\n\nimport React from 'react';\nimport { IonButton, IonContent, IonPage, useIonLoading } from '@ionic/react';\n\ninterface LoadingProps {}\n\nconst LoadingExample: React.FC = () => {\n const [present, dismiss] = useIonLoading();\n /**\n * The recommended way of dismissing is to use the `dismiss` property\n * on `IonLoading`, but the `dismiss` method returned from `useIonLoading`\n * can be used for more complex scenarios.\n */\n return (\n \n \n {\n present({\n message: 'Loading...',\n duration: 3000\n })\n }}\n >\n Show Loading\n \n present('Loading', 2000, 'dots')}\n >\n Show Loading using params\n \n \n \n );\n};\n```\n\n```tsx\n/* Using with IonLoading Component */\n\nimport React, { useState } from 'react';\nimport { IonLoading, IonButton, IonContent } from '@ionic/react';\n\nexport const LoadingExample: React.FC = () => {\n const [showLoading, setShowLoading] = useState(true);\n\n setTimeout(() => {\n setShowLoading(false);\n }, 2000);\n\n return (\n \n setShowLoading(true)}>Show Loading\n setShowLoading(false)}\n message={'Please wait...'}\n duration={5000}\n />\n \n );\n};\n```\n", "stencil": "```tsx\nimport { Component, h } from '@stencil/core';\n\nimport { loadingController } from '@ionic/core';\n\n@Component({\n tag: 'loading-example',\n styleUrl: 'loading-example.css'\n})\nexport class LoadingExample {\n async presentLoading() {\n const loading = await loadingController.create({\n cssClass: 'my-custom-class',\n message: 'Please wait...',\n duration: 2000\n });\n await loading.present();\n\n const { role, data } = await loading.onDidDismiss();\n console.log('Loading dismissed!', role, data);\n }\n\n async presentLoadingWithOptions() {\n const loading = await loadingController.create({\n spinner: null,\n duration: 5000,\n message: 'Click the backdrop to dismiss early...',\n translucent: true,\n cssClass: 'custom-class custom-loading',\n backdropDismiss: true\n });\n await loading.present();\n\n const { role, data } = await loading.onDidDismiss();\n console.log('Loading dismissed with role:', role, data);\n }\n\n render() {\n return [\n \n this.presentLoading()}>Present Loading\n this.presentLoadingWithOptions()}>Present Loading: Options\n \n ];\n }\n}\n```", - "vue": "```html\n\n\n\n```\n\nDevelopers can also use this component directly in their template:\n\n```html\n\n\n\n```\n" + "vue": "```html\n\n\n\n```\n\nDevelopers can also use this component directly in their template:\n\n```html\n\n\n\n```\n" }, "props": [ { @@ -10546,7 +10546,7 @@ "filePath": "./src/components/modal/modal.tsx", "encapsulation": "shadow", "tag": "ion-modal", - "readme": "# ion-modal\n\nA Modal is a dialog that appears on top of the app's content, and must be dismissed by the app before interaction can resume. It is useful as a select component when there are a lot of options to choose from, or when filtering items in a list, as well as many other use cases.\n\n## Presenting\n\nThere are two ways to use `ion-modal`: inline or via the `modalController`. Each method comes with different considerations, so be sure to use the approach that best fits your use case.\n\n## Inline Modals\n\n`ion-modal` can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the modal. See [Usage](#usage) for an example of how to write a modal inline. \n\nWhen using `ion-modal` with Angular, React, or Vue, the component you pass in will be destroyed when the modal is dismissed. As this functionality is provided by the JavaScript framework, using `ion-modal` without a JavaScript framework will not destroy the component you passed in. If this is a needed functionality, we recommend using the `modalController` instead.\n\n### Angular \n\nSince the component you passed in needs to be created when the modal is presented and destroyed when the modal is dismissed, we are unable to project the content using `` internally. Instead, we use `` which expects an `` to be passed in. As a result, when passing in your component you will need to wrap it in an ``:\n\n```html\n\n \n \n \n\n```\n\n### When to use\n\nUsing a modal inline is useful when you do not want to explicitly wire up click events to open the modal. For example, you can use the `is-open` property to easily present or dismiss a modal based on some state in your application.\n\nIf you need fine grained control over when the modal is presented and dismissed, we recommend you use the `modalController`. \n\n## Controller Modals\n\n`ion-modal` can also be presented programmatically by using the `modalController` imported from Ionic Framework. This allows you to have complete control over when a modal is presented above and beyond the customization that inline modals give you. See [Usage](#usage) for an example of how to use the `modalController`.\n\n### When to use\n\nWe typically recommend that you write your modals inline as it streamlines the amount of code in your application. You should only use the `modalController` for complex use cases where writing a modal inline is impractical.\n\n## Card Modal\n\nDevelopers can create a card modal effect where the modal appears as a card stacked on top of your app's main content. To create a card modal, developers need to set the `presentingElement` property and the `swipeToClose` properties on `ion-modal`.\n\nThe `presentingElement` property accepts a reference to the element that should display under your modal. This is typically a reference to `ion-router-outlet`.\n\nThe `swipeToClose` property can be used to control whether or not the card modal can be swiped to close.\n\nSee [Usage](#usage) for examples on how to use the sheet modal.\n\n## Sheet Modal\n\nDevelopers can create a sheet modal effect similar to the drawer components available in maps applications. To create a sheet modal, developers need to set the `breakpoints` and `initialBreakpoint` properties on `ion-modal`.\n\nThe `breakpoints` property accepts an array which states each breakpoint that the sheet can snap to when swiped. A `breakpoints` property of `[0, 0.5, 1]` would indicate that the sheet can be swiped to show 0% of the modal, 50% of the modal, and 100% of the modal. When the modal is swiped to 0%, the modal will be automatically dismissed.\n\nThe `initialBreakpoint` property is required so that the sheet modal knows which breakpoint to start at when presenting. The `initalBreakpoint` value must also exist in the `breakpoints` array. Given a `breakpoints` value of `[0, 0.5, 1]`, an `initialBreakpoint` value of `0.5` would be valid as `0.5` is in the `breakpoints` array. An `initialBreakpoint` value of `0.25` would not be valid as `0.25` does not exist in the `breakpoints` array.\n\nThe `backdropBreakpoint` property can be used to customize the point at which the `ion-backdrop` will begin to fade in. This is useful when creating interfaces that have content underneath the sheet that should remain interactive. A common use case is a sheet modal that overlays a map where the map is interactive until the sheet is fully expanded.\n\nSee [Usage](#usage) for examples on how to use the sheet modal.\n\n> Note: The `swipeToClose` property has no effect when using a sheet modal as sheet modals must be swipeable in order to be usable.\n\n## Interfaces\n\nBelow you will find all of the options available to you when using the `modalController`. These options should be supplied when calling `modalController.create()`.\n\n```typescript\ninterface ModalOptions {\n component: any;\n componentProps?: { [key: string]: any };\n presentingElement?: HTMLElement;\n showBackdrop?: boolean;\n backdropDismiss?: boolean;\n cssClass?: string | string[];\n animated?: boolean;\n swipeToClose?: boolean;\n\n mode?: 'ios' | 'md';\n keyboardClose?: boolean;\n id?: string;\n\n enterAnimation?: AnimationBuilder;\n leaveAnimation?: AnimationBuilder;\n}\n```\n\n## Dismissing\n\nThe modal can be dismissed after creation by calling the `dismiss()` method on the modal controller. The `onDidDismiss` function can be called to perform an action after the modal is dismissed.\n\n## Styling\n\nModals are presented at the root of your application so they overlay your entire app. This behavior applies to both inline modals and modals presented from a controller. As a result, custom modal styles can not be scoped to a particular component as they will not apply to the modal. Instead, styles must be applied globally. For most developers, placing the custom styles in `global.css` is sufficient.\n\n> If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.\n\n> `ion-modal` works under the assumption that stacked modals are the same size. As a result, each subsequent modal will have no box shadow and a backdrop opacity of `0`. This is to avoid the effect of shadows and backdrops getting darker with each added modal. This can be changed by setting the `--box-shadow` and `--backdrop-opacity` CSS variables:\n``` \nion-modal.stack-modal {\n --box-shadow: 0 28px 48px rgba(0, 0, 0, 0.4);\n --backdrop-opacity: var(--ion-backdrop-opacity, 0.32);\n}\n```\n\n## Interfaces\n\n### ModalOptions\n\n```typescript\ninterface ModalOptions {\n component: T;\n componentProps?: ComponentProps;\n presentingElement?: HTMLElement;\n showBackdrop?: boolean;\n backdropDismiss?: boolean;\n cssClass?: string | string[];\n animated?: boolean;\n swipeToClose?: boolean;\n\n mode?: Mode;\n keyboardClose?: boolean;\n id?: string;\n htmlAttributes?: ModalAttributes;\n\n enterAnimation?: AnimationBuilder;\n leaveAnimation?: AnimationBuilder;\n\n breakpoints?: number[];\n initialBreakpoint?: number;\n backdropBreakpoint?: number;\n handle?: boolean;\n}\n```\n\n### ModalAttributes\n\n```typescript\ninterface ModalAttributes extends JSXBase.HTMLAttributes {}\n```\n\n", + "readme": "# ion-modal\n\nA Modal is a dialog that appears on top of the app's content, and must be dismissed by the app before interaction can resume. It is useful as a select component when there are a lot of options to choose from, or when filtering items in a list, as well as many other use cases.\n\n## Presenting\n\nThere are two ways to use `ion-modal`: inline or via the `modalController`. Each method comes with different considerations, so be sure to use the approach that best fits your use case.\n\n## Inline Modals\n\n`ion-modal` can be used by writing the component directly in your template. This reduces the number of handlers you need to wire up in order to present the modal. See [Usage](#usage) for an example of how to write a modal inline. \n\nWhen using `ion-modal` with Angular, React, or Vue, the component you pass in will be destroyed when the modal is dismissed. As this functionality is provided by the JavaScript framework, using `ion-modal` without a JavaScript framework will not destroy the component you passed in. If this is a needed functionality, we recommend using the `modalController` instead.\n\n### Angular \n\nSince the component you passed in needs to be created when the modal is presented and destroyed when the modal is dismissed, we are unable to project the content using `` internally. Instead, we use `` which expects an `` to be passed in. As a result, when passing in your component you will need to wrap it in an ``:\n\n```html\n\n \n \n \n\n```\n\n### When to use\n\nUsing a modal inline is useful when you do not want to explicitly wire up click events to open the modal. For example, you can use the `is-open` property to easily present or dismiss a modal based on some state in your application.\n\nIf you need fine grained control over when the modal is presented and dismissed, we recommend you use the `modalController`. \n\n## Controller Modals\n\n`ion-modal` can also be presented programmatically by using the `modalController` imported from Ionic Framework. This allows you to have complete control over when a modal is presented above and beyond the customization that inline modals give you. See [Usage](#usage) for an example of how to use the `modalController`.\n\n### When to use\n\nWe typically recommend that you write your modals inline as it streamlines the amount of code in your application. You should only use the `modalController` for complex use cases where writing a modal inline is impractical.\n\n## Card Modal\n\nDevelopers can create a card modal effect where the modal appears as a card stacked on top of your app's main content. To create a card modal, developers need to set the `presentingElement` property and the `swipeToClose` properties on `ion-modal`.\n\nThe `presentingElement` property accepts a reference to the element that should display under your modal. This is typically a reference to `ion-router-outlet`.\n\nThe `swipeToClose` property can be used to control whether or not the card modal can be swiped to close.\n\nSee [Usage](#usage) for examples on how to use the sheet modal.\n\n## Sheet Modal\n\nDevelopers can create a sheet modal effect similar to the drawer components available in maps applications. To create a sheet modal, developers need to set the `breakpoints` and `initialBreakpoint` properties on `ion-modal`.\n\nThe `breakpoints` property accepts an array which states each breakpoint that the sheet can snap to when swiped. A `breakpoints` property of `[0, 0.5, 1]` would indicate that the sheet can be swiped to show 0% of the modal, 50% of the modal, and 100% of the modal. When the modal is swiped to 0%, the modal will be automatically dismissed.\n\nThe `initialBreakpoint` property is required so that the sheet modal knows which breakpoint to start at when presenting. The `initalBreakpoint` value must also exist in the `breakpoints` array. Given a `breakpoints` value of `[0, 0.5, 1]`, an `initialBreakpoint` value of `0.5` would be valid as `0.5` is in the `breakpoints` array. An `initialBreakpoint` value of `0.25` would not be valid as `0.25` does not exist in the `breakpoints` array.\n\nThe `backdropBreakpoint` property can be used to customize the point at which the `ion-backdrop` will begin to fade in. This is useful when creating interfaces that have content underneath the sheet that should remain interactive. A common use case is a sheet modal that overlays a map where the map is interactive until the sheet is fully expanded.\n\nSee [Usage](#usage) for examples on how to use the sheet modal.\n\n> Note: The `swipeToClose` property has no effect when using a sheet modal as sheet modals must be swipeable in order to be usable.\n\n## Interfaces\n\nBelow you will find all of the options available to you when using the `modalController`. These options should be supplied when calling `modalController.create()`.\n\n```typescript\ninterface ModalOptions {\n component: any;\n componentProps?: { [key: string]: any };\n presentingElement?: HTMLElement;\n showBackdrop?: boolean;\n backdropDismiss?: boolean;\n cssClass?: string | string[];\n animated?: boolean;\n swipeToClose?: boolean;\n\n mode?: 'ios' | 'md';\n keyboardClose?: boolean;\n id?: string;\n\n enterAnimation?: AnimationBuilder;\n leaveAnimation?: AnimationBuilder;\n}\n```\n\n## Dismissing\n\nThe modal can be dismissed after creation by calling the `dismiss()` method on the modal controller. The `onDidDismiss` function can be called to perform an action after the modal is dismissed.\n\n## Styling\n\nModals are presented at the root of your application so they overlay your entire app. This behavior applies to both inline modals and modals presented from a controller. As a result, custom modal styles can not be scoped to a particular component as they will not apply to the modal. Instead, styles must be applied globally. For most developers, placing the custom styles in `global.css` is sufficient.\n\n> If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. Read [Style Placement](#style-placement) in the Angular section below for more information.\n\n> `ion-modal` works under the assumption that stacked modals are the same size. As a result, each subsequent modal will have no box shadow and a backdrop opacity of `0`. This is to avoid the effect of shadows and backdrops getting darker with each added modal. This can be changed by setting the `--box-shadow` and `--backdrop-opacity` CSS variables:\n``` \nion-modal.stack-modal {\n --box-shadow: 0 28px 48px rgba(0, 0, 0, 0.4);\n --backdrop-opacity: var(--ion-backdrop-opacity, 0.32);\n}\n```\n\n## Interfaces\n\n### ModalOptions\n\n```typescript\ninterface ModalOptions {\n component: T;\n componentProps?: ComponentProps;\n presentingElement?: HTMLElement;\n showBackdrop?: boolean;\n backdropDismiss?: boolean;\n cssClass?: string | string[];\n animated?: boolean;\n swipeToClose?: boolean;\n\n mode?: Mode;\n keyboardClose?: boolean;\n id?: string;\n htmlAttributes?: ModalAttributes;\n\n enterAnimation?: AnimationBuilder;\n leaveAnimation?: AnimationBuilder;\n\n breakpoints?: number[];\n initialBreakpoint?: number;\n backdropBreakpoint?: number;\n handle?: boolean;\n}\n```\n\n### ModalAttributes\n\n```typescript\ninterface ModalAttributes extends JSXBase.HTMLAttributes {}\n```\n\n## Accessibility\n\n### Keyboard Navigation\n\n| Key | Function |\n| ----- | ------------------- |\n| `Esc` | Dismisses the modal |\n\n### Screen Readers\n\nModals have the `aria-modal` attribute applied. This attribute can cause assistive technologies to limit navigation to the modal element's contents. As a result, using gestures that move to the next or previous items may not focus elements outside of the modal. This applies even when the backdrop is disabled in sheet modals using the `backdropBreakpoint` property.\n\nAssistive technologies will not limit navigation to the modal element's contents if developers manually move focus. However, manually moving focus outside of a modal is not supported in Ionic for modals that have focus trapping enabled.\n\nSee https://w3c.github.io/aria/#aria-modal for more information.\n\n### Focus Trapping\n\nWhen a modal is presented, focus will be trapped inside of the presented modal. Users can focus other interactive elements inside the modal but will never be able to focus interactive elements outside the modal while the modal is presented. For applications that present multiple stacked modals, focus will be trapped on the modal that was presented last.\n\nSheet modals that have had their backdrop disabled by the `backdropBreakpoint` property are not subject to focus trapping.\n\n### Sheet Modals\n\nSheet modals allow users to interact with content behind the modal when the `backdropBreakpoint` property is used. The backdrop will be disabled up to and including the specified `backdropBreakpoint` and will be enabled after it.\n\nWhen the backdrop is disabled, users will be able to interact with elements outside the sheet modal using a pointer or keyboard. Assistive technologies may not focus outside the sheet modal by default due to the usage of `aria-modal`. We recommend avoiding features such as autofocus here as it can cause assistive technologies to jump between two interactive contexts without warning the user. \n", "docs": "A Modal is a dialog that appears on top of the app's content, and must be dismissed by the app before interaction can resume. It is useful as a select component when there are a lot of options to choose from, or when filtering items in a list, as well as many other use cases.", "docsTags": [ { @@ -19895,7 +19895,7 @@ "filePath": "./src/components/virtual-scroll/virtual-scroll.tsx", "encapsulation": "none", "tag": "ion-virtual-scroll", - "readme": "# ion-virtual-scroll\n\nVirtual Scroll displays a virtual, \"infinite\" list. An array of records\nis passed to the virtual scroll containing the data to create templates\nfor. The template created for each record, referred to as a cell, can\nconsist of items, headers, and footers. For performance reasons, not every record\nin the list is rendered at once; instead a small subset of records (enough to fill the viewport)\nare rendered and reused as the user scrolls.\n\nThis guide will go over the recommended virtual scrolling packages for each framework integration as well as documentation for the deprecated `ion-virtual-scroll` component for Ionic Angular. We recommend using the framework-specific solutions listed below, but the `ion-virtual-scroll` documentation is available below for developers who are still using that component.\n\n## Angular\n\nFor virtual scrolling options in Ionic Angular, please see [Angular Virtual Scroll Guide](../../angular/virtual-scroll).\n\n## React\n\nFor virtual scrolling options in Ionic React, please see [React Virtual Scroll Guide](../../react/virtual-scroll).\n\n## Vue\n\nFor virtual scrolling options in Ionic Vue, please see [Vue Virtual Scroll Guide](../../vue/virtual-scroll).\n\n------\n\nThe following documentation applies to the `ion-virtual-scroll` component.\n\n## Approximate Widths and Heights\n\nIf the height of items in the virtual scroll are not close to the\ndefault size of `40px`, it is extremely important to provide a value for\nthe `approxItemHeight` property. An exact pixel-perfect size is not necessary,\nbut without an estimate the virtual scroll will not render correctly.\n\nThe approximate width and height of each template is used to help\ndetermine how many cells should be created, and to help calculate\nthe height of the scrollable area. Note that the actual rendered size\nof each cell comes from the app's CSS, whereas this approximation\nis only used to help calculate initial dimensions.\n\nIt's also important to know that Ionic's default item sizes have\nslightly different heights between platforms, which is perfectly fine.\n\n## Images Within Virtual Scroll\n\nHTTP requests, image decoding, and image rendering can cause jank while\nscrolling. In order to better control images, Ionic provides ``\nto manage HTTP requests and image rendering. While scrolling through items\nquickly, `` knows when and when not to make requests, when and\nwhen not to render images, and only loads the images that are viewable\nafter scrolling. [Read more about `ion-img`.](../img)\n\nIt's also important for app developers to ensure image sizes are locked in,\nand after images have fully loaded they do not change size and affect any\nother element sizes. Simply put, to ensure rendering bugs are not introduced,\nit's vital that elements within a virtual item does not dynamically change.\n\nFor virtual scrolling, the natural effects of the `` are not desirable\nfeatures. We recommend using the `` component over the native\n`` element because when an `` element is added to the DOM, it\nimmediately makes a HTTP request for the image file. Additionally, ``\nrenders whenever it wants which could be while the user is scrolling. However,\n`` is governed by the containing `ion-content` and does not render\nimages while scrolling quickly.\n\n\n## Virtual Scroll Performance Tips\n\n### iOS Cordova WKWebView\n\nWhen deploying to iOS with Cordova, it's highly recommended to use the\n[WKWebView plugin](https://blog.ionicframework.com/cordova-ios-performance-improvements-drop-in-speed-with-wkwebview/)\nin order to take advantage of iOS's higher performing webview. Additionally,\nWKWebView is superior at scrolling efficiently in comparison to the older\nUIWebView.\n\n### Lock in element dimensions and locations\n\nIn order for virtual scroll to efficiently size and locate every item, it's\nvery important every element within each virtual item does not dynamically\nchange its dimensions or location. The best way to ensure size and location\ndoes not change, it's recommended each virtual item has locked in its size\nvia CSS.\n\n### Use `ion-img` for images\n\nWhen including images within Virtual Scroll, be sure to use\n[`ion-img`](../img) rather than the standard `` HTML element.\nWith `ion-img`, images are lazy loaded so only the viewable ones are\nrendered, and HTTP requests are efficiently controlled while scrolling.\n\n### Set Approximate Widths and Heights\n\nAs mentioned above, all elements should lock in their dimensions. However,\nvirtual scroll isn't aware of the dimensions until after they have been\nrendered. For the initial render, virtual scroll still needs to set\nhow many items should be built. With \"approx\" property inputs, such as\n`approxItemHeight`, we're able to give virtual scroll an approximate size,\ntherefore allowing virtual scroll to decide how many items should be\ncreated.\n\n### Changing dataset should use `trackBy`\n\nIt is possible for the identities of elements in the iterator to change\nwhile the data does not. This can happen, for example, if the iterator\nproduced from an RPC to the server, and that RPC is re-run. Even if the\n\"data\" hasn't changed, the second response will produce objects with\ndifferent identities, and Ionic will tear down the entire DOM and rebuild\nit. This is an expensive operation and should be avoided if possible.\n\n### Efficient headers and footer functions\nEach virtual item must stay extremely efficient, but one way to really\nkill its performance is to perform any DOM operations within section header\nand footer functions. These functions are called for every record in the\ndataset, so please make sure they're performant.\n", + "readme": "# ion-virtual-scroll\n\nVirtual Scroll displays a virtual, \"infinite\" list. An array of records\nis passed to the virtual scroll containing the data to create templates\nfor. The template created for each record, referred to as a cell, can\nconsist of items, headers, and footers. For performance reasons, not every record\nin the list is rendered at once; instead a small subset of records (enough to fill the viewport)\nare rendered and reused as the user scrolls.\n\nThis guide will go over the recommended virtual scrolling packages for each framework integration as well as documentation for the deprecated `ion-virtual-scroll` component for Ionic Angular. We recommend using the framework-specific solutions listed below, but the `ion-virtual-scroll` documentation is available below for developers who are still using that component.\n\n## Angular\n\nFor virtual scrolling options in Ionic Angular, please see [Angular Virtual Scroll Guide](../angular/virtual-scroll.md).\n\n## React\n\nFor virtual scrolling options in Ionic React, please see [React Virtual Scroll Guide](../react/virtual-scroll.md).\n\n## Vue\n\nFor virtual scrolling options in Ionic Vue, please see [Vue Virtual Scroll Guide](../vue/virtual-scroll.md).\n\n------\n\nThe following documentation applies to the `ion-virtual-scroll` component.\n\n## Approximate Widths and Heights\n\nIf the height of items in the virtual scroll are not close to the\ndefault size of `40px`, it is extremely important to provide a value for\nthe `approxItemHeight` property. An exact pixel-perfect size is not necessary,\nbut without an estimate the virtual scroll will not render correctly.\n\nThe approximate width and height of each template is used to help\ndetermine how many cells should be created, and to help calculate\nthe height of the scrollable area. Note that the actual rendered size\nof each cell comes from the app's CSS, whereas this approximation\nis only used to help calculate initial dimensions.\n\nIt's also important to know that Ionic's default item sizes have\nslightly different heights between platforms, which is perfectly fine.\n\n## Images Within Virtual Scroll\n\nHTTP requests, image decoding, and image rendering can cause jank while\nscrolling. In order to better control images, Ionic provides ``\nto manage HTTP requests and image rendering. While scrolling through items\nquickly, `` knows when and when not to make requests, when and\nwhen not to render images, and only loads the images that are viewable\nafter scrolling. [Read more about `ion-img`.](../img)\n\nIt's also important for app developers to ensure image sizes are locked in,\nand after images have fully loaded they do not change size and affect any\nother element sizes. Simply put, to ensure rendering bugs are not introduced,\nit's vital that elements within a virtual item does not dynamically change.\n\nFor virtual scrolling, the natural effects of the `` are not desirable\nfeatures. We recommend using the `` component over the native\n`` element because when an `` element is added to the DOM, it\nimmediately makes a HTTP request for the image file. Additionally, ``\nrenders whenever it wants which could be while the user is scrolling. However,\n`` is governed by the containing `ion-content` and does not render\nimages while scrolling quickly.\n\n\n## Virtual Scroll Performance Tips\n\n### iOS Cordova WKWebView\n\nWhen deploying to iOS with Cordova, it's highly recommended to use the\n[WKWebView plugin](https://blog.ionicframework.com/cordova-ios-performance-improvements-drop-in-speed-with-wkwebview/)\nin order to take advantage of iOS's higher performing webview. Additionally,\nWKWebView is superior at scrolling efficiently in comparison to the older\nUIWebView.\n\n### Lock in element dimensions and locations\n\nIn order for virtual scroll to efficiently size and locate every item, it's\nvery important every element within each virtual item does not dynamically\nchange its dimensions or location. The best way to ensure size and location\ndoes not change, it's recommended each virtual item has locked in its size\nvia CSS.\n\n### Use `ion-img` for images\n\nWhen including images within Virtual Scroll, be sure to use\n[`ion-img`](../img) rather than the standard `` HTML element.\nWith `ion-img`, images are lazy loaded so only the viewable ones are\nrendered, and HTTP requests are efficiently controlled while scrolling.\n\n### Set Approximate Widths and Heights\n\nAs mentioned above, all elements should lock in their dimensions. However,\nvirtual scroll isn't aware of the dimensions until after they have been\nrendered. For the initial render, virtual scroll still needs to set\nhow many items should be built. With \"approx\" property inputs, such as\n`approxItemHeight`, we're able to give virtual scroll an approximate size,\ntherefore allowing virtual scroll to decide how many items should be\ncreated.\n\n### Changing dataset should use `trackBy`\n\nIt is possible for the identities of elements in the iterator to change\nwhile the data does not. This can happen, for example, if the iterator\nproduced from an RPC to the server, and that RPC is re-run. Even if the\n\"data\" hasn't changed, the second response will produce objects with\ndifferent identities, and Ionic will tear down the entire DOM and rebuild\nit. This is an expensive operation and should be avoided if possible.\n\n### Efficient headers and footer functions\nEach virtual item must stay extremely efficient, but one way to really\nkill its performance is to perform any DOM operations within section header\nand footer functions. These functions are called for every record in the\ndataset, so please make sure they're performant.\n", "docs": "Virtual Scroll displays a virtual, \"infinite\" list. An array of records\nis passed to the virtual scroll containing the data to create templates\nfor. The template created for each record, referred to as a cell, can\nconsist of items, headers, and footers. For performance reasons, not every record\nin the list is rendered at once; instead a small subset of records (enough to fill the viewport)\nare rendered and reused as the user scrolls.\n\nThis guide will go over the recommended virtual scrolling packages for each framework integration as well as documentation for the deprecated `ion-virtual-scroll` component for Ionic Angular. We recommend using the framework-specific solutions listed below, but the `ion-virtual-scroll` documentation is available below for developers who are still using that component.", "docsTags": [], "usage": { diff --git a/packages/vue/test-app/tests/unit/routing.spec.ts b/packages/vue/test-app/tests/unit/routing.spec.ts index 82952bea5d..7749d96033 100644 --- a/packages/vue/test-app/tests/unit/routing.spec.ts +++ b/packages/vue/test-app/tests/unit/routing.spec.ts @@ -229,11 +229,13 @@ describe('Routing', () => { routes: [ { path: '/', redirect: '/tabs/tab1' }, { path: '/parent', component: Parent }, - { path: '/tabs/', component: Tabs, children: [ - { path: '/', redirect: 'tab1' }, - { path: 'tab1', component: Tab1 }, - { path: 'tab2', component: Tab2 } - ]} + { + path: '/tabs/', component: Tabs, children: [ + { path: '/', redirect: 'tab1' }, + { path: 'tab1', component: Tab1 }, + { path: 'tab2', component: Tab2 } + ] + } ] }); @@ -474,7 +476,7 @@ describe('Routing', () => { const router = createRouter({ history: createWebHistory(process.env.BASE_URL), routes: [ - { path: '/', component: Page } + { path: '/', component: Page }, { path: '/page2', component: Page2 } ] }); @@ -527,7 +529,7 @@ describe('Routing', () => { const router = createRouter({ history: createWebHistory(process.env.BASE_URL), routes: [ - { path: '/', component: Page } + { path: '/', component: Page }, { path: '/page2', component: Page2 }, { path: '/page3', component: Page3 }, ]