Deprecate onReorder callback

The onReorder callback in the ReorderableListView, ReorderableListView.builder, ReorderableList, and SliverReorderableList widgets has been replaced by a new callback, onReorderItem, which provides more intuitive behavior for newIndex.

The onReorder callback in the ReorderableListView, ReorderableListView.builder, ReorderableList, and SliverReorderableList widgets required a manual correction for the second parameter, newIndex, in case the oldIndex is before the newIndex because the list of items would be shortened by one element.

void handleReorder(int oldIndex, int newIndex) {
  if (oldIndex < newIndex) {
    // Removing the item at oldIndex shortens the list by 1.
    newIndex -= 1;
  }
​
  // Handle the actual reorder behavior...
}
​
ReorderableListView(
  onReorder: handleReorder,
)

The new callback, onReorderItem, solves this problem by doing the correction automatically.

void handleReorder(int oldIndex, int newIndex) {
  // Handle the actual reorder behavior...
}
​
ReorderableListView(
  onReorderItem: handleReorder,
)

The ReorderableListView, ReorderableListView.builder, ReorderableList, and SliverReorderableList widgets share the same reordering logic. The same migration steps apply to each of these widgets.

This migration guide uses ReorderableListView as an example.

Code before migration:

ReorderableListView(
  onReorder: (int oldIndex, int newIndex) {
    if (oldIndex < newIndex) {
      newIndex -= 1;
    }
​
    // Handle reorder ...
  }
)

Code after migration:

ReorderableListView(
  onReorder: (int oldIndex, int newIndex) {
    if (oldIndex < newIndex) {
      newIndex -= 1;
    }
​
  onReorderItem: (int oldIndex, int newIndex) {
    // Handle reorder ...
  }
)

In some cases, such as when the provided callback is complex, the migration to the new onReorderItem callback might not be obvious.

In these cases, to opt out of the new behavior, adjust the newIndex to match the old behavior.

Code before migration:

void handleSomeComplexReorder(int oldIndex, int newIndex) {
  // Handle reorder ...
}
​
ReorderableListView(
  onReorder: (int oldIndex, int newIndex) {
    handleSomeComplexReorder(oldIndex, newIndex);
  }
)

Code after migration:

void handleSomeComplexReorder(int oldIndex, int newIndex) {
  // Handle reorder ...
}
​
ReorderableListView(
  onReorder: (int oldIndex, int newIndex) {
  onReorderItem: (int oldIndex, int newIndex) {
    // To get the equivalent of the old newIndex:
    if (oldIndex < newIndex) {
      newIndex += 1;
    }
​
    return handleSomeComplexReorder(oldIndex, newIndex);
  }
)

Landed in version: 3.41.0-1.0.pre-364
In stable release: 3.44

API documentation:

• ReorderCallback
• ReorderableList
• ReorderableListView
• SliverReorderableList

Relevant issues:

• The index parameter for ReorderableListView's onReorderCallback is confusing
• SliverReorderableList newIndex arg off by one on drag down list

Relevant PRs:

• Deprecate onReorder callback