diff --git a/docs/api/reorder-group.md b/docs/api/reorder-group.md
index c3c6c4e9508..2d1d7f73fd3 100644
--- a/docs/api/reorder-group.md
+++ b/docs/api/reorder-group.md
@@ -16,27 +16,71 @@ import Slots from '@ionic-internal/component-api/v8/reorder-group/slots.md';
import EncapsulationPill from '@components/page/api/EncapsulationPill';
-The reorder group is a container for items using the [reorder](./reorder) component. When the user drags an item and drops it in a new position, the `ionItemReorder` event is dispatched. A handler for this event should be implemented that calls the `complete` method.
+The reorder group is a container for items using the [reorder](./reorder) component. When the user drags an item and drops it, the `ionReorderEnd` event is dispatched. A handler for this event should be implemented that calls the `complete` method.
-The `detail` property of the `ionItemReorder` event includes all of the relevant information about the reorder operation, including the `from` and `to` indexes. In the context of reordering, an item moves `from` an index `to` a new index. For example usage of the reorder group, see the [reorder](./reorder) documentation.
+The `detail` property of the `ionReorderEnd` event includes all of the relevant information about the reorder operation, including the `from` and `to` indexes. In the context of reordering, an item moves `from` an index `to` an index. For example usage of the reorder group, see the [reorder](./reorder) documentation.
## Interfaces
-### ItemReorderEventDetail
+### ReorderMoveEventDetail
```typescript
-interface ItemReorderEventDetail {
+interface ReorderMoveEventDetail {
+ from: number;
+ to: number;
+}
+```
+
+### ReorderEndEventDetail
+
+```typescript
+interface ReorderEndEventDetail {
from: number;
to: number;
complete: (data?: boolean | any[]) => any;
}
```
-### ItemReorderCustomEvent
+### ReorderMoveCustomEvent
+
+While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.
+
+```typescript
+interface ReorderMoveCustomEvent extends CustomEvent {
+ detail: ReorderMoveEventDetail;
+ target: HTMLIonReorderGroupElement;
+}
+
+```
+
+### ReorderEndCustomEvent
While not required, this interface can be used in place of the `CustomEvent` interface for stronger typing with Ionic events emitted from this component.
+```typescript
+interface ReorderEndCustomEvent extends CustomEvent {
+ detail: ReorderEndEventDetail;
+ target: HTMLIonReorderGroupElement;
+}
+```
+
+### ItemReorderEventDetail (deprecated)
+
+**_Deprecated_** — Use the `ionReorderEnd` event with `ReorderEndEventDetail` instead.
+
+```typescript
+interface ItemReorderEventDetail {
+ from: number;
+ to: number;
+ complete: (data?: boolean | any[]) => any;
+}
+```
+
+### ItemReorderCustomEvent (deprecated)
+
+**_Deprecated_** — Use the `ionReorderEnd` event with `ReorderEndCustomEvent` instead.
+
```typescript
interface ItemReorderCustomEvent extends CustomEvent {
detail: ItemReorderEventDetail;
diff --git a/docs/api/reorder.md b/docs/api/reorder.md
index ad07a4290ea..5f771c9badf 100644
--- a/docs/api/reorder.md
+++ b/docs/api/reorder.md
@@ -20,7 +20,7 @@ import EncapsulationPill from '@components/page/api/EncapsulationPill';
Reorder is a component that allows an item to be dragged to change its order within a group of items. It must be used within a [reorder group](./reorder-group) to provide a visual drag and drop interface.
-The reorder is the anchor used to drag and drop the items. Once the reorder is complete, the `ionItemReorder` event will be dispatched from the reorder group and the `complete` method needs to be called.
+The reorder is the anchor used to drag and drop the items. Once the reorder is complete, the `ionReorderEnd` event will be dispatched from the reorder group and the `complete` method needs to be called.
## Basic Usage
@@ -73,6 +73,29 @@ import UpdatingData from '@site/static/usage/v8/reorder/updating-data/index.md';
+## Event Handling
+
+### Using `ionReorderStart` and `ionReorderEnd`
+
+The `ionReorderStart` event is emitted when the user begins a reorder gesture. This event fires when the user taps and holds an item, before any movement occurs. This is useful for preparing the UI for the reorder operation, such as hiding certain elements or updating the visual state of items. For example, icons in list items can be hidden while they are being dragged and shown again when the reorder is complete.
+
+The `ionReorderEnd` event is emitted when the user completes the reorder gesture. This occurs when the user releases the item they are dragging, for example by lifting their finger on a touch screen or releasing the mouse button. The event includes the `from` and `to` indices of the item, as well as the `complete` method that should be called to finalize the reorder operation. The `from` index will always be the position of the item when the gesture started, while the `to` index will be its final position. This event will fire even if no items have changed position, in which case the `from` and `to` indices will be the same.
+
+import ReorderStartEndEvents from '@site/static/usage/v8/reorder/reorder-start-end-events/index.md';
+
+
+
+### Using `ionReorderMove`
+
+The `ionReorderMove` event is emitted continuously during the reorder gesture as the user drags an item. The event includes the `from` and `to` indices of the item. Unlike `ionReorderEnd`, the `from` index in this event represents the last known position of the item (which updates as the item moves), while the `to` index represents its current position. If the item has not changed position since the last event, the `from` and `to` indices will be the same. This event is useful for tracking position changes during the drag operation. For example, the ranking or numbering of items can be updated in real-time as they are being dragged to maintain a logical ascending order.
+
+:::warning
+Do not call the `complete` method during the `ionReorderMove` event as it can break the gesture.
+:::
+
+import ReorderMoveEvent from '@site/static/usage/v8/reorder/reorder-move-event/index.md';
+
+
## Usage with Virtual Scroll
diff --git a/plugins/docusaurus-plugin-ionic-component-api/index.js b/plugins/docusaurus-plugin-ionic-component-api/index.js
index d3b3d2d7255..90e59ee09f3 100644
--- a/plugins/docusaurus-plugin-ionic-component-api/index.js
+++ b/plugins/docusaurus-plugin-ionic-component-api/index.js
@@ -145,7 +145,7 @@ ${properties
.map((prop) => {
const isDeprecated = prop.deprecation !== undefined;
- const docs = isDeprecated ? `${prop.docs}\n_Deprecated_ ${prop.deprecation}` : prop.docs;
+ const docs = isDeprecated ? `${prop.docs}\n\n**_Deprecated_** — ${prop.deprecation}` : prop.docs;
return `
### ${prop.name} ${isDeprecated ? '(deprecated)' : ''}
@@ -170,7 +170,15 @@ function renderEvents({ events }) {
return `
| Name | Description | Bubbles |
| --- | --- | --- |
-${events.map((event) => `| \`${event.event}\` | ${formatMultiline(event.docs)} | \`${event.bubbles}\` |`).join('\n')}`;
+${events
+ .map((event) => {
+ const isDeprecated = event.deprecation !== undefined;
+ const docs = isDeprecated ? `${event.docs}\n\n**_Deprecated_** — ${event.deprecation}` : event.docs;
+ return `| \`${event.event}\` ${isDeprecated ? '**(deprecated)**' : ''} | ${formatMultiline(docs)} | \`${
+ event.bubbles
+ }\` |`;
+ })
+ .join('\n')}`;
}
/**
diff --git a/static/demos/api/reorder/index.html b/static/demos/api/reorder/index.html
index 695a50c2701..3903da1eb7d 100644
--- a/static/demos/api/reorder/index.html
+++ b/static/demos/api/reorder/index.html
@@ -99,7 +99,7 @@
function toggleReorder() {
const reorderGroup = document.getElementById('reorder');
reorderGroup.disabled = !reorderGroup.disabled;
- reorderGroup.addEventListener('ionItemReorder', ({ detail }) => {
+ reorderGroup.addEventListener('ionReorderEnd', ({ detail }) => {
detail.complete(true);
});
}
diff --git a/static/usage/v8/reorder/basic/angular/example_component_html.md b/static/usage/v8/reorder/basic/angular/example_component_html.md
index 60795eaa3ff..8b1294bd101 100644
--- a/static/usage/v8/reorder/basic/angular/example_component_html.md
+++ b/static/usage/v8/reorder/basic/angular/example_component_html.md
@@ -2,7 +2,7 @@
-
+ Item 1
diff --git a/static/usage/v8/reorder/basic/angular/example_component_ts.md b/static/usage/v8/reorder/basic/angular/example_component_ts.md
index 541fd9c6df3..5553891178a 100644
--- a/static/usage/v8/reorder/basic/angular/example_component_ts.md
+++ b/static/usage/v8/reorder/basic/angular/example_component_ts.md
@@ -1,12 +1,12 @@
```ts
import { Component } from '@angular/core';
import {
- ItemReorderEventDetail,
IonItem,
IonLabel,
IonList,
IonReorder,
IonReorderGroup,
+ ReorderEndCustomEvent,
} from '@ionic/angular/standalone';
@Component({
@@ -16,14 +16,14 @@ import {
imports: [IonItem, IonLabel, IonList, IonReorder, IonReorderGroup],
})
export class ExampleComponent {
- handleReorder(event: CustomEvent) {
+ handleReorderEnd(event: ReorderEndCustomEvent) {
// The `from` and `to` properties contain the index of the item
// when the drag started and ended, respectively
console.log('Dragged from index', event.detail.from, 'to', event.detail.to);
// Finish the reorder and position the item in the DOM based on
// where the gesture ended. This method can also be called directly
- // by the reorder group
+ // by the reorder group.
event.detail.complete();
}
}
diff --git a/static/usage/v8/reorder/basic/demo.html b/static/usage/v8/reorder/basic/demo.html
index f9afb7d750a..7b8abca0b96 100644
--- a/static/usage/v8/reorder/basic/demo.html
+++ b/static/usage/v8/reorder/basic/demo.html
@@ -11,7 +11,7 @@
@@ -56,14 +56,14 @@
diff --git a/static/usage/v8/reorder/basic/javascript.md b/static/usage/v8/reorder/basic/javascript.md
index fe805d10fc6..4b07e8ad210 100644
--- a/static/usage/v8/reorder/basic/javascript.md
+++ b/static/usage/v8/reorder/basic/javascript.md
@@ -32,14 +32,14 @@
diff --git a/static/usage/v8/reorder/basic/react.md b/static/usage/v8/reorder/basic/react.md
index abe3b187294..397ebc395d7 100644
--- a/static/usage/v8/reorder/basic/react.md
+++ b/static/usage/v8/reorder/basic/react.md
@@ -1,23 +1,23 @@
```tsx
import React from 'react';
-import { IonItem, IonLabel, IonList, IonReorder, IonReorderGroup, ItemReorderEventDetail } from '@ionic/react';
+import { IonItem, IonLabel, IonList, IonReorder, IonReorderGroup, ReorderEndCustomEvent } from '@ionic/react';
function Example() {
- function handleReorder(event: CustomEvent) {
+ function handleReorderEnd(event: ReorderEndCustomEvent) {
// The `from` and `to` properties contain the index of the item
// when the drag started and ended, respectively
console.log('Dragged from index', event.detail.from, 'to', event.detail.to);
// Finish the reorder and position the item in the DOM based on
// where the gesture ended. This method can also be called directly
- // by the reorder group
+ // by the reorder group.
event.detail.complete();
}
return (
{/* The reorder gesture is disabled by default, enable it to drag and drop items */}
-
+ Item 1
diff --git a/static/usage/v8/reorder/basic/vue.md b/static/usage/v8/reorder/basic/vue.md
index 0ac2374089f..285a1c347be 100644
--- a/static/usage/v8/reorder/basic/vue.md
+++ b/static/usage/v8/reorder/basic/vue.md
@@ -2,7 +2,7 @@
-
+ Item 1
@@ -32,24 +32,24 @@
diff --git a/static/usage/v8/reorder/custom-icon/angular/example_component_html.md b/static/usage/v8/reorder/custom-icon/angular/example_component_html.md
index 6d1fb8960bd..cc6692c862d 100644
--- a/static/usage/v8/reorder/custom-icon/angular/example_component_html.md
+++ b/static/usage/v8/reorder/custom-icon/angular/example_component_html.md
@@ -2,7 +2,7 @@
-
+ Item 1
diff --git a/static/usage/v8/reorder/custom-icon/angular/example_component_ts.md b/static/usage/v8/reorder/custom-icon/angular/example_component_ts.md
index e9bdafd6df8..4d0472c0bd3 100644
--- a/static/usage/v8/reorder/custom-icon/angular/example_component_ts.md
+++ b/static/usage/v8/reorder/custom-icon/angular/example_component_ts.md
@@ -1,13 +1,13 @@
```ts
import { Component } from '@angular/core';
import {
- ItemReorderEventDetail,
IonIcon,
IonItem,
IonLabel,
IonList,
IonReorder,
IonReorderGroup,
+ ReorderEndCustomEvent,
} from '@ionic/angular/standalone';
import { addIcons } from 'ionicons';
@@ -29,14 +29,14 @@ export class ExampleComponent {
addIcons({ pizza });
}
- handleReorder(event: CustomEvent) {
+ handleReorderEnd(event: ReorderEndCustomEvent) {
// The `from` and `to` properties contain the index of the item
// when the drag started and ended, respectively
console.log('Dragged from index', event.detail.from, 'to', event.detail.to);
// Finish the reorder and position the item in the DOM based on
// where the gesture ended. This method can also be called directly
- // by the reorder group
+ // by the reorder group.
event.detail.complete();
}
}
diff --git a/static/usage/v8/reorder/custom-icon/demo.html b/static/usage/v8/reorder/custom-icon/demo.html
index ab2c55b9423..b089815bd07 100644
--- a/static/usage/v8/reorder/custom-icon/demo.html
+++ b/static/usage/v8/reorder/custom-icon/demo.html
@@ -11,7 +11,7 @@
@@ -66,14 +66,14 @@
diff --git a/static/usage/v8/reorder/custom-icon/javascript.md b/static/usage/v8/reorder/custom-icon/javascript.md
index d7aa87d8f64..8535da7544a 100644
--- a/static/usage/v8/reorder/custom-icon/javascript.md
+++ b/static/usage/v8/reorder/custom-icon/javascript.md
@@ -42,14 +42,14 @@
diff --git a/static/usage/v8/reorder/custom-icon/javascript/index_html.md b/static/usage/v8/reorder/custom-icon/javascript/index_html.md
index d7aa87d8f64..8535da7544a 100644
--- a/static/usage/v8/reorder/custom-icon/javascript/index_html.md
+++ b/static/usage/v8/reorder/custom-icon/javascript/index_html.md
@@ -42,14 +42,14 @@
diff --git a/static/usage/v8/reorder/custom-icon/react.md b/static/usage/v8/reorder/custom-icon/react.md
index 9103db6029d..f5fe620035b 100644
--- a/static/usage/v8/reorder/custom-icon/react.md
+++ b/static/usage/v8/reorder/custom-icon/react.md
@@ -1,24 +1,24 @@
```tsx
import React from 'react';
-import { IonIcon, IonItem, IonLabel, IonList, IonReorder, IonReorderGroup, ItemReorderEventDetail } from '@ionic/react';
+import { IonIcon, IonItem, IonLabel, IonList, IonReorder, IonReorderGroup, ReorderEndCustomEvent } from '@ionic/react';
import { pizza } from 'ionicons/icons';
function Example() {
- function handleReorder(event: CustomEvent) {
+ function handleReorderEnd(event: ReorderEndCustomEvent) {
// The `from` and `to` properties contain the index of the item
// when the drag started and ended, respectively
console.log('Dragged from index', event.detail.from, 'to', event.detail.to);
// Finish the reorder and position the item in the DOM based on
// where the gesture ended. This method can also be called directly
- // by the reorder group
+ // by the reorder group.
event.detail.complete();
}
return (
{/* The reorder gesture is disabled by default, enable it to drag and drop items */}
-
+ Item 1
diff --git a/static/usage/v8/reorder/custom-icon/vue.md b/static/usage/v8/reorder/custom-icon/vue.md
index 87d77e33048..eec6b5222a9 100644
--- a/static/usage/v8/reorder/custom-icon/vue.md
+++ b/static/usage/v8/reorder/custom-icon/vue.md
@@ -2,7 +2,7 @@
-
+ Item 1
@@ -42,24 +42,24 @@
diff --git a/static/usage/v8/reorder/custom-scroll-target/angular/example_component_html.md b/static/usage/v8/reorder/custom-scroll-target/angular/example_component_html.md
index 2296a5506c4..73fc3967021 100644
--- a/static/usage/v8/reorder/custom-scroll-target/angular/example_component_html.md
+++ b/static/usage/v8/reorder/custom-scroll-target/angular/example_component_html.md
@@ -4,7 +4,7 @@
-
+ Item 1
diff --git a/static/usage/v8/reorder/custom-scroll-target/angular/example_component_ts.md b/static/usage/v8/reorder/custom-scroll-target/angular/example_component_ts.md
index bdd83c0417f..84dedb755b1 100644
--- a/static/usage/v8/reorder/custom-scroll-target/angular/example_component_ts.md
+++ b/static/usage/v8/reorder/custom-scroll-target/angular/example_component_ts.md
@@ -1,7 +1,7 @@
```ts
import { Component } from '@angular/core';
import {
- ItemReorderEventDetail,
+ ReorderEndCustomEvent,
IonContent,
IonItem,
IonLabel,
@@ -17,14 +17,14 @@ import {
imports: [IonContent, IonItem, IonLabel, IonList, IonReorder, IonReorderGroup],
})
export class ExampleComponent {
- handleReorder(event: CustomEvent) {
+ handleReorderEnd(event: ReorderEndCustomEvent) {
// The `from` and `to` properties contain the index of the item
// when the drag started and ended, respectively
console.log('Dragged from index', event.detail.from, 'to', event.detail.to);
// Finish the reorder and position the item in the DOM based on
// where the gesture ended. This method can also be called directly
- // by the reorder group
+ // by the reorder group.
event.detail.complete();
}
}
diff --git a/static/usage/v8/reorder/custom-scroll-target/demo.html b/static/usage/v8/reorder/custom-scroll-target/demo.html
index 760fb525d79..fb66a69e0ce 100644
--- a/static/usage/v8/reorder/custom-scroll-target/demo.html
+++ b/static/usage/v8/reorder/custom-scroll-target/demo.html
@@ -10,16 +10,17 @@
+
+
+
+
+
+