Add `.separated` constructor to `ReorderableListView` #168834

Fintasys · May 14, 2025

This PR introduces a .separated constructor to the ReorderableListView widget. The .separated constructor allows developers to define custom separators between the list items without the need to manually modify their list or create custom widgets. This API enhancement improves the overall usability and flexibility of ReorderableListView.

Key Changes:

Added a new .separated constructor to ReorderableListView.
Included appropriate documentation for the new constructor with usage examples.
Updated the relevant tests to verify the behavior of .separated functionality.
Ensured backward compatibility for existing constructors.

This new feature addresses the requests in issue #76706.

Pre-launch Checklist

I read the Contributor Guide and followed the process outlined there for submitting PRs.
I read the Tree Hygiene wiki page, which explains my responsibilities.
I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
I signed the CLA.
I listed at least one issue that this PR fixes in the description above.
I updated/added relevant documentation (doc comments with ///).
I added new tests to check the change I am making, or this PR is test-exempt.
I followed the breaking change policy and added Data Driven Fixes where supported.
All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

Video

separated_example.mp4

victorsanni · May 22, 2025

packages/flutter/lib/src/material/reorderable_list.dart

@@ -75,6 +76,8 @@ class ReorderableListView extends StatefulWidget {
  ///
  ///   * [ReorderableListView.builder], which allows you to build a reorderable
  ///     list where the items are built as needed when scrolling the list.
+  ///   * [ReorderableListView.separated], which allows you to build a reorderable


Nit: Unrelated to this PR, but this and above (ReorderableListView.builder) should use third person instead of second person (i.e no 'you'). https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md#use-the-passive-voice-recommend-do-not-require-never-say-things-are-simple

victorsanni · May 22, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+         }
+         final int itemIndex = index ~/ 2;
+         if (index.isEven) {
+           // It's an item


Nit: Here and below, I'm not sure the comments add anything not already clear from the lines of code succeeding it.

victorsanni · May 22, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+           // It's an item
+           return itemBuilder(context, itemIndex);
+         } else {
+           // It's a separator


packages/flutter/lib/src/material/reorderable_list.dart

victorsanni · May 22, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+  /// When using the [ReorderableListView.separated] constructor, this is the total
+  /// number of children in the list, including items and separators.
+  /// The actual number of data items is less.


Since there is a separatorBuilder, is there a world where this only counts data items? or is this because a user might want separators only on certain indices?

Do you think renaming it to childCount would make more sense? I was just following the existing naming pattern. Should itemCount be stored in the widget as well?

victorsanni · May 22, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+  /// This callback is used to build the separator widgets that appear between items.
+  /// It is called with indices from 0 to `itemCount - 2` (where `itemCount` is
+  /// the number of actual data items).


Instead of speculating about the data items or non-data items, can we directly reference ReorderableListView.itemCount here (assuming an item-separator-item pattern)?

Related to above question, I think it's better then to store itemCount and childCount separately and itemCount can be properly referenced here.

victorsanni · May 22, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+  /// It is called with indices from 0 to `itemCount - 2` (where `itemCount` is
+  /// the number of actual data items).
+  ///
+  /// Will be null if not using the `separated` constructor.


Suggested change

/// Will be null if not using the `separated` constructor.

/// Null if this is not a `ReorderableListView.separated`.

or something similar.

victorsanni · May 22, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+  /// Will be null if not using the `separated` constructor.
+  final IndexedWidgetBuilder? separatorBuilder;
+
+  /// Helper method to compute the actual child count for the separated constructor.


Suggested change

/// Helper method to compute the actual child count for the separated constructor.

/// Helper method to compute the actual child count for a `ReorderableListView.separated`.

Prefer the actual reference over a (possibly) vague allusion.

victorsanni · May 22, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+    // If using .separated, separators are at odd indices.
+    // We only want drag handles and specific keys for actual items (even indices).
+    final bool isSeparator = widget.separatorBuilder != null && index.isOdd;


This feels odd (no pun intended). Does this break down if a user has their separators at non-regular intervals?

The current implementation enforces a regular pattern where separators must appear between every item. This is by design and matches the behavior of ListView.separated. If users need non-regular separators, they should use the regular ReorderableListView or ReorderableListView.builder constructors and handle the separators manually in their item builder.

The documentation for the constructor should contain this info if it doesn't already.

Fintasys · May 27, 2025

@victorsanni Thanks for the detailed review ! I tried to address all of your concerns, please have another look 🙇

Fintasys · May 27, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+       itemCount = children.length,
+       childCount = children.length,


Note
Keep separated track of itemCount and childCount. itemCount is used in the default constructor and .builder constructor. .seperated constructor requires additional property childCount to keep track of combined count of items + divider.

I see ListView.separated does something similar with what you had previously (using itemCount etc). I first blind-reviewed but now I see the implementation aims to be almost identical to ListView.separated.

Can I confirm with you if you say I should revert my changes and exclusively use itemCount? Or is it okay to continue having separate variables for itemCount and childCount ? Later one makes technical more sense to me.

The problem is that childCount is defined and calculated but never used. If childCount does not modify the behavior of this widget, then it shouldn't be added.

victorsanni

Thanks for responding! Can you also attach videos/screenshots to the PR description comparing before/after? This will make the PR easier to review.

The example and tests are also really nice. For now, can you attach the example code to the PR description, and add the example/example test in a subsequent PR? The leaner the PR, the easier it is to review.

Thanks once again.

victorsanni · May 27, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+       itemCount = children.length,
+       childCount = children.length,


I see ListView.separated does something similar with what you had previously (using itemCount etc). I first blind-reviewed but now I see the implementation aims to be almost identical to ListView.separated.

victorsanni · May 27, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+    // If using .separated, separators are at odd indices.
+    // We only want drag handles and specific keys for actual items (even indices).
+    final bool isSeparator = widget.separatorBuilder != null && index.isOdd;


The documentation for the constructor should contain this info if it doesn't already.

victorsanni · May 27, 2025

packages/flutter/lib/src/material/reorderable_list.dart

@@ -143,7 +148,7 @@ class ReorderableListView extends StatefulWidget {
  /// {@end-tool}
  /// See also:
  ///
-  ///   * [ReorderableListView], which allows you to build a reorderable
+  ///   * [ReorderableListView], which allows one to build a reorderable


Suggested change

/// * [ReorderableListView], which allows one to build a reorderable

/// * [ReorderableListView], which builds a reorderable

Or something similar. But this is a nit, feel free to edit.

victorsanni · May 27, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+  /// number of children in the list, including items and separators.
+  /// When using [ReorderableListView] or the [ReorderableListView.builder] constructor, this is the number of items
+  /// in the list.
+  final int childCount;


Don't think this property should be added.

victorsanni · May 27, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+  /// The number of data items in the list.
+  ///
+  /// This is the number of data items in the list, not the number of children.
+  /// For example, if there is a list with 10 items and 9 separators, this will be 10.


If this is custom, then the macro should be removed. You can combine the information in here with what the macro already has with something like this:

/// The number of data items in the list. /// /// If this widget is a ReorderableListView.separated, {insert docs for special case} /// /// This value must be a non-negative integer. When zero, nothing is displayed and /// the widget occupies no space.

victorsanni · May 27, 2025

packages/flutter/lib/src/material/reorderable_list.dart

  final double? itemExtent;

  /// {@macro flutter.widgets.list_view.itemExtentBuilder}
+  /// This is not used by the [ReorderableListView.separated] constructor.


Suggested change

/// This is not used by the [ReorderableListView.separated] constructor.

///

/// Null if this is a [ReorderableListView.separated].

victorsanni · May 27, 2025

packages/flutter/lib/src/material/reorderable_list.dart

  final ItemExtentBuilder? itemExtentBuilder;

  /// {@macro flutter.widgets.list_view.prototypeItem}
+  /// This is not used by the [ReorderableListView.separated] constructor.


Suggested change

/// This is not used by the [ReorderableListView.separated] constructor.

///

/// Null if this is a [ReorderableListView.separated].

victorsanni · May 27, 2025

packages/flutter/lib/src/material/reorderable_list.dart

+  /// Helper method to compute the actual child count for [ReorderableListView.separated].
+  static int _computeActualChildCount(int itemCount) {
+    return math.max(0, itemCount * 2 - 1);
+  }


Not sure this method is needed or used.

This method is needed to calculate the total child length based on amount of items and the necessary dividers.

The method is only used here to calculate childCount, but childCount is never used as far as I can see. Could I be missing something?

You suggest to remove childCount and consolidate it with itemCount. For calculation of itemCount we would still need the method to properly count the total items (items + divider count). Am I completely misunderstanding what you mean?
Or do you mean it is not necessary to combine divider count + item count into itemCount so that itemCount should just be the number of items (exclusive dividers). I didn't consider that so far, cause I'm not sure if it plays internally a role.

I searched in this file for childCount. I saw it was added as a property, and it was also updated here:

childCount = _computeActualChildCount(itemCount),

but I can't find where it is actually used/referenced.

You suggest to remove childCount and consolidate it with itemCount. For calculation of itemCount we would still need the method to properly count the total items (items + divider count). Am I completely misunderstanding what you mean?

If the method is needed to calculate itemCount, then it should be used to do that. But right now I don't see it being used to calculate itemCount, only childCount.

packages/flutter/lib/src/widgets/reorderable_list.dart

packages/flutter/lib/src/material/reorderable_list.dart

Fintasys added 9 commits May 15, 2025 00:20

first working draft

70d9bd6

remove unnecessary changes

bc8be76

add example file

1a1567f

add tests

95a33de

update comment

8630334

undo removal

e22b611

Update reorderable_list.dart

42f5191

fix comment

b0f1a24

update comment

d0bd21f

github-actions bot added framework flutter/packages/flutter repository. See also f: labels. f: material design flutter/packages/flutter/material repository. d: api docs Issues with https://api.flutter.dev/ d: examples Sample code and demos labels May 14, 2025

Fintasys changed the title ~~Add separated constructor to reorderable list~~ Add .separated constructor to ReorderableListView May 14, 2025

Fintasys added 6 commits May 15, 2025 00:48

remove comment

2472232

address analyzer issues

cd41588

improve code

77c8e53

deal with separatorBuilder null case

1a0c67e

add test

bc5adc2

add interaction tests

cbff027

Fintasys marked this pull request as ready for review May 15, 2025 04:29

dkwingsmt requested a review from victorsanni May 21, 2025 18:11

victorsanni reviewed May 22, 2025

View reviewed changes

victorsanni requested a review from bleroux May 22, 2025 23:50

address comments, improve documentation

297393a

Fintasys added 2 commits May 27, 2025 17:31

fix ci issues

91e8a52

Fix incorrect usage

961686e

Fintasys commented May 27, 2025

View reviewed changes

fix inadvertently renaming

957f9a1

Fintasys added 3 commits May 27, 2025 17:49

re-add comment

ae2911c

fix comment

75fba0c

fix failing ci attempt

4538d23

victorsanni reviewed May 27, 2025

View reviewed changes

Fintasys and others added 2 commits June 2, 2025 01:06

address comments

0ac57ce

Merge branch 'master' into add-separated-constructor-to-reorderable_list

63baddd

	/// Will be null if not using the `separated` constructor.
	/// Null if this is not a `ReorderableListView.separated`.

	/// Helper method to compute the actual child count for the separated constructor.
	/// Helper method to compute the actual child count for a `ReorderableListView.separated`.

	/// * [ReorderableListView], which allows one to build a reorderable
	/// * [ReorderableListView], which builds a reorderable

	/// This is not used by the [ReorderableListView.separated] constructor.
	///
	/// Null if this is a [ReorderableListView.separated].

Search code, repositories, users, issues, pull requests...

Add .separated constructor to ReorderableListView #168834

Are you sure you want to change the base?

Add .separated constructor to ReorderableListView #168834

Uh oh!

Conversation

Fintasys commented May 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key Changes:

Pre-launch Checklist

Video

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Fintasys commented May 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

victorsanni left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Add `.separated` constructor to `ReorderableListView` #168834

Add `.separated` constructor to `ReorderableListView` #168834

Fintasys commented May 14, 2025 •

edited

Loading