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 a more intuitive behavior on index.

The onReorder callback in the ReorderableListView, ReorderableListView.builder, ReorderableList and SliverReorderableList widgets used to require a manual correction for the second parameter, newIndex, in case the oldIndex is before the newIndex, due to the list of items shortening by one element in this case.

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

The new callback, onReorderItem, aims to solve 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 migration steps are identical for any of these widgets.

For the purpose of this migration guide, ReorderableListView is chosen 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, it might not be obvious how to do the migration to the new onReorderItem callback, particularly if the provided callback is very complex.

In that case, 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: Not yet

API documentation:

• ReorderCallback
• ReorderableList
• ReorderableListView
• SliverReorderableList

Relevant issues:

• Issue 127901
• Issue 169878

Relevant PRs:

• Deprecate onReorder callback