From 9517b9031f0bdac1e37a1929b5cbb3fb6181ce84 Mon Sep 17 00:00:00 2001 From: rkishan516 Date: Wed, 5 Nov 2025 07:33:20 +0530 Subject: [PATCH 1/6] docs: add migration guide for findChildIndexCallback of seperated builders --- src/content/release/breaking-changes/index.md | 2 + ...rated-builder-find-child-index-callback.md | 156 ++++++++++++++++++ 2 files changed, 158 insertions(+) create mode 100644 src/content/release/breaking-changes/separated-builder-find-child-index-callback.md diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index ef6a3744604..250678aab04 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -41,12 +41,14 @@ They're sorted by release and listed in alphabetical order: * [`$FLUTTER_ROOT/version` replaced by `$FLUTTER_ROOT/bin/cache/flutter.version.json`][] * [Stop generating `AssetManifest.json`][] * [Deprecate `TextField.canRequestFocus`][] +* [Deprecated findChildIndexCallback for separated constructors][] [`FontWeight` also controls the weight attribute of variable fonts]: /release/breaking-changes/font-weight-variation [UISceneDelegate adoption]: /release/breaking-changes/uiscenedelegate [Stop generating `AssetManifest.json`]: /release/breaking-changes/asset-manifest-dot-json [`$FLUTTER_ROOT/version` replaced by `$FLUTTER_ROOT/bin/cache/flutter.version.json`]: /release/breaking-changes/flutter-root-version-file [Deprecate `TextField.canRequestFocus`]: /release/breaking-changes/can-request-focus +[Deprecated findChildIndexCallback for separated constructors]: /release/breaking-changes/separated-builder-find-child-index-callback ### Released in Flutter 3.38 diff --git a/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md new file mode 100644 index 00000000000..b1d870e7902 --- /dev/null +++ b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md @@ -0,0 +1,156 @@ +--- +title: Deprecated findChildIndexCallback for separated constructors +description: >- + The findChildIndexCallback parameter in ListView.separated and + SliverList.separated has been deprecated in favor of findItemIndexCallback. +--- + +## Summary + +The `findChildIndexCallback` parameter in `ListView.separated` and +`SliverList.separated` constructors has been deprecated in favor of +`findItemIndexCallback`. The new callback returns item indices directly, +eliminating the need for manual index calculations to account for separators. + +## Background + +In `ListView.separated` and `SliverList.separated` constructors, +the `findChildIndexCallback` was used to locate widgets by their key. +However, this callback returned child indices, which include both items +and separators in the internal widget tree. This meant developers had to +multiply item indices by 2 to get the correct child index, creating +confusion and error-prone code. + +The new `findItemIndexCallback` parameter simplifies this by working +directly with item indices, which do not include separators. +This makes the API more intuitive and reduces the likelihood of +index calculation errors. + +If you use the deprecated `findChildIndexCallback` parameter, +you will see a deprecation warning: + +``` +'findChildIndexCallback' is deprecated and shouldn't be used. +Use findItemIndexCallback instead. +findChildIndexCallback returns child indices (which include separators), +while findItemIndexCallback returns item indices (which do not). +If you were multiplying results by 2 to account for separators, +you can remove that workaround when migrating to findItemIndexCallback. +This feature was deprecated after v3.37.0-1.0.pre. +``` + +Additionally, if you try to provide both parameters, you will encounter +an assertion error: + +``` +Cannot provide both findItemIndexCallback and findChildIndexCallback. +Use findItemIndexCallback as findChildIndexCallback is deprecated. +``` + +## Migration guide + +To migrate from `findChildIndexCallback` to `findItemIndexCallback`, +replace the parameter name and remove any index multiplications +that were used to account for separators. + +Code before migration: + +```dart +ListView.separated( + itemCount: items.length, + findChildIndexCallback: (Key key) { + final ValueKey valueKey = key as ValueKey; + final int itemIndex = items.indexOf(valueKey.value); + // Multiply by 2 to account for separators + return itemIndex == -1 ? null : itemIndex * 2; + }, + itemBuilder: (BuildContext context, int index) { + return ListTile( + key: ValueKey(items[index]), + title: Text(items[index]), + ); + }, + separatorBuilder: (BuildContext context, int index) => const Divider(), +) +``` + +Code after migration: + +```dart +ListView.separated( + itemCount: items.length, + findItemIndexCallback: (Key key) { + final ValueKey valueKey = key as ValueKey; + // Return item index directly - no need to multiply by 2 + return items.indexOf(valueKey.value); + }, + itemBuilder: (BuildContext context, int index) { + return ListTile( + key: ValueKey(items[index]), + title: Text(items[index]), + ); + }, + separatorBuilder: (BuildContext context, int index) => const Divider(), +) +``` + +The same migration applies to `SliverList.separated`: + +Code before migration: + +```dart +SliverList.separated( + itemCount: items.length, + findChildIndexCallback: (Key key) { + final ValueKey valueKey = key as ValueKey; + final int itemIndex = items.indexOf(valueKey.value); + return itemIndex == -1 ? null : itemIndex * 2; + }, + itemBuilder: (BuildContext context, int index) { + return Container( + key: ValueKey(items[index]), + child: Text(items[index]), + ); + }, + separatorBuilder: (BuildContext context, int index) => const Divider(), +) +``` + +Code after migration: + +```dart +SliverList.separated( + itemCount: items.length, + findItemIndexCallback: (Key key) { + final ValueKey valueKey = key as ValueKey; + return items.indexOf(valueKey.value); + }, + itemBuilder: (BuildContext context, int index) { + return Container( + key: ValueKey(items[index]), + child: Text(items[index]), + ); + }, + separatorBuilder: (BuildContext context, int index) => const Divider(), +) +``` + +## Timeline + +Landed in version: 3.38.0-1.0.pre
+In stable release: Not yet + +## References + +API documentation: + +* [`ListView.separated`][] +* [`SliverList.separated`][] + +Relevant PRs: + +* [Deprecate findChildIndexCallback for separated constructors][] + +[`ListView.separated`]: {{site.api}}/flutter/widgets/ListView/ListView.separated.html +[`SliverList.separated`]: {{site.api}}/flutter/widgets/SliverList/SliverList.separated.html +[Deprecate findChildIndexCallback for separated constructors]: {{site.repo.flutter}}/pull/174491 From 453c654b26e7c52bdce5e3a8d82a297151615695 Mon Sep 17 00:00:00 2001 From: rkishan516 Date: Thu, 6 Nov 2025 06:39:01 +0530 Subject: [PATCH 2/6] docs: update findItemIndexCallback example based on gemini feedback --- .../separated-builder-find-child-index-callback.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md index b1d870e7902..b217dc81120 100644 --- a/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md +++ b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md @@ -81,8 +81,9 @@ ListView.separated( itemCount: items.length, findItemIndexCallback: (Key key) { final ValueKey valueKey = key as ValueKey; + final int itemIndex = items.indexOf(valueKey.value); // Return item index directly - no need to multiply by 2 - return items.indexOf(valueKey.value); + return itemIndex == -1 ? null : itemIndex; }, itemBuilder: (BuildContext context, int index) { return ListTile( @@ -123,7 +124,8 @@ SliverList.separated( itemCount: items.length, findItemIndexCallback: (Key key) { final ValueKey valueKey = key as ValueKey; - return items.indexOf(valueKey.value); + final int itemIndex = items.indexOf(valueKey.value); + return itemIndex == -1 ? null : itemIndex; }, itemBuilder: (BuildContext context, int index) { return Container( From bf665300acef3428d9303615e0c7f3380ba175ce Mon Sep 17 00:00:00 2001 From: rkishan516 Date: Fri, 7 Nov 2025 06:43:42 +0530 Subject: [PATCH 3/6] docs: update title for migration guide --- src/content/release/breaking-changes/index.md | 4 ++-- .../separated-builder-find-child-index-callback.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/content/release/breaking-changes/index.md b/src/content/release/breaking-changes/index.md index 250678aab04..706f8aacaa5 100644 --- a/src/content/release/breaking-changes/index.md +++ b/src/content/release/breaking-changes/index.md @@ -41,14 +41,14 @@ They're sorted by release and listed in alphabetical order: * [`$FLUTTER_ROOT/version` replaced by `$FLUTTER_ROOT/bin/cache/flutter.version.json`][] * [Stop generating `AssetManifest.json`][] * [Deprecate `TextField.canRequestFocus`][] -* [Deprecated findChildIndexCallback for separated constructors][] +* [Deprecate `findChildIndexCallback` in favor of `findItemIndexCallback` in `ListView` and `SliverList` separated constructors][] [`FontWeight` also controls the weight attribute of variable fonts]: /release/breaking-changes/font-weight-variation [UISceneDelegate adoption]: /release/breaking-changes/uiscenedelegate [Stop generating `AssetManifest.json`]: /release/breaking-changes/asset-manifest-dot-json [`$FLUTTER_ROOT/version` replaced by `$FLUTTER_ROOT/bin/cache/flutter.version.json`]: /release/breaking-changes/flutter-root-version-file [Deprecate `TextField.canRequestFocus`]: /release/breaking-changes/can-request-focus -[Deprecated findChildIndexCallback for separated constructors]: /release/breaking-changes/separated-builder-find-child-index-callback +[Deprecate `findChildIndexCallback` in favor of `findItemIndexCallback` in `ListView` and `SliverList` separated constructors]: /release/breaking-changes/separated-builder-find-child-index-callback ### Released in Flutter 3.38 diff --git a/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md index b217dc81120..f07656dc839 100644 --- a/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md +++ b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md @@ -1,5 +1,5 @@ --- -title: Deprecated findChildIndexCallback for separated constructors +title: Deprecate `findChildIndexCallback` in favor of `findItemIndexCallback` in `ListView` and `SliverList` separated constructors description: >- The findChildIndexCallback parameter in ListView.separated and SliverList.separated has been deprecated in favor of findItemIndexCallback. From 8dceca3a1a0f897e67ef6f7b36f54841a9796e16 Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 13 Nov 2025 09:45:10 -0800 Subject: [PATCH 4/6] Update src/content/release/breaking-changes/separated-builder-find-child-index-callback.md --- .../separated-builder-find-child-index-callback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md index f07656dc839..3192b7b7fca 100644 --- a/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md +++ b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md @@ -2,7 +2,7 @@ title: Deprecate `findChildIndexCallback` in favor of `findItemIndexCallback` in `ListView` and `SliverList` separated constructors description: >- The findChildIndexCallback parameter in ListView.separated and - SliverList.separated has been deprecated in favor of findItemIndexCallback. + SliverList.separated have been deprecated in favor of findItemIndexCallback. --- ## Summary From 3320dde4fc7f3cbff78b3902fe9d2bddb95ca8ca Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 13 Nov 2025 09:45:20 -0800 Subject: [PATCH 5/6] Update src/content/release/breaking-changes/separated-builder-find-child-index-callback.md --- .../separated-builder-find-child-index-callback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md index 3192b7b7fca..88d613cfe81 100644 --- a/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md +++ b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md @@ -8,7 +8,7 @@ description: >- ## Summary The `findChildIndexCallback` parameter in `ListView.separated` and -`SliverList.separated` constructors has been deprecated in favor of +`SliverList.separated` constructors have been deprecated in favor of `findItemIndexCallback`. The new callback returns item indices directly, eliminating the need for manual index calculations to account for separators. From 8435295aaecc629874255c653f531cd1408c8468 Mon Sep 17 00:00:00 2001 From: Shams Zakhour <44418985+sfshaza2@users.noreply.github.com> Date: Thu, 13 Nov 2025 09:45:29 -0800 Subject: [PATCH 6/6] Update src/content/release/breaking-changes/separated-builder-find-child-index-callback.md --- .../separated-builder-find-child-index-callback.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md index 88d613cfe81..a67c0fb21dd 100644 --- a/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md +++ b/src/content/release/breaking-changes/separated-builder-find-child-index-callback.md @@ -17,7 +17,7 @@ eliminating the need for manual index calculations to account for separators. In `ListView.separated` and `SliverList.separated` constructors, the `findChildIndexCallback` was used to locate widgets by their key. However, this callback returned child indices, which include both items -and separators in the internal widget tree. This meant developers had to +and separators in the internal widget tree. This meant that developers had to multiply item indices by 2 to get the correct child index, creating confusion and error-prone code.