From 5e4d301be70083862812fe4cbf7dc0b7c9f99bc6 Mon Sep 17 00:00:00 2001 From: Maria Hutt Date: Wed, 26 Aug 2026 19:36:25 -0700 Subject: [PATCH] chore(docs): correct ignore lists and drop archived playground versions --- .prettierignore | 5 +- CONTRIBUTING.md | 9 +- _templates/playground/new/index.js | 2 +- docs/api/accordion-group.md | 12 +- docs/api/accordion.md | 47 ++++--- docs/api/action-sheet.md | 15 ++- docs/api/alert.md | 20 +-- docs/api/app.md | 26 ++-- docs/api/avatar.md | 13 +- docs/api/back-button.md | 15 ++- docs/api/backdrop.md | 13 +- docs/api/badge.md | 14 ++- docs/api/breadcrumb.md | 13 +- docs/api/breadcrumbs.md | 12 +- docs/api/button.md | 15 ++- docs/api/buttons.md | 31 +++-- docs/api/card-content.md | 11 +- docs/api/card-header.md | 11 +- docs/api/card-subtitle.md | 11 +- docs/api/card-title.md | 16 ++- docs/api/card.md | 21 ++-- docs/api/checkbox.md | 15 ++- docs/api/chip.md | 14 ++- docs/api/col.md | 19 +-- docs/api/content.md | 21 ++-- docs/api/datetime-button.md | 14 ++- docs/api/datetime.md | 50 ++++---- docs/api/fab-button.md | 17 ++- docs/api/fab-list.md | 11 +- docs/api/fab.md | 14 ++- docs/api/footer.md | 19 +-- docs/api/grid.md | 22 ++-- docs/api/header.md | 22 ++-- docs/api/img.md | 13 +- docs/api/infinite-scroll-content.md | 10 +- docs/api/infinite-scroll.md | 22 ++-- docs/api/input-otp.md | 39 ++++-- docs/api/input-password-toggle.md | 16 ++- docs/api/input.md | 22 ++-- docs/api/item-divider.md | 19 +-- docs/api/item-group.md | 16 ++- docs/api/item-option.md | 16 ++- docs/api/item-options.md | 21 ++-- docs/api/item-sliding.md | 19 +-- docs/api/item.md | 184 +++++++++++++++++++++++----- docs/api/label.md | 15 ++- docs/api/list-header.md | 14 ++- docs/api/list.md | 19 +-- docs/api/loading.md | 22 ++-- docs/api/menu-button.md | 16 ++- docs/api/menu-toggle.md | 16 ++- docs/api/menu.md | 23 ++-- docs/api/modal.md | 35 ++++-- docs/api/nav-link.md | 16 ++- docs/api/nav.md | 22 ++-- docs/api/note.md | 15 ++- docs/api/picker-column-option.md | 9 +- docs/api/picker-column.md | 9 +- docs/api/picker.md | 21 ++-- docs/api/popover.md | 28 +++-- docs/api/progress-bar.md | 21 ++-- docs/api/radio-group.md | 17 ++- docs/api/radio.md | 18 ++- docs/api/range.md | 18 ++- docs/api/refresher-content.md | 11 +- docs/api/refresher.md | 23 ++-- docs/api/reorder-group.md | 18 ++- docs/api/reorder.md | 21 ++-- docs/api/ripple-effect.md | 19 +-- docs/api/route-redirect.md | 28 +++-- docs/api/route.md | 101 +++++++-------- docs/api/router-link.md | 17 ++- docs/api/router-outlet.md | 20 ++- docs/api/router.md | 26 ++-- docs/api/row.md | 18 ++- docs/api/searchbar.md | 23 ++-- docs/api/segment-button.md | 21 ++-- docs/api/segment-content.md | 15 ++- docs/api/segment-view.md | 15 ++- docs/api/segment.md | 21 ++-- docs/api/select-option.md | 18 ++- docs/api/select.md | 55 +++++---- docs/api/skeleton-text.md | 16 ++- docs/api/spinner.md | 17 ++- docs/api/split-pane.md | 32 +++-- docs/api/tab-bar.md | 26 ++-- docs/api/tab-button.md | 32 ++--- docs/api/tab.md | 19 +-- docs/api/tabs.md | 14 ++- docs/api/text.md | 15 ++- docs/api/textarea.md | 14 ++- docs/api/thumbnail.md | 13 +- docs/api/title.md | 16 ++- docs/api/toast.md | 22 +++- docs/api/toggle.md | 19 +-- docs/api/toolbar.md | 25 ++-- 96 files changed, 1383 insertions(+), 688 deletions(-) diff --git a/.prettierignore b/.prettierignore index 956f8ee3d6..c761ae17b3 100644 --- a/.prettierignore +++ b/.prettierignore @@ -12,11 +12,12 @@ src/theme/prism-include-languages.ts legacy-stencil-components scripts/bak -docs/api -versioned_docs/version-v*/api +# Auto-generated files docs/native versioned_docs/version-v*/native docs/cli/commands +versioned_docs/version-v*/cli/commands + # Each definition in these files is one line of prose inside a JSX
. # Prettier's mdx parser reflows those children and moves link text onto its own # line, which MDX then wraps in a paragraph, rendering invalid HTML such as diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 24dc310f71..0e5d0bcc60 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -299,7 +299,14 @@ Everything from here on refers to ``: Then remove that version's `@ionic/` `allowedVersions` rule from `packageRules`, since it no longer has anything to match. -9. **Open a PR.** Once merged, the version picker links to the archive and `main` stops building ``. +9. **Update the playground generator.** Remove `` from the version choices in [`_templates/playground/new/index.js`](./_templates/playground/new/index.js) so `npm run playground:new` stops offering a version that is no longer built. The choices are bare numbers, without the `v`: + + ```diff + - choices: ['', '8', '9'], + + choices: ['8', '9'], + ``` + +10. **Open a PR.** Once merged, the version picker links to the archive and `main` stops building ``. Removed versions keep their `versioned_docs/` and `versioned_sidebars/` content, so they can be rebuilt anytime by adding them back to `versions.json`. diff --git a/_templates/playground/new/index.js b/_templates/playground/new/index.js index c69d04db73..f83047db8e 100644 --- a/_templates/playground/new/index.js +++ b/_templates/playground/new/index.js @@ -55,7 +55,7 @@ module.exports = { name: 'version', message: 'Select the Ionic Framework version for the playground', initial: '9', - choices: ['6', '7', '8', '9'], + choices: ['8', '9'], }, { type: 'toggle', diff --git a/docs/api/accordion-group.md b/docs/api/accordion-group.md index 3dc7a93f81..2fa5d47432 100644 --- a/docs/api/accordion-group.md +++ b/docs/api/accordion-group.md @@ -1,6 +1,7 @@ --- -title: "ion-accordion-group" +title: 'ion-accordion-group' --- + import Props from '@ionic-internal/component-api/v9/accordion-group/props.mdx'; import Events from '@ionic-internal/component-api/v9/accordion-group/events.mdx'; import Methods from '@ionic-internal/component-api/v9/accordion-group/methods.mdx'; @@ -16,7 +17,6 @@ Accordion group is a container for accordion instances. It manages the state of Refer to the [Accordion](./accordion) documentation for more information. - ## Interfaces ### AccordionGroupChangeEventDetail @@ -38,22 +38,26 @@ interface AccordionGroupCustomEvent extends CustomEvent { } ``` - - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/accordion.md b/docs/api/accordion.md index b5f5a5335f..bcd2a3528d 100644 --- a/docs/api/accordion.md +++ b/docs/api/accordion.md @@ -1,6 +1,7 @@ --- -title: "ion-accordion" +title: 'ion-accordion' --- + import Props from '@ionic-internal/component-api/v9/accordion/props.mdx'; import Events from '@ionic-internal/component-api/v9/accordion/events.mdx'; import Methods from '@ionic-internal/component-api/v9/accordion/methods.mdx'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v9/accordion/slots.mdx'; ion-accordion: Accordion Components: How to Build & Examples - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Accordions provide collapsible sections in your content to reduce vertical space while providing a way of organizing and grouping information. All `ion-accordion` components should be grouped inside `ion-accordion-group` components. ## Basic Usage @@ -120,18 +123,18 @@ import ExpansionStyles from '@site/static/usage/v9/accordion/customization/expan You can customize the expansion behavior by styling based on the accordion's state. There are four state classes applied to `ion-accordion`. Styling using these classes can allow you to create advanced state transitions: -| Class Name | Description | -| ---------- | ----------- | -| `.accordion-expanding` | Applied when the accordion is actively expanding | -| `.accordion-expanded` | Applied when the accordion is fully expanded | +| Class Name | Description | +| ----------------------- | ------------------------------------------------- | +| `.accordion-expanding` | Applied when the accordion is actively expanding | +| `.accordion-expanded` | Applied when the accordion is fully expanded | | `.accordion-collapsing` | Applied when the accordion is actively collapsing | -| `.accordion-collapsed` | Applied when the accordion is fully collapsed | +| `.accordion-collapsed` | Applied when the accordion is fully collapsed | If you need to target specific pieces of the accordion, we recommend targeting the element directly. For example, if you want to customize the ion-item in your header slot when the accordion is expanded, you can use the following selector: ```css -ion-accordion.accordion-expanding ion-item[slot="header"], -ion-accordion.accordion-expanded ion-item[slot="header"] { +ion-accordion.accordion-expanding ion-item[slot='header'], +ion-accordion.accordion-expanded ion-item[slot='header'] { --color: red; } ``` @@ -174,15 +177,15 @@ import AccessibilityAnimations from '@site/static/usage/v9/accordion/accessibili When used inside an `ion-accordion-group`, `ion-accordion` has full keyboard support for interacting with the component. The following table details what each key does: -| Key | Description | -| ------------------------------------ | ------------------------------------------------------------ | -| Space or Enter | When focus is on the accordion header, the accordion will collapse or expand depending on the state of the component. | -| Tab | Moves focus to the next focusable element. | -| Shift + Tab | Moves focus to the previous focusable element. | -| Down Arrow | - When focus is on an accordion header, moves focus to the next accordion header.
- When focus is on the last accordion header, moves focus to the first accordion header. | -| Up Arrow | - When focus is on an accordion header, moves focus to the previous accordion header.
- When focus is on the first accordion header, moves focus to the last accordion header. | -| Home | When focus is on an accordion header, moves focus to the first accordion header. | -| End | When focus is on an accordion header, moves focus to the last accordion header. | +| Key | Description | +| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Space or Enter | When focus is on the accordion header, the accordion will collapse or expand depending on the state of the component. | +| Tab | Moves focus to the next focusable element. | +| Shift + Tab | Moves focus to the previous focusable element. | +| Down Arrow | - When focus is on an accordion header, moves focus to the next accordion header.
- When focus is on the last accordion header, moves focus to the first accordion header. | +| Up Arrow | - When focus is on an accordion header, moves focus to the previous accordion header.
- When focus is on the first accordion header, moves focus to the last accordion header. | +| Home | When focus is on an accordion header, moves focus to the first accordion header. | +| End | When focus is on an accordion header, moves focus to the last accordion header. | ## Performance @@ -199,19 +202,25 @@ For example, lazily loading images may cause layout shifts as they load. As the 3. If neither of these options are applicable, developers may want to consider disabling animations altogether by using the `animated` property on [ion-accordion-group](./accordion-group). ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/action-sheet.md b/docs/api/action-sheet.md index b326c1ada0..7d7a50e048 100644 --- a/docs/api/action-sheet.md +++ b/docs/api/action-sheet.md @@ -1,6 +1,7 @@ --- -title: "ion-action-sheet" +title: 'ion-action-sheet' --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -13,14 +14,16 @@ import Slots from '@ionic-internal/component-api/v9/action-sheet/slots.mdx'; ion-action-sheet: Action Sheet Dialog for iOS and Android - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - An Action Sheet is a dialog that displays a set of options. It appears on top of the app's content, and must be manually dismissed by the user before they can resume interaction with the app. Destructive options are made obvious in `ios` mode. There are multiple ways to dismiss the action sheet, including tapping the backdrop or hitting the escape key on desktop. ## Inline Action Sheets (Recommended) @@ -280,19 +283,25 @@ interface ActionSheetOptions { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/alert.md b/docs/api/alert.md index a388cf60c7..b151a1c9fd 100644 --- a/docs/api/alert.md +++ b/docs/api/alert.md @@ -1,6 +1,7 @@ --- -title: "ion-alert" +title: 'ion-alert' --- + import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -13,7 +14,10 @@ import Slots from '@ionic-internal/component-api/v9/alert/slots.mdx'; ion-alert: Ionic Alert Buttons with Custom Message Prompts - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -58,7 +62,6 @@ import Buttons from '@site/static/usage/v9/alert/buttons/index.md'; - ## Inputs Alerts can also include several different inputs whose data can be passed back to the app. Inputs can be used as a simple way to prompt users for information. Radios, checkboxes and text inputs are all accepted, but they cannot be mixed. For example, an alert could have all radio button inputs, or all checkbox inputs, but the same alert cannot mix radio and checkbox inputs. Do note however, different types of "text" inputs can be mixed, such as `url`, `email`, `text`, `textarea` etc. If you require a complex form UI which doesn't fit within the guidelines of an alert then we recommend building the form within a modal instead. @@ -106,7 +109,7 @@ import Customization from '@site/static/usage/v9/alert/customization/index.md'; :::note - If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. +If you are building an Ionic Angular app, the styles need to be added to a global stylesheet file. ::: ## Accessibility @@ -181,7 +184,6 @@ const alert = await alertController.create({ - All ARIA attributes can be manually overwritten by defining custom values in the `htmlAttributes` property of the Alert. #### Alert Buttons Description @@ -281,7 +283,6 @@ interface AlertButton { } ``` - ### AlertInput ```typescript @@ -306,7 +307,6 @@ interface AlertInput { } ``` - ### AlertOptions ```typescript @@ -332,19 +332,25 @@ interface AlertOptions { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/app.md b/docs/api/app.md index eefae452ef..4e3a11d815 100644 --- a/docs/api/app.md +++ b/docs/api/app.md @@ -1,6 +1,7 @@ --- -title: "ion-app" +title: 'ion-app' --- + import Props from '@ionic-internal/component-api/v9/app/props.mdx'; import Events from '@ionic-internal/component-api/v9/app/events.mdx'; import Methods from '@ionic-internal/component-api/v9/app/methods.mdx'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v9/app/slots.mdx'; ion-app: Container Element for an Ionic Application - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -19,12 +23,12 @@ App is a container element for an Ionic application. There should only be one `< Using `ion-app` enables the following behaviors: -* [Keyboard Lifecycle Events](../developing/keyboard#keyboard-lifecycle-events) without the need for any native plugins -* [Hardware Back Button Listeners](../developing/hardware-back-button) for customizing the hardware back button behavior on Android devices -* Status bar support in Capacitor or Cordova which allows users to scroll to the top of the view by tapping the status bar -* Scroll assist utilities which scroll the content so focused text inputs are not covered by the on-screen keyboard -* [Ripple effect](./ripple-effect) when activating buttons on Material Design mode -* Other tap and focus utilities which make the experience of using an Ionic app feel more native +- [Keyboard Lifecycle Events](../developing/keyboard#keyboard-lifecycle-events) without the need for any native plugins +- [Hardware Back Button Listeners](../developing/hardware-back-button) for customizing the hardware back button behavior on Android devices +- Status bar support in Capacitor or Cordova which allows users to scroll to the top of the view by tapping the status bar +- Scroll assist utilities which scroll the content so focused text inputs are not covered by the on-screen keyboard +- [Ripple effect](./ripple-effect) when activating buttons on Material Design mode +- Other tap and focus utilities which make the experience of using an Ionic app feel more native ## Programmatic Focus @@ -35,19 +39,25 @@ import SetFocus from '@site/static/usage/v9/app/set-focus/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/avatar.md b/docs/api/avatar.md index e27de6fac4..820d8442a3 100644 --- a/docs/api/avatar.md +++ b/docs/api/avatar.md @@ -1,5 +1,5 @@ --- -title: "ion-avatar" +title: 'ion-avatar' --- import Props from '@ionic-internal/component-api/v9/avatar/props.mdx'; @@ -11,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v9/avatar/slots.mdx'; ion-avatar: Circular Application Avatar Icon Component - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -49,19 +52,25 @@ import CSSProps from '@site/static/usage/v9/avatar/theming/css-properties/index. ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/back-button.md b/docs/api/back-button.md index bd2e7f7b0f..af92d0a5da 100644 --- a/docs/api/back-button.md +++ b/docs/api/back-button.md @@ -1,6 +1,7 @@ --- -title: "ion-back-button" +title: 'ion-back-button' --- + import Props from '@ionic-internal/component-api/v9/back-button/props.mdx'; import Events from '@ionic-internal/component-api/v9/back-button/events.mdx'; import Methods from '@ionic-internal/component-api/v9/back-button/methods.mdx'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v9/back-button/slots.mdx'; ion-back-button: Custom Menu Back Button for Applications - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The back button navigates back in the app's history when clicked. It is only displayed when there is history in the navigation stack, unless [`defaultHref`](#default-back-history) is set. The back button displays different text and icon based on the mode, but this can be customized. ## Basic Usage @@ -39,19 +42,25 @@ import Custom from '@site/static/usage/v9/back-button/custom/index.md'; Occasionally an app may need to show the back button and navigate back when there is no history. This can be done by setting the `defaultHref` on the back button to a path. In order to use `defaultHref`, the app must contain a router with paths set. ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/backdrop.md b/docs/api/backdrop.md index 08253dadb9..b410f1724d 100644 --- a/docs/api/backdrop.md +++ b/docs/api/backdrop.md @@ -1,6 +1,7 @@ --- -title: "ion-backdrop" +title: 'ion-backdrop' --- + import Props from '@ionic-internal/component-api/v9/backdrop/props.mdx'; import Events from '@ionic-internal/component-api/v9/backdrop/events.mdx'; import Methods from '@ionic-internal/component-api/v9/backdrop/methods.mdx'; @@ -24,7 +25,7 @@ import Basic from '@site/static/usage/v9/backdrop/basic/index.md'; ## Styling -The backdrop can be customized by assigning CSS properties directly to the backdrop element. Common properties include `background-color`, `background` and `opacity`. +The backdrop can be customized by assigning CSS properties directly to the backdrop element. Common properties include `background-color`, `background` and `opacity`. Content can be displayed above the backdrop by setting a `z-index` on the content, higher than the backdrop (defaults to `2`). @@ -33,19 +34,25 @@ import Styling from '@site/static/usage/v9/backdrop/styling/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots - \ No newline at end of file + + diff --git a/docs/api/badge.md b/docs/api/badge.md index c720ed1336..fa8ac902ad 100644 --- a/docs/api/badge.md +++ b/docs/api/badge.md @@ -1,6 +1,7 @@ --- -title: "ion-badge" +title: 'ion-badge' --- + import Props from '@ionic-internal/component-api/v9/badge/props.mdx'; import Events from '@ionic-internal/component-api/v9/badge/events.mdx'; import Methods from '@ionic-internal/component-api/v9/badge/methods.mdx'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v9/badge/slots.mdx'; ion-badge: iOS & Android App Notification Badge Icons - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -52,19 +56,25 @@ import CSSProps from '@site/static/usage/v9/badge/theming/css-properties/index.m ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/breadcrumb.md b/docs/api/breadcrumb.md index cf087a8eb9..315371ce3e 100644 --- a/docs/api/breadcrumb.md +++ b/docs/api/breadcrumb.md @@ -1,6 +1,7 @@ --- -title: "ion-breadcrumb" +title: 'ion-breadcrumb' --- + import Props from '@ionic-internal/component-api/v9/breadcrumb/props.mdx'; import Events from '@ionic-internal/component-api/v9/breadcrumb/events.mdx'; import Methods from '@ionic-internal/component-api/v9/breadcrumb/methods.mdx'; @@ -12,7 +13,6 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; - A Breadcrumb is a single navigation item that is a child of the Breadcrumbs component. A breadcrumb can link elsewhere in an app or it can be plain text. Each breadcrumb has a separator between it and the next breadcrumb and can optionally contain an icon. Refer to the [Breadcrumbs](./breadcrumbs) documentation for more information. @@ -38,23 +38,26 @@ interface BreadcrumbCustomEvent extends CustomEvent { } ``` - - - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/breadcrumbs.md b/docs/api/breadcrumbs.md index 3e7255ecd8..0b787c195d 100644 --- a/docs/api/breadcrumbs.md +++ b/docs/api/breadcrumbs.md @@ -1,6 +1,7 @@ --- -title: "ion-breadcrumbs" +title: 'ion-breadcrumbs' --- + import Props from '@ionic-internal/component-api/v9/breadcrumbs/props.mdx'; import Events from '@ionic-internal/component-api/v9/breadcrumbs/events.mdx'; import Methods from '@ionic-internal/component-api/v9/breadcrumbs/methods.mdx'; @@ -8,8 +9,6 @@ import Parts from '@ionic-internal/component-api/v9/breadcrumbs/parts.mdx'; import CustomProps from '@ionic-internal/component-api/v9/breadcrumbs/custom-props.mdx'; import Slots from '@ionic-internal/component-api/v9/breadcrumbs/slots.mdx'; - - import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -84,21 +83,26 @@ import CSSProps from '@site/static/usage/v9/breadcrumbs/theming/css-properties/i - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/button.md b/docs/api/button.md index 7a8348eb15..9f8adea40d 100644 --- a/docs/api/button.md +++ b/docs/api/button.md @@ -1,6 +1,7 @@ --- -title: "ion-button" +title: 'ion-button' --- + import Props from '@ionic-internal/component-api/v9/button/props.mdx'; import Events from '@ionic-internal/component-api/v9/button/events.mdx'; import Methods from '@ionic-internal/component-api/v9/button/methods.mdx'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v9/button/slots.mdx'; ion-button: Style Buttons with Custom CSS Properties - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -41,7 +45,6 @@ import Shape from '@site/static/usage/v9/button/shape/index.md'; - ## Fill This property determines the background and border color of the button. By default, buttons have a solid background unless the button is inside of a toolbar, in which case it has a transparent background. @@ -97,19 +100,25 @@ import TextWrapping from '@site/static/usage/v9/button/text-wrapping/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/buttons.md b/docs/api/buttons.md index 2fa1c024eb..30a16b1c9c 100644 --- a/docs/api/buttons.md +++ b/docs/api/buttons.md @@ -1,6 +1,7 @@ --- -title: "ion-buttons" +title: 'ion-buttons' --- + import Props from '@ionic-internal/component-api/v9/buttons/props.mdx'; import Events from '@ionic-internal/component-api/v9/buttons/events.mdx'; import Methods from '@ionic-internal/component-api/v9/buttons/methods.mdx'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v9/buttons/slots.mdx'; ion-buttons: Toolbar Element with Named Slots for Buttons - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The Buttons component is a container element. It should be used inside of a [toolbar](./toolbar) and can contain several types of buttons, including standard [buttons](./button), [menu buttons](./menu-button), and [back buttons](./back-button). ## Basic Usage @@ -26,23 +29,21 @@ import Basic from '@site/static/usage/v9/buttons/basic/index.md'; - ## Buttons Placement Buttons can be positioned inside of the toolbar using a named slot. The below chart has a description of each slot. -| Slot | Description | -|--------------|----------------------------------------------------------------------------------------------------------| -| `start` | Positions to the `left` of the content in LTR, and to the `right` in RTL. | -| `end` | Positions to the `right` of the content in LTR, and to the `left` in RTL. | -| `secondary` | Positions element to the `left` of the content in `ios` mode, and directly to the `right` in `md` mode. | -| `primary` | Positions element to the `right` of the content in `ios` mode, and to the far `right` in `md` mode. | +| Slot | Description | +| ----------- | ------------------------------------------------------------------------------------------------------- | +| `start` | Positions to the `left` of the content in LTR, and to the `right` in RTL. | +| `end` | Positions to the `right` of the content in LTR, and to the `left` in RTL. | +| `secondary` | Positions element to the `left` of the content in `ios` mode, and directly to the `right` in `md` mode. | +| `primary` | Positions element to the `right` of the content in `ios` mode, and to the far `right` in `md` mode. | import Placement from '@site/static/usage/v9/buttons/placement/index.md'; - ## Types of Buttons A button in a toolbar is styled to be clear by default, but this can be changed using the [`fill`](./button#fill) property on the button. The properties included on [back button](./back-button) and [menu button](./menu-button) in this example are for display purposes; refer to their respective documentation for proper usage. @@ -51,7 +52,6 @@ import Types from '@site/static/usage/v9/buttons/types/index.md'; - ## Collapsible Buttons The `collapse` property can be set on the buttons to collapse them when the header collapses. This is typically used with [collapsible large titles](./title#collapsible-large-titles). @@ -67,21 +67,26 @@ import CollapsibleLargeTitleButtons from '@site/static/usage/v9/title/collapsibl - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/card-content.md b/docs/api/card-content.md index 23833ccf86..6e7671eb1a 100644 --- a/docs/api/card-content.md +++ b/docs/api/card-content.md @@ -1,6 +1,7 @@ --- -title: "ion-card-content" +title: 'ion-card-content' --- + import Props from '@ionic-internal/component-api/v9/card-content/props.mdx'; import Events from '@ionic-internal/component-api/v9/card-content/events.mdx'; import Methods from '@ionic-internal/component-api/v9/card-content/methods.mdx'; @@ -10,26 +11,30 @@ import Slots from '@ionic-internal/component-api/v9/card-content/slots.mdx'; import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Card content is a child component of card that adds padding around its contents. It is recommended that any text content for a card should be placed inside of card content. Refer to the [Card](./card) documentation for more information. - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/card-header.md b/docs/api/card-header.md index baebad56a4..d0428dbbb6 100644 --- a/docs/api/card-header.md +++ b/docs/api/card-header.md @@ -1,6 +1,7 @@ --- -title: "ion-card-header" +title: 'ion-card-header' --- + import Props from '@ionic-internal/component-api/v9/card-header/props.mdx'; import Events from '@ionic-internal/component-api/v9/card-header/events.mdx'; import Methods from '@ionic-internal/component-api/v9/card-header/methods.mdx'; @@ -12,26 +13,30 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Card header is a child component of card that should be placed before the card content. It can contain a [card title](./card-title) and a [card subtitle](./card-subtitle). Refer to the [Card](./card) documentation for more information. - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/card-subtitle.md b/docs/api/card-subtitle.md index 4fdcf06548..0bf881f168 100644 --- a/docs/api/card-subtitle.md +++ b/docs/api/card-subtitle.md @@ -1,6 +1,7 @@ --- -title: "ion-card-subtitle" +title: 'ion-card-subtitle' --- + import Props from '@ionic-internal/component-api/v9/card-subtitle/props.mdx'; import Events from '@ionic-internal/component-api/v9/card-subtitle/events.mdx'; import Methods from '@ionic-internal/component-api/v9/card-subtitle/methods.mdx'; @@ -12,26 +13,30 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Card subtitle is a child component of card that should be placed inside of a [card header](./card-header). Refer to the [Card](./card) documentation for more information. - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/card-title.md b/docs/api/card-title.md index 38df96d475..b828bb1dfb 100644 --- a/docs/api/card-title.md +++ b/docs/api/card-title.md @@ -1,6 +1,7 @@ --- -title: "ion-card-title" +title: 'ion-card-title' --- + import Props from '@ionic-internal/component-api/v9/card-title/props.mdx'; import Events from '@ionic-internal/component-api/v9/card-title/events.mdx'; import Methods from '@ionic-internal/component-api/v9/card-title/methods.mdx'; @@ -12,31 +13,38 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; ion-card-title: Ionic App Card Title Component - + - Card title is a child component of card that should be placed inside of a [card header](./card-header). Refer to the [Card](./card) documentation for more information. - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/card.md b/docs/api/card.md index 78828e630d..c31373c39a 100644 --- a/docs/api/card.md +++ b/docs/api/card.md @@ -1,6 +1,7 @@ --- -title: "ion-card" +title: 'ion-card' --- + import Props from '@ionic-internal/component-api/v9/card/props.mdx'; import Events from '@ionic-internal/component-api/v9/card/events.mdx'; import Methods from '@ionic-internal/component-api/v9/card/methods.mdx'; @@ -12,47 +13,44 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; ion-card: Card UI Components for Ionic Framework API - + - Cards are containers that display content such as text, images, buttons, and lists. A card can be a single component, but is often made up of a header, title, subtitle, and content. Cards are broken up into several components to accommodate this structure: [card header](./card-header), [card title](./card-title), [card subtitle](./card-subtitle), and [card content](./card-content). - ## Basic Usage import Basic from '@site/static/usage/v9/card/basic/index.md'; - ## Media Cards import Media from '@site/static/usage/v9/card/media/index.md'; - ## Card Buttons import Buttons from '@site/static/usage/v9/card/buttons/index.md'; - ## List Card import List from '@site/static/usage/v9/card/list/index.md'; - ## Theming ### Colors @@ -67,21 +65,26 @@ import CSSProps from '@site/static/usage/v9/card/theming/css-properties/index.md - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/checkbox.md b/docs/api/checkbox.md index ac8d53ccf3..2ca87ed328 100644 --- a/docs/api/checkbox.md +++ b/docs/api/checkbox.md @@ -1,5 +1,5 @@ --- -title: "ion-checkbox" +title: 'ion-checkbox' --- import Props from '@ionic-internal/component-api/v9/checkbox/props.mdx'; @@ -11,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v9/checkbox/slots.mdx'; ion-checkbox: Ionic App Checkbox to Select Multiple Options - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Checkboxes allow the selection of multiple options from a set of options. They appear as checked (ticked) when activated. Clicking on a checkbox will toggle the `checked` property. They can also be checked programmatically by setting the `checked` property. ## Basic Usage @@ -55,7 +57,6 @@ import Justify from '@site/static/usage/v9/checkbox/justify/index.md'; - :::note `ion-item` is only used in the demos to emphasize how `justify` works. It is not needed in order for `justify` to function correctly. ::: @@ -115,19 +116,25 @@ interface CheckboxCustomEvent extends CustomEvent { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/chip.md b/docs/api/chip.md index 518e8a4f34..3ac157f818 100644 --- a/docs/api/chip.md +++ b/docs/api/chip.md @@ -1,6 +1,7 @@ --- -title: "ion-chip" +title: 'ion-chip' --- + import Props from '@ionic-internal/component-api/v9/chip/props.mdx'; import Events from '@ionic-internal/component-api/v9/chip/events.mdx'; import Methods from '@ionic-internal/component-api/v9/chip/methods.mdx'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v9/chip/slots.mdx'; ion-chip: Text, Icon and Avatar for Ionic Framework Apps - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -46,19 +50,25 @@ import CSSProps from '@site/static/usage/v9/chip/theming/css-properties/index.md ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/col.md b/docs/api/col.md index bd36bd00f6..920d47f0a0 100644 --- a/docs/api/col.md +++ b/docs/api/col.md @@ -1,6 +1,7 @@ --- -title: "ion-col" +title: 'ion-col' --- + import Props from '@ionic-internal/component-api/v9/col/props.mdx'; import Events from '@ionic-internal/component-api/v9/col/events.mdx'; import Methods from '@ionic-internal/component-api/v9/col/methods.mdx'; @@ -10,40 +11,44 @@ import Slots from '@ionic-internal/component-api/v9/col/slots.mdx'; ion-col: Column Component Padding and Other Properties - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Columns are cellular components of the [grid](./grid) system and go inside of a [row](./row). They will expand to fill the row. All content within a grid should go inside of a column. Refer to the [grid](./grid) documentation for more information. - ## Column Alignment By default, columns will stretch to fill the entire height of the row. Columns are [flex items](https://developer.mozilla.org/en-US/docs/Glossary/Flex_Item), so there are several [CSS classes](/docs/layout/css-utilities#flex-item-properties) that can be applied to a column to customize this behavior. - - - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/content.md b/docs/api/content.md index 2cf74e851f..660275a8a3 100644 --- a/docs/api/content.md +++ b/docs/api/content.md @@ -1,6 +1,7 @@ --- -title: "ion-content" +title: 'ion-content' --- + import Props from '@ionic-internal/component-api/v9/content/props.mdx'; import Events from '@ionic-internal/component-api/v9/content/events.mdx'; import Methods from '@ionic-internal/component-api/v9/content/methods.mdx'; @@ -10,28 +11,28 @@ import Slots from '@ionic-internal/component-api/v9/content/slots.mdx'; ion-content: Scrollable Component for Ionic App Content - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The content component provides an easy to use content area with some useful methods to control the scrollable area. There should only be one content in a single view. Content, along with many other Ionic components, can be customized to modify its padding, margin, and more using the global styles provided in the [CSS Utilities](/docs/layout/css-utilities) or by individually styling it using CSS and the available [CSS Custom Properties](#css-custom-properties). - ## Basic Usage import Basic from '@site/static/usage/v9/content/basic/index.md'; - ## Header & Footer Content can be the only top-level component in a page, or it can be used alongside a [header](./header), [footer](./footer), or both. When used with a header or footer, it will adjust its size to fill the remaining height. @@ -40,7 +41,6 @@ import HeaderFooter from '@site/static/usage/v9/content/header-footer/index.md'; - ## Fullscreen Content By default, content fills the space between a [header](./header) and [footer](./footer) but does not go behind them. In certain cases, it may be desired to have the content scroll behind the header and footer, such as when the `translucent` property is set on either of them, or `opacity` is set on the toolbar. This can be achieved by setting the `fullscreen` property on the content to `true`. @@ -49,7 +49,6 @@ import Fullscreen from '@site/static/usage/v9/content/fullscreen/index.md'; - ## Fixed Content To place elements outside of the scrollable area, assign them to the `fixed` slot. Doing so will [absolutely position](https://developer.mozilla.org/en-US/docs/Web/CSS/position#absolute_positioning) the element to the top left of the content. In order to change the position of the element, it can be styled using the [top, right, bottom, and left](https://developer.mozilla.org/en-US/docs/Web/CSS/position) CSS properties. @@ -76,7 +75,6 @@ import ScrollEvents from '@site/static/usage/v9/content/scroll-events/index.md'; - ## Theming ### Colors @@ -161,21 +159,26 @@ interface ScrollCustomEvent extends ScrollBaseCustomEvent { } ``` - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/datetime-button.md b/docs/api/datetime-button.md index 50da6bead6..597442a285 100644 --- a/docs/api/datetime-button.md +++ b/docs/api/datetime-button.md @@ -1,6 +1,7 @@ --- -title: "ion-datetime-button" +title: 'ion-datetime-button' --- + import Props from '@ionic-internal/component-api/v9/datetime-button/props.mdx'; import Events from '@ionic-internal/component-api/v9/datetime-button/events.mdx'; import Methods from '@ionic-internal/component-api/v9/datetime-button/methods.mdx'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v9/datetime-button/slots.mdx'; ion-datetime-button: Ionic Input for Datetime Picker - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -48,19 +52,25 @@ import FormatOptions from '@site/static/usage/v9/datetime-button/format-options/ `ion-datetime-button` must be associated with a mounted `ion-datetime` instance. As a result, [Inline Modals](./modal#inline-modals-recommended) and [Inline Popovers](./popover#inline-popovers) with the `keepContentsMounted` property set to `true` must be used. ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/datetime.md b/docs/api/datetime.md index c84533ca8e..67b4587116 100644 --- a/docs/api/datetime.md +++ b/docs/api/datetime.md @@ -1,6 +1,7 @@ --- -title: "ion-datetime" +title: 'ion-datetime' --- + import Props from '@ionic-internal/component-api/v9/datetime/props.mdx'; import Events from '@ionic-internal/component-api/v9/datetime/events.mdx'; import Methods from '@ionic-internal/component-api/v9/datetime/methods.mdx'; @@ -48,7 +49,10 @@ import WheelStyling from '@site/static/usage/v9/datetime/styling/wheel-styling/i ion-datetime: Ionic API Input for Datetime Format Picker - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -77,15 +81,15 @@ and parse within JSON objects and databases. Below are some examples of ISO 8601 formats that can be used with `ion-datetime`: -| Description | Format | Datetime Value Example | -| -------------------- | ------------------------ | ------------------------------ | -| Year | `YYYY` | `1994` | -| Year and Month | `YYYY-MM` | `1994-12` | -| Complete Date | `YYYY-MM-DD` | `1994-12-15` | -| Date and Time | `YYYY-MM-DDTHH:mm` | `1994-12-15T13:47` | -| UTC Timezone | `YYYY-MM-DDTHH:mm:ssZ` | `1994-12-15T13:47:20Z` | -| Timezone Offset | `YYYY-MM-DDTHH:mm:ssTZD` | `1994-12-15T13:47:20+05:00` | -| Hour and Minute | `HH:mm` | `13:47` | +| Description | Format | Datetime Value Example | +| --------------- | ------------------------ | --------------------------- | +| Year | `YYYY` | `1994` | +| Year and Month | `YYYY-MM` | `1994-12` | +| Complete Date | `YYYY-MM-DD` | `1994-12-15` | +| Date and Time | `YYYY-MM-DDTHH:mm` | `1994-12-15T13:47` | +| UTC Timezone | `YYYY-MM-DDTHH:mm:ssZ` | `1994-12-15T13:47:20Z` | +| Timezone Offset | `YYYY-MM-DDTHH:mm:ssTZD` | `1994-12-15T13:47:20+05:00` | +| Hour and Minute | `HH:mm` | `13:47` | Note that the year is always four-digits, milliseconds (if it's added) is always three-digits, and all others are always two-digits. So the number representing @@ -158,18 +162,17 @@ The time label is not automatically localized. Refer to [Time Label](#time-label There are 4 primary hour cycle types: -| Hour cycle type | Description | -| --------------- | ------------------------------------------------------------ | -| `'h12'` | Hour system using 1–12; corresponds to 'h' in patterns. The 12 hour clock, with midnight starting at 12:00 am. | -| `'h23'` | Hour system using 0–23; corresponds to 'H' in patterns. The 24 hour clock, with midnight starting at 0:00. | -| `'h11'` | Hour system using 0–11; corresponds to 'K' in patterns. The 12 hour clock, with midnight starting at 0:00 am. | -| `'h24'` | Hour system using 1–24; corresponds to 'k' in pattern. The 24 hour clock, with midnight starting at 24:00. | +| Hour cycle type | Description | +| --------------- | -------------------------------------------------------------------------------------------------------------- | +| `'h12'` | Hour system using 1–12; corresponds to 'h' in patterns. The 12 hour clock, with midnight starting at 12:00 am. | +| `'h23'` | Hour system using 0–23; corresponds to 'H' in patterns. The 24 hour clock, with midnight starting at 0:00. | +| `'h11'` | Hour system using 0–11; corresponds to 'K' in patterns. The 12 hour clock, with midnight starting at 0:00 am. | +| `'h24'` | Hour system using 1–24; corresponds to 'k' in pattern. The 24 hour clock, with midnight starting at 24:00. | :::note - Source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/hourCycle +Source: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/hourCycle ::: - There may be scenarios where you need to have more control over which hour cycle is used. This is where the `hourCycle` property can help. In 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: @@ -197,7 +200,7 @@ For example, if you wanted to use a 12 hour cycle with the `en-GB` locale, you c :::note -Be sure to check the [Browser Compatibility Chart](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale#browser_compatibility) for `Intl.Locale` before using it in your app. +Be sure to check the [Browser Compatibility Chart](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale#browser_compatibility) for `Intl.Locale` before using it in your app. ::: ## Presentation @@ -435,7 +438,6 @@ console.log(formattedString); // Jun 4, 2021 See https://date-fns.org/docs/format for a list of all the valid format tokens. - ## Advanced Datetime Validation and Manipulation The datetime picker provides the simplicity of selecting an exact format, and @@ -501,19 +503,25 @@ interface DatetimeCustomEvent extends CustomEvent { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/fab-button.md b/docs/api/fab-button.md index 18523dfbd1..c2aab48e30 100644 --- a/docs/api/fab-button.md +++ b/docs/api/fab-button.md @@ -1,6 +1,7 @@ --- -title: "ion-fab-button" +title: 'ion-fab-button' --- + import Props from '@ionic-internal/component-api/v9/fab-button/props.mdx'; import Events from '@ionic-internal/component-api/v9/fab-button/events.mdx'; import Methods from '@ionic-internal/component-api/v9/fab-button/methods.mdx'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v9/fab-button/slots.mdx'; ion-fab-button: Ionic FAB Button Icon for Primary Action - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Floating Action Buttons (FABs) represent the primary action in an application. By default, they have a circular shape. When pressed, the button may open more related actions. As the name suggests, FABs generally float over the content in a fixed position. This is achieved by wrapping the fab button in a [fab](./fab) component. If the button is not wrapped with a fab, it will scroll with the content. @@ -25,19 +28,25 @@ As the name suggests, FABs generally float over the content in a fixed position. For usage examples, refer to the [fab documentation](./fab). ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots - \ No newline at end of file + + diff --git a/docs/api/fab-list.md b/docs/api/fab-list.md index 566b2f7ad3..5a2a912917 100644 --- a/docs/api/fab-list.md +++ b/docs/api/fab-list.md @@ -1,6 +1,7 @@ --- -title: "ion-fab-list" +title: 'ion-fab-list' --- + import Props from '@ionic-internal/component-api/v9/fab-list/props.mdx'; import Events from '@ionic-internal/component-api/v9/fab-list/events.mdx'; import Methods from '@ionic-internal/component-api/v9/fab-list/methods.mdx'; @@ -17,19 +18,25 @@ The fab list component is a container for multiple [fab buttons](./fab-button). For usage examples, refer to the [fab documentation](./fab). ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots - \ No newline at end of file + + diff --git a/docs/api/fab.md b/docs/api/fab.md index 6723ebd592..ca8924dfe0 100644 --- a/docs/api/fab.md +++ b/docs/api/fab.md @@ -1,6 +1,7 @@ --- -title: "ion-fab" +title: 'ion-fab' --- + import Props from '@ionic-internal/component-api/v9/fab/props.mdx'; import Events from '@ionic-internal/component-api/v9/fab/events.mdx'; import Methods from '@ionic-internal/component-api/v9/fab/methods.mdx'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v9/fab/slots.mdx'; ion-fab: Ionic Floating Action Button for Android and iOS - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -112,19 +116,25 @@ import CSSShadowParts from '@site/static/usage/v9/fab/theming/css-shadow-parts/i Since FABs are allowed to contain only icons, developers must provide an `aria-label` on each `ion-fab-button` instance. Without this label, assistive technologies will not be able to announce the purpose of each button. ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/footer.md b/docs/api/footer.md index 2ca6198762..0d1a667779 100644 --- a/docs/api/footer.md +++ b/docs/api/footer.md @@ -1,6 +1,7 @@ --- -title: "ion-footer" +title: 'ion-footer' --- + import Props from '@ionic-internal/component-api/v9/footer/props.mdx'; import Events from '@ionic-internal/component-api/v9/footer/events.mdx'; import Methods from '@ionic-internal/component-api/v9/footer/methods.mdx'; @@ -10,12 +11,14 @@ import Slots from '@ionic-internal/component-api/v9/footer/slots.mdx'; ion-footer: Page Footer | Ionic App Footer Root Component - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Footer is a root component of a page that aligns itself to the bottom of the page. It is recommended to be used as a wrapper for one or more [toolbars](./toolbar), but it can be used to wrap any element. When a toolbar is used inside of a footer, the content will be adjusted so it is sized correctly, and the footer will account for any device safe areas. ## Basic Usage @@ -24,7 +27,6 @@ import Basic from '@site/static/usage/v9/footer/basic/index.md'; - ## Translucent Footer Footers can match the transparency found in native iOS applications by setting the `translucent` property. In order for the content to scroll behind the footer, the `fullscreen` property needs to be set on the content. This effect will only apply when the mode is `"ios"` and the device supports [backdrop-filter](https://developer.mozilla.org/en-US/docs/Web/CSS/backdrop-filter#browser_compatibility). @@ -33,7 +35,6 @@ import Translucent from '@site/static/usage/v9/footer/translucent/index.md'; - ## Fade Footer Many native iOS applications have a fade effect on the toolbar. This can be achieved by setting the `collapse` property on the footer to `"fade"`. When the content is scrolled to the end, the background and border on the footer will fade away. This effect will only apply when the mode is `"ios"`. @@ -42,7 +43,6 @@ import Fade from '@site/static/usage/v9/footer/fade/index.md'; - ### Usage with Virtual Scroll A fade footer requires a scroll container to work properly. When using a virtual scrolling solution, a custom scroll target needs to be provided. Scrolling on the content needs to be disabled and the `.ion-content-scroll-host` class needs to be added to the element responsible for scrolling. @@ -59,21 +59,26 @@ import NoBorder from '@site/static/usage/v9/footer/no-border/index.md'; - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/grid.md b/docs/api/grid.md index 3cc67dfc33..39a05cfa40 100644 --- a/docs/api/grid.md +++ b/docs/api/grid.md @@ -1,6 +1,7 @@ --- -title: "ion-grid" +title: 'ion-grid' --- + import Props from '@ionic-internal/component-api/v9/grid/props.mdx'; import Events from '@ionic-internal/component-api/v9/grid/events.mdx'; import Methods from '@ionic-internal/component-api/v9/grid/methods.mdx'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v9/grid/slots.mdx'; ion-grid: Display Grids for Mobile-First Custom App Layout - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The grid is a powerful mobile-first flexbox system for building custom layouts. It is composed of three units — a grid, [row(s)](row.md) and [column(s)](col.md). Columns will expand to fill the row, and will resize to fit additional columns. It is based on a 12 column layout with different breakpoints based on the screen size. The number of columns can be customized using CSS. ## Overview @@ -49,7 +52,6 @@ The default breakpoints for the grid and the corresponding properties are define | lg | 992px | `sizeLg` | `offsetLg` | `pushLg` | `pullLg` | Set columns when (min-width: 992px) | | xl | 1200px | `sizeXl` | `offsetXl` | `pushXl` | `pullXl` | Set columns when (min-width: 1200px) | - ## Basic Usage By default, columns will take up equal width inside of a row for all devices and screen sizes. @@ -58,7 +60,6 @@ import Basic from '@site/static/usage/v9/grid/basic/index.md'; - ## Fixed Grid Grids take up 100% width of their container. By adding the `fixed` property to the grid, the width will be set based on the screen size. The width of the grid for each breakpoint is listed in the table below, but it can be customized. For more information, refer to [Customizing the Grid](#customizing-the-grid). Open the below example in StackBlitz and resize the screen to observe how the grid width changes. @@ -75,7 +76,6 @@ import Fixed from '@site/static/usage/v9/grid/fixed/index.md'; - ## Column Size Columns can be set to specific sizes to take up a certain number out of the total number of columns, or resize their width based on the content. The default number of columns is 12, but this can be customized. Refer to the [Number of Columns](#number-of-columns) section below for more information. @@ -88,7 +88,6 @@ import SizeAuto from '@site/static/usage/v9/grid/size-auto/index.md'; - ### Specified size Set the `size` of a column and the others will automatically resize around it. If a size is specified on all of the columns and it doesn't add up to the total number of columns, there will be empty space after the columns. @@ -105,7 +104,6 @@ import SizeResponsive from '@site/static/usage/v9/grid/size-responsive/index.md' - ## Column Offset Columns can be offset to shift to the right by a certain number of columns out of the total number of columns. @@ -126,7 +124,6 @@ import OffsetResponsive from '@site/static/usage/v9/grid/offset-responsive/index - ## Column Push & Pull Columns can be pushed to to the right or pulled to the left by a certain number of columns out of the total number of columns. @@ -157,7 +154,6 @@ import VerticalAlignment from '@site/static/usage/v9/grid/vertical-alignment/ind - ### Horizontal Alignment All columns can be horizontally aligned inside of a row by adding different classes to the row. For a list of available classes, refer to [css utilities](/layout/css-utilities.md#flex-container-properties). @@ -197,19 +193,25 @@ import Padding from '@site/static/usage/v9/grid/customizing/padding/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/header.md b/docs/api/header.md index 79c77b2406..9582c73384 100644 --- a/docs/api/header.md +++ b/docs/api/header.md @@ -1,6 +1,7 @@ --- -title: "ion-header" +title: 'ion-header' --- + import Props from '@ionic-internal/component-api/v9/header/props.mdx'; import Events from '@ionic-internal/component-api/v9/header/events.mdx'; import Methods from '@ionic-internal/component-api/v9/header/methods.mdx'; @@ -10,22 +11,22 @@ import Slots from '@ionic-internal/component-api/v9/header/slots.mdx'; ion-header: Header Parent Component for Ionic Framework Apps - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Header is a root component of a page that aligns itself to the top of the page. It is recommended to be used as a wrapper for one or more [toolbars](./toolbar), but it can be used to wrap any element. When a toolbar is used inside of a header, the content will be adjusted so it is sized correctly, and the header will account for any device safe areas. - ## Basic Usage import Basic from '@site/static/usage/v9/header/basic/index.md'; - ## Translucent Header Headers can match the transparency found in native iOS applications by setting the `translucent` property. In order for the content to scroll behind the header, the `fullscreen` property needs to be set on the content. This effect will only apply when the mode is `"ios"` and the device supports [backdrop-filter](https://developer.mozilla.org/en-US/docs/Web/CSS/backdrop-filter#browser_compatibility). @@ -34,7 +35,6 @@ import Translucent from '@site/static/usage/v9/header/translucent/index.md'; - ## Condensed Header Ionic provides the functionality found in native iOS applications to show a large toolbar title and then collapse it to a small title when scrolling. This can be done by adding two headers, one above the content and one inside of the content, and then setting the `collapse` property to `"condense"` on the header inside of the content. This effect will only apply when the mode is "ios". @@ -43,7 +43,6 @@ import Condense from '@site/static/usage/v9/header/condense/index.md'; - ## Fade Header Many native iOS applications have a fade effect on the toolbar. This can be achieved by setting the `collapse` property on the header to `"fade"`. When the page is first loaded, the background and border on the header will be hidden. As the content is scrolled, the header will fade back in. This effect will only apply when the mode is "ios". @@ -54,7 +53,6 @@ import Fade from '@site/static/usage/v9/header/fade/index.md'; - ### Usage with Virtual Scroll A fade header requires a scroll container to work properly. When using a virtual scrolling solution, a custom scroll target needs to be provided. Scrolling on the content needs to be disabled and the `.ion-content-scroll-host` class needs to be added to the element responsible for scrolling. @@ -63,7 +61,6 @@ import CustomScrollTarget from '@site/static/usage/v9/header/custom-scroll-targe - ## Borders In `"md"` mode, the header will have a `box-shadow` on the bottom. In `"ios"` mode, it will receive a `border` on the bottom. These can be removed by adding the `.ion-no-border` class to the header. @@ -72,21 +69,26 @@ import NoBorder from '@site/static/usage/v9/header/no-border/index.md'; - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/img.md b/docs/api/img.md index c79ac4cfeb..992d0af2ca 100644 --- a/docs/api/img.md +++ b/docs/api/img.md @@ -1,5 +1,5 @@ --- -title: "ion-img" +title: 'ion-img' --- import Props from '@ionic-internal/component-api/v9/img/props.mdx'; @@ -11,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v9/img/slots.mdx'; ion-img: Img Tag to Lazy Load Images in Viewport - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -31,19 +34,25 @@ import Basic from '@site/static/usage/v9/img/basic/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/infinite-scroll-content.md b/docs/api/infinite-scroll-content.md index 333e3bc486..de3741b9c2 100644 --- a/docs/api/infinite-scroll-content.md +++ b/docs/api/infinite-scroll-content.md @@ -1,5 +1,5 @@ --- -title: "ion-infinite-scroll-content" +title: 'ion-infinite-scroll-content' --- import Props from '@ionic-internal/component-api/v9/infinite-scroll-content/props.mdx'; @@ -16,19 +16,25 @@ The `ion-infinite-scroll-content` component is the default child used by the `io For more information as well as usage, refer to the [Infinite Scroll Documentation](./infinite-scroll.md#infinite-scroll-content). ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots - \ No newline at end of file + + diff --git a/docs/api/infinite-scroll.md b/docs/api/infinite-scroll.md index dfdcc6de64..a2c0247508 100644 --- a/docs/api/infinite-scroll.md +++ b/docs/api/infinite-scroll.md @@ -1,5 +1,5 @@ --- -title: "ion-infinite-scroll" +title: 'ion-infinite-scroll' --- import Props from '@ionic-internal/component-api/v9/infinite-scroll/props.mdx'; @@ -11,12 +11,14 @@ import Slots from '@ionic-internal/component-api/v9/infinite-scroll/slots.mdx'; ion-infinite-scroll: Infinite Scroller Action Component - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The Infinite Scroll component calls an action to be performed when the user scrolls a specified distance from the bottom or top of the page. The expression assigned to the `ionInfinite` event is called when the user reaches that defined distance. When this expression has finished any and all tasks, it should call the `complete()` method on the infinite scroll instance. @@ -75,12 +77,8 @@ For example, when rendering a collection of items in an `ion-list`: ```html - - First item - - - Second item - + First item + Second item ... @@ -105,19 +103,25 @@ interface InfiniteScrollCustomEvent extends CustomEvent { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/input-otp.md b/docs/api/input-otp.md index 932b9b7c96..e91a6bdef1 100644 --- a/docs/api/input-otp.md +++ b/docs/api/input-otp.md @@ -1,6 +1,7 @@ --- -title: "ion-input-otp" +title: 'ion-input-otp' --- + import Props from '@ionic-internal/component-api/v9/input-otp/props.mdx'; import Events from '@ionic-internal/component-api/v9/input-otp/events.mdx'; import Methods from '@ionic-internal/component-api/v9/input-otp/methods.mdx'; @@ -10,7 +11,10 @@ import Slots from '@ionic-internal/component-api/v9/input-otp/slots.mdx'; ion-input-otp: One-Time Password Input Component - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -32,6 +36,7 @@ import Basic from '@site/static/usage/v9/input-otp/basic/index.md'; The `type` property determines the input format, supporting either numeric or alphanumeric verification codes. It accepts two values: `number` and `text`. It uses `type="number"` by default for entering numeric verification codes. When `type="text"` is specified, it accepts alphanumeric input. This flexibility allows handling different OTP formats, whether numeric-only codes (like SMS verification codes) or alphanumeric codes (like backup codes or recovery keys). The `type` property automatically sets both the `inputmode` and `pattern` attributes: + - When `type="number"`: - Sets `inputmode="numeric"` to show a numeric keyboard on mobile devices - Sets `pattern="[\p{N}]"` to allow only numeric input @@ -72,6 +77,7 @@ import Size from '@site/static/usage/v9/input-otp/size/index.md'; ## Separators The `separators` property adds visual dividers between one or more of the input boxes. Separators can be defined in three ways: + - Comma-separated string of numbers (e.g., `"1,3"`) - Array of numbers (e.g., `[1, 3]`) - String `"all"` to show separators between every input box @@ -85,6 +91,7 @@ import Separators from '@site/static/usage/v9/input-otp/separators/index.md'; ## States The component supports various states for automatic styling of input boxes: + - `disabled` and `readonly` states via respective properties - Form validation states: `valid` and `invalid` visually indicated through CSS classes - In Angular: validation states are automatically managed through the framework's value accessors and form validation @@ -99,6 +106,7 @@ import States from '@site/static/usage/v9/input-otp/states/index.md'; ## Pattern The `pattern` property enables custom validation using regular expressions. It accepts a [string regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_expressions/Cheatsheet) or [unicode regular expression](https://www.regular-expressions.info/unicode.html) to validate allowed characters. The `pattern` must match the entire value, not just a subset. Default patterns: + - `type="number"`: `"[\p{N}]"` for matching any kind of numeric character in any script. - `type="text"`: `"[\p{L}\p{N}]"` for any kind of numeric character in any script and any kind of letter from any language. @@ -106,9 +114,10 @@ The component will prevent users from entering any characters that don't match t :::tip When using a custom `pattern`, remember that the `type` property controls which keyboard appears on mobile devices: + - Use `type="number"` for numeric-only patterns to show the numeric keyboard - Use `type="text"` for patterns that include letters to show the alphanumeric keyboard -::: + ::: import Pattern from '@site/static/usage/v9/input-otp/pattern/index.md'; @@ -121,7 +130,7 @@ import Pattern from '@site/static/usage/v9/input-otp/pattern/index.md'; The `color` property changes the color palette for input boxes. For `outline` fills, this property changes the caret color, highlight color and border color. For `solid` fills, this property changes the caret color and highlight color. :::note -The `color` property does *not* change the text color of the input OTP. For that, use the [`--color` CSS property](#css-custom-properties-1). +The `color` property does _not_ change the text color of the input OTP. For that, use the [`--color` CSS property](#css-custom-properties-1). ::: import Colors from '@site/static/usage/v9/input-otp/theming/colors/index.md'; @@ -144,30 +153,36 @@ The keyboard navigation for Input OTP follows the [ARIA Authoring Practices Guid These keyboard interactions apply to all `ion-input-otp` elements when the component is not disabled. -| Key | Description | -| --- | --- | -| Tab | When first tabbing into the component, focus moves to the first empty box. If all boxes are filled, focus moves to the last box. Once inside the component, tabbing moves to the next focusable element on the page. | -| Shift + Tab | When tabbing backwards into the component, focus moves to the first empty box. If all boxes are filled, focus moves to the last box. Once inside the component, shift tabbing focus moves to the previous focusable element on the page. | -| ArrowRight | Moves focus to the next input box, stopping at the first empty box. In RTL mode, moves focus back to any previous box that contains a value. | -| ArrowLeft | Moves focus back to any previous box that contains a value. In RTL mode, moves focus to the next input box, stopping at the first empty box. | -| Any character matching the `pattern` property | Fills the current box and automatically moves focus to the next empty box. If all boxes are filled, focus remains on the last box. If the current box has a value, override the value with the entered character. In RTL mode, input fills boxes from right to left. | -| Backspace | In an empty box: moves focus back one box and clears its value.
In a box with a value: clears that value.
With values in boxes to the right: shifts them all one position to the left. In RTL mode, with values in boxes to the left: shifts them all one position to the right. | +| Key | Description | +| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Tab | When first tabbing into the component, focus moves to the first empty box. If all boxes are filled, focus moves to the last box. Once inside the component, tabbing moves to the next focusable element on the page. | +| Shift + Tab | When tabbing backwards into the component, focus moves to the first empty box. If all boxes are filled, focus moves to the last box. Once inside the component, shift tabbing focus moves to the previous focusable element on the page. | +| ArrowRight | Moves focus to the next input box, stopping at the first empty box. In RTL mode, moves focus back to any previous box that contains a value. | +| ArrowLeft | Moves focus back to any previous box that contains a value. In RTL mode, moves focus to the next input box, stopping at the first empty box. | +| Any character matching the `pattern` property | Fills the current box and automatically moves focus to the next empty box. If all boxes are filled, focus remains on the last box. If the current box has a value, override the value with the entered character. In RTL mode, input fills boxes from right to left. | +| Backspace | In an empty box: moves focus back one box and clears its value.
In a box with a value: clears that value.
With values in boxes to the right: shifts them all one position to the left. In RTL mode, with values in boxes to the left: shifts them all one position to the right. | | Ctrl + V
Cmd + V | Pastes content starting from the first box, regardless of which box is currently focused. All existing values are cleared before pasting. For example, if you have "1234" in all boxes and paste "56", the result will be "56" in the first two boxes with the remaining boxes empty. If the pasted content is longer than the available boxes, the extra characters are ignored. | ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/input-password-toggle.md b/docs/api/input-password-toggle.md index 1894df02c0..4b5d721426 100644 --- a/docs/api/input-password-toggle.md +++ b/docs/api/input-password-toggle.md @@ -1,6 +1,7 @@ --- -title: "ion-input-password-toggle" +title: 'ion-input-password-toggle' --- + import Props from '@ionic-internal/component-api/v9/input-password-toggle/props.mdx'; import Events from '@ionic-internal/component-api/v9/input-password-toggle/events.mdx'; import Methods from '@ionic-internal/component-api/v9/input-password-toggle/methods.mdx'; @@ -10,14 +11,16 @@ import Slots from '@ionic-internal/component-api/v9/input-password-toggle/slots. ion-input-password-toggle: Toggle the visibility of a password in Input - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The InputPasswordToggle component is a companion component to [Input](./input). It allows users to toggle the visibility of text in a password input. ## Basic Usage @@ -28,25 +31,30 @@ InputPasswordToggle must be used with an [Input](./input) that has its [`type`]( Using any other `type` will cause a warning to be logged. ::: - import Basic from '@site/static/usage/v9/input-password-toggle/basic/index.md'; ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/input.md b/docs/api/input.md index ac87e1a431..2cb83e1b6d 100644 --- a/docs/api/input.md +++ b/docs/api/input.md @@ -1,6 +1,7 @@ --- -title: "ion-input" +title: 'ion-input' --- + import Props from '@ionic-internal/component-api/v9/input/props.mdx'; import Events from '@ionic-internal/component-api/v9/input/events.mdx'; import Methods from '@ionic-internal/component-api/v9/input/methods.mdx'; @@ -10,24 +11,24 @@ import Slots from '@ionic-internal/component-api/v9/input/slots.mdx'; ion-input: Custom Input With Styling and CSS Properties - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The input component is a wrapper to the HTML input element with custom styling and additional functionality. It accepts most of the same properties as the HTML input and integrates with the keyboard on mobile devices. - ## Basic Usage import Basic from '@site/static/usage/v9/input/basic/index.md'; - ## Types The input component is meant for text type inputs only, such as `"text"`, `"password"`, `"email"`, `"number"`, `"search"`, `"tel"`, and `"url"`. It supports all standard text input events including `keyup`, `keydown`, `keypress`, and more. The default `type` is `"text"`. @@ -78,7 +79,6 @@ import Clear from '@site/static/usage/v9/input/clear/index.md'; - ## Filled Inputs Material Design offers filled styles for an input. The `fill` property on the input can be set to either `"solid"` or `"outline"`. @@ -93,7 +93,6 @@ import Fill from '@site/static/usage/v9/input/fill/index.md'; - ## Helper & Error Text Helper and error text can be used inside of an input with the `helperText` and `errorText` property. The error text will not be displayed unless the `ion-invalid` and `ion-touched` classes are added to the `ion-input`. This ensures errors are not shown before the user has a chance to enter data. @@ -173,7 +172,7 @@ import StartEndSlots from '@site/static/usage/v9/input/start-end-slots/index.md' Setting the `color` property changes the color palette for each input. On `ios` mode, this property changes the caret color. On `md` mode, this property changes the caret color and the highlight/underline color. :::note -The `color` property does *not* change the text color of the input. For that, use the [`--color` CSS property](#css-custom-properties-1). +The `color` property does _not_ change the text color of the input. For that, use the [`--color` CSS property](#css-custom-properties-1). ::: import Colors from '@site/static/usage/v9/input/theming/colors/index.md'; @@ -209,21 +208,26 @@ interface InputCustomEvent extends CustomEvent { } ``` - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/item-divider.md b/docs/api/item-divider.md index 0f48a74fe0..21f7eff903 100644 --- a/docs/api/item-divider.md +++ b/docs/api/item-divider.md @@ -1,6 +1,7 @@ --- -title: "ion-item-divider" +title: 'ion-item-divider' --- + import Props from '@ionic-internal/component-api/v9/item-divider/props.mdx'; import Events from '@ionic-internal/component-api/v9/item-divider/events.mdx'; import Methods from '@ionic-internal/component-api/v9/item-divider/methods.mdx'; @@ -10,24 +11,24 @@ import Slots from '@ionic-internal/component-api/v9/item-divider/slots.mdx'; ion-item-divider: Item Divider Block Element for Ionic Apps - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Item dividers are block elements that can be used to separate [items](./item) in a list. They are similar to list headers, but instead of only being placed at the top of a list, they should go in between groups of items. - ## Basic Usage import Basic from '@site/static/usage/v9/item-divider/basic/index.md'; - ## Theming ### Colors @@ -36,28 +37,32 @@ import Colors from '@site/static/usage/v9/item-divider/theming/colors/index.md'; - ### CSS Custom Properties import CSSProps from '@site/static/usage/v9/item-divider/theming/css-properties/index.md'; - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/item-group.md b/docs/api/item-group.md index 70f1f642c6..7f429a68ac 100644 --- a/docs/api/item-group.md +++ b/docs/api/item-group.md @@ -1,6 +1,7 @@ --- -title: "ion-item-group" +title: 'ion-item-group' --- + import Props from '@ionic-internal/component-api/v9/item-group/props.mdx'; import Events from '@ionic-internal/component-api/v9/item-group/events.mdx'; import Methods from '@ionic-internal/component-api/v9/item-group/methods.mdx'; @@ -10,12 +11,14 @@ import Slots from '@ionic-internal/component-api/v9/item-group/slots.mdx'; ion-item-group: Group Items to Divide into Multiple Sections - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - Item groups are containers that organize similar [items](./item) together. They can contain [item dividers](./item-divider) to divide the items into multiple sections. They can also be used to group [sliding items](./item-sliding). ## Basic Usage @@ -30,21 +33,26 @@ import SlidingItems from '@site/static/usage/v9/item-group/sliding-items/index.m - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/item-option.md b/docs/api/item-option.md index 4a62ba173f..2e9d77b226 100644 --- a/docs/api/item-option.md +++ b/docs/api/item-option.md @@ -1,6 +1,7 @@ --- -title: "ion-item-option" +title: 'ion-item-option' --- + import Props from '@ionic-internal/component-api/v9/item-option/props.mdx'; import Events from '@ionic-internal/component-api/v9/item-option/events.mdx'; import Methods from '@ionic-internal/component-api/v9/item-option/methods.mdx'; @@ -10,33 +11,40 @@ import Slots from '@ionic-internal/component-api/v9/item-option/slots.mdx'; ion-item-option: Option Button for Sliding Item in Ionic - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The item option component is an button for a sliding item. It must be placed inside of [item options](./item-options). The `ionSwipe` event and the `expandable` property can be combined to create a full swipe action for the item. Refer to the [item sliding](./item-sliding) documentation for more information. - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/item-options.md b/docs/api/item-options.md index 4c8d41920c..1efa8330aa 100644 --- a/docs/api/item-options.md +++ b/docs/api/item-options.md @@ -1,6 +1,7 @@ --- -title: "ion-item-options" +title: 'ion-item-options' --- + import Props from '@ionic-internal/component-api/v9/item-options/props.mdx'; import Events from '@ionic-internal/component-api/v9/item-options/events.mdx'; import Methods from '@ionic-internal/component-api/v9/item-options/methods.mdx'; @@ -10,41 +11,45 @@ import Slots from '@ionic-internal/component-api/v9/item-options/slots.mdx'; ion-item-options: Option Button Components for Ionic Apps - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - The item options component is a container for the [item option](./item-option) buttons in a sliding item. These buttons can be placed either on the [start or end side](#side-description). Refer to the [item sliding](./item-sliding) documentation for more information. - ## Side Description | Side | Position | Swipe Direction | -|---------|-----------------------------------------------------------------|-------------------------------------------------------------------| +| ------- | --------------------------------------------------------------- | ----------------------------------------------------------------- | | `start` | To the `left` of the content in LTR, and to the `right` in RTL. | From `left` to `right` in LTR, and from `right` to `left` in RTL. | | `end` | To the `right` of the content in LTR, and to the `left` in RTL. | From `right` to `left` in LTR, and from `left` to `right` in RTL. | - - - ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/item-sliding.md b/docs/api/item-sliding.md index c28d9858cc..54b9ae5cca 100644 --- a/docs/api/item-sliding.md +++ b/docs/api/item-sliding.md @@ -1,6 +1,7 @@ --- -title: "ion-item-sliding" +title: 'ion-item-sliding' --- + import Props from '@ionic-internal/component-api/v9/item-sliding/props.mdx'; import Events from '@ionic-internal/component-api/v9/item-sliding/events.mdx'; import Methods from '@ionic-internal/component-api/v9/item-sliding/methods.mdx'; @@ -10,15 +11,16 @@ import Slots from '@ionic-internal/component-api/v9/item-sliding/slots.mdx'; ion-item-sliding: Slide Buttons | Slide Right to Left - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; - A sliding item contains an item that can be dragged to reveal option buttons. It requires an [item](./item) component as a child. All options to reveal should be placed in the [item options](./item-options) element. - ## Basic Usage Sliding item options are placed on the `"end"` side of the item by default. This means that options are revealed when the item is swiped from end to start, i.e. from right to left in LTR, but from left to right in RTL. To place them on the opposite side, so that they are revealed when swiping in the opposite direction, set the side attribute to `"start"` on the [item options](./item-options) element. Up to two item options can be used at the same time in order to reveal two different sets of options depending on the swiping direction. @@ -27,7 +29,6 @@ import Basic from '@site/static/usage/v9/item-sliding/basic/index.md'; - ## Icon Options When an icon is placed alongside text in the [item option](./item-option), it will display the icon on top of the text by default. The slot on the icon can be changed to any of the available [item option slots](./item-option#slots) to change its position. @@ -36,7 +37,6 @@ import Icons from '@site/static/usage/v9/item-sliding/icons/index.md'; - ## Expandable Options Options can be expanded to take up the full width of the parent `ion-item` if you swipe past a certain point. This can be combined with the `ionSwipe` event on the [item options](./item-options) to call a method when the item is fully swiped. @@ -45,7 +45,6 @@ import Expandable from '@site/static/usage/v9/item-sliding/expandable/index.md'; - ## Interfaces ### ItemSlidingCustomEvent @@ -59,19 +58,25 @@ interface ItemSlidingCustomEvent extends CustomEvent { ``` ## Properties + ## Events + ## Methods + ## CSS Shadow Parts + ## CSS Custom Properties + ## Slots + diff --git a/docs/api/item.md b/docs/api/item.md index baee6ca83c..7a49638acc 100644 --- a/docs/api/item.md +++ b/docs/api/item.md @@ -1,6 +1,7 @@ --- -title: "ion-item" +title: 'ion-item' --- + import Props from '@ionic-internal/component-api/v9/item/props.mdx'; import Events from '@ionic-internal/component-api/v9/item/events.mdx'; import Methods from '@ionic-internal/component-api/v9/item/methods.mdx'; @@ -15,7 +16,10 @@ import TabItem from '@theme/TabItem'; ion-item: Input, Edit, or Delete iOS and Android Item Elements - + import EncapsulationPill from '@components/page/api/EncapsulationPill'; @@ -24,7 +28,6 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill'; Items are elements that can contain text, icons, avatars, images, inputs, and any other native or custom elements. Items should only be used as rows in a [List](./list) with other items. Items can be swiped, deleted, reordered, edited, and more. - ## Basic Usage Items left align text and wrap when the text is wider than the item. We can modify this behavior using the CSS Utilities provided by Ionic Framework, such as using `.ion-text-nowrap` in the below example. Refer to the [CSS Utilities Documentation](/docs/layout/css-utilities) for more classes that can be added to an item to transform the text. @@ -33,7 +36,6 @@ import Basic from '@site/static/usage/v9/item/basic/index.md'; - ## Content Types While items in a list take many forms, they typically support 5 different content types: supporting visuals, text, metadata, actions, and controls. However, not all of these content types should be used together at the same time. The following guide shows the different content types as well as how to properly utilize them in an application. @@ -48,8 +50,18 @@ If a visual is required to interact with the item, such as an icon button, then text="Supporting visuals should be rendered in a consistent manner. This makes the information in each item easier to parse." doText="Align visuals on the same side in a list" doNotText="Don't render visuals with different alignments in the same list" - doImage={A list with several items. Each item has an icon and visible text describing the item. The icon in each item is rendered at the start of the line.} - doNotImage={A list with several items. Each item has an icon and visible text describing the item. Some icons are rendered at the start of the line, and some icons are rendered at the end of the line} + doImage={ + A list with several items. Each item has an icon and visible text describing the item. The icon in each item is rendered at the start of the line. + } + doNotImage={ + A list with several items. Each item has an icon and visible text describing the item. Some icons are rendered at the start of the line, and some icons are rendered at the end of the line + } /> In the example below, we are creating two lists with supporting visuals. The first list uses icons, and the second list uses avatars. The visuals are decorative, so they all have `aria-hidden="true"`. Additionally, they are presented consistently in the `start` slot. @@ -63,11 +75,27 @@ import SupportingVisuals from '@site/static/usage/v9/item/content-types/supporti The text content type includes form control labels or other visible text. This text serves to indicate the intent of the item. Try to keep the text short and to the point. If you find that you need a few more sentences to clarify the item's purpose, consider moving the additional sentences to a Note at the bottom of the list. Adding the item to its own list makes it clear which item the text is associated with.} + text={ + <> + If you find that you need a few more sentences to clarify the item's purpose, consider moving the additional + sentences to a Note at the bottom of the list. Adding the item to its own + list makes it clear which item the text is associated with. + + } doText="Move long text outside of the list" doNotText="Don't try to fit long text in an item" - doImage={A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed underneath the list.} - doNotImage={A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed as a single paragraph inline with the checkbox, making the text hard to read and increasing the height of the item.} + doImage={ + A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed underneath the list. + } + doNotImage={ + A list with an item that contains a checked checkbox indicating the user wants to receive emails. Text describing how often the user will receive emails as well as how to unsubscribe from emails is placed as a single paragraph inline with the checkbox, making the text hard to read and increasing the height of the item. + } /> In the example below, we are creating a list with different types of text. The "First Name" and "Last Name" labels serve to indicate what to type into the text inputs. @@ -88,16 +116,36 @@ Metadata provides additional context for an item such as status text or counts. text="Limit the amount of metadata you include to only the most relevant information." doText="Add only the most important metadata" doNotText="Don't add too much metadata as it can overwhelm or confuse the user." - doImage={A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item.} - doNotImage={A list that contains several items, each representing a different to-do list. Two counts are placed at the end of each item: One count that states the total number of tasks, and another count that states the total number of tasks that are due today.} + doImage={ + A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item. + } + doNotImage={ + A list that contains several items, each representing a different to-do list. Two counts are placed at the end of each item: One count that states the total number of tasks, and another count that states the total number of tasks that are due today. + } /> } - cautionImage={A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item. However, the count is highlighted in blue which draws the user's attention away from the name of the to-do list.} + doImage={ + A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item. + } + cautionImage={ + A list that contains several items, each representing a different to-do list. A count of how many tasks in each to-do list is placed at the end of each item. However, the count is highlighted in blue which draws the user's attention away from the name of the to-do list. + } /> In the example below, we are creating two lists with different kinds of metadata. The first list uses [Note](./note) to show how many tasks are in each to-do list. @@ -115,11 +163,32 @@ Actions are interactive elements that do something when you activate them. An it Developers should avoid creating nested interactives which can break the user experience with screen readers. For example, developers should avoid adding a button inside the main content of the Item if the `button` property is set to `true`. Actions can be added by using the Item Sliding component. Actions can also be placed directly inside of the Item without the use of Item Sliding, but this should be limited to no more than 2 actions.} - doText={<>Use an Item Sliding to reveal multiple actions by swiping on the Item.} + text={ + <> + Actions can be added by using the Item Sliding component. Actions can + also be placed directly inside of the Item without the use of Item Sliding, but this should be limited to no more + than 2 actions. + + } + doText={ + <> + Use an Item Sliding to reveal multiple actions by swiping on the + Item. + + } doNotText="Don't put more than 2 actions within an Item." - doImage={A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. These actions are revealed by swiping on the item.} - doNotImage={A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. The actions are placed directly on the item. Since there are so many actions, some of the text is cut off.} + doImage={ + A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. These actions are revealed by swiping on the item. + } + doNotImage={ + A list that contains several items, each representing a contact. Each item has text that states the contact's name as well as several actions including pinning the contact, sharing the contact, and deleting the contact. The actions are placed directly on the item. Since there are so many actions, some of the text is cut off. + } /> In the example below, we are creating a list of contacts. Each item is a stubbed button intended to bring you to the full contact page for that item. There are additional actions associated with each item that users can reveal by swiping on the item. @@ -133,27 +202,74 @@ import Actions from '@site/static/usage/v9/item/content-types/actions/index.md'; Controls are form components such as checkboxes, inputs, radios, and more. Each item in a list should have at most two controls due to screen space constraints. Metadata such as helper text or character counts should not be used on form controls in list views. If such metadata is needed, the form control should be placed outside of a list. Filled Inputs are a great way of visually defining the input container outside of a list.} + text={ + <> + Metadata such as helper text or character counts should not be used on form controls in list views. If such + metadata is needed, the form control should be placed outside of a list.{' '} + Filled Inputs are a great way of visually defining the input + container outside of a list. + + } doText="Place inputs with metadata outside of the list." doNotText="Don't put metadata for inputs in the list." - doImage={There is an email input and a password input. Both have helper text associated with them. Since both are placed outside of a list it is clear which input each helper text is associated with.} - doNotImage={There is a list containing an email input and a password input. Both have helper texts associated with them. However, the divider between each item and between the helper text makes it hard to tell which input each helper text is associated with.} + doImage={ + There is an email input and a password input. Both have helper text associated with them. Since both are placed outside of a list it is clear which input each helper text is associated with. + } + doNotImage={ + There is a list containing an email input and a password input. Both have helper texts associated with them. However, the divider between each item and between the helper text makes it hard to tell which input each helper text is associated with. + } /> Alternatively, the metadata can be placed in a Note at the bottom of the list.} + text={ + <> + Alternatively, the metadata can be placed in a Note at the bottom of the + list. + + } doText="Place metadata for inputs at the end of a list." doNotText="Don't put metadata for inputs in the list." - doImage={There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above.} - doNotImage={There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with.} + doImage={ + There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above. + } + doNotImage={ + There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with. + } /> Items should typically have no more than two controls. If you need more controls, consider adding the additional controls in a Modal that is accessible from the item.} + text={ + <> + Items should typically have no more than two controls. If you need more controls, consider adding the additional + controls in a Modal that is accessible from the item. + + } doText="Move additional controls to a submenu accessible from the item." doNotText="Don't use more than two controls within an item." - doImage={There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with.} - doNotImage={There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above.} + doImage={ + There is one list of inputs. One of the inputs is a password input with text below the input that says 'Password must be at least 16 characters'. However, this text is placed directly above another input, so it's not immediately clear which input the text is associated with. + } + doNotImage={ + There are two lists of inputs. The first list contains a password input. Below that list contains text that says 'Password must be at least 16 characters'. The second list contains an email input. This second list is separated so the password length requirement text is clearly associated with the password input above. + } /> In the example below, we are creating a list of to-do tasks. Each item has a checkbox and an input. The checkbox lets the user mark a task as complete, and the input lets the user change the name of the task. @@ -162,7 +278,6 @@ import Controls from '@site/static/usage/v9/item/content-types/controls/index.md - ## Clickable Items An item is considered "clickable" if it has an `href`, `button`, or `routerLink` property set. Clickable items have a few visual differences that indicate they can be interacted with. For example, a clickable item receives the ripple effect upon activation in `md` mode, has a highlight when activated in `ios` mode, and has a [detail arrow](#detail-arrows) by default in `ios` mode. @@ -171,7 +286,6 @@ import Clickable from '@site/static/usage/v9/item/clickable/index.md'; - ## Routing Items support client-side navigation using the `routerLink` property. Setting `routerLink` renders the item as an anchor and navigates to the specified route when tapped. The `routerDirection` property controls the transition animation direction, and `routerAnimation` accepts a custom animation builder. @@ -274,7 +388,6 @@ In Vue, use the `router-link` attribute on `ion-item`. The `router-direction` an - ## Detail Arrows By default [clickable items](#clickable-items) will display a right arrow icon on `ios` mode. To hide the right arrow icon on clickable elements, set the `detail` property to `false`. To show the right arrow icon on an item that doesn't display it naturally, set the `detail` property to `true`. @@ -339,6 +452,7 @@ The following guidelines will help ensure your list items are easy to understand ### Keyboard Interactions An `` has the following keyboard interactions when any of these conditions are met: + - The `button` property is set to `"true"`, rendering a native `