Feat: Add carousel view builder #172837

rkishan516 · 2025-07-28T05:31:42Z

Add carousel view builder named constructor
Fixes: #170692

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.

QuncCccccc

Instead of introducing 2 more constructor methods, can we just add itemBuilder to the existing methods?

rkishan516 · 2025-08-20T01:58:07Z

Instead of introducing 2 more constructor methods, can we just add itemBuilder to the existing methods?

Yes, that's certainly possible. However, I'd recommend maintaining consistency with the established patterns, as widgets like ListView and PageView follow this same approach. Should we still do this change?

QuncCccccc · 2025-08-20T17:03:12Z

I see. Then I think this way sounds good to me! I'll take another look today:)!

QuncCccccc · 2025-08-26T01:22:43Z

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

+       itemBuilder = null,
+       itemCount = null;
+
+  /// Creates a scrollable carousel with items created on demand.


Maybe

Suggested change

/// Creates a scrollable carousel with items created on demand.

/// Creates a scrollable carousel with fixed-sized items created on demand.

QuncCccccc · 2025-08-26T01:27:06Z

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

+  /// Will be called only for indices greater than or equal to zero and less than [itemCount].
+  ///
+  /// Must return a non-null widget for valid indices.
+  final Widget Function(BuildContext, int)? itemBuilder;


Maybe create a typedef CarouselItemBuilder = Widget Function(BuildContext, int)? so here would look simper:) typedef should be placed on the top of this file.

QuncCccccc · 2025-08-26T01:31:08Z

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

+        ? (BuildContext context, int index) => _buildCarouselItem(index)
+        : (BuildContext context, int index) => _buildCarouselItem(index);


This return the same no matter widget.itemBuilder is null or not?

QuncCccccc · 2025-08-26T01:36:26Z

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


    final bool hasFlexWeights = _carouselState!._flexWeights?.isNotEmpty ?? false;
-    index = index.clamp(0, _carouselState!.widget.children.length - 1);
+    final int itemCount =


If we use the lazy loading constructors, and if widget.itemCount is not specified, itemCount will default to 0 and then index.clamp(0, itemCount - 1) will have an invalid upper limit.

QuncCccccc · 2025-08-26T01:36:42Z

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

    int leadingIndex = carouselState._consumeMaxWeight ? index : index - maxWeightIndex;
-    leadingIndex = leadingIndex.clamp(0, _carouselState!.widget.children.length - 1);
+    final int itemCount = carouselState.widget.itemCount ?? carouselState.widget.children.length;
+    leadingIndex = leadingIndex.clamp(0, itemCount - 1);


rkishan516 · 2025-08-26T13:33:45Z

@QuncCccccc Updated PR based on all your feedback.

QuncCccccc

LGTM with nits. Thanks for your contribution:)

QuncCccccc · 2025-09-03T04:14:13Z

packages/flutter/test/material/carousel_test.dart

    expect(secondItemWidth, surfaceWidth * secondWeight / totalWeight);
  });

+  testWidgets('CarouselView.builder creates items lazily', (WidgetTester tester) async {


Can we also add one more unit test for CarouselView.buildWeighted?

Sure. will add..

QuncCccccc · 2025-09-03T04:14:56Z

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

+  /// This example shows how to create a weighted carousel with lazy loading:
+  ///
+  /// ```dart
+  /// CarouselView.buildWeighted(


Maybe CarouselView.weightedBuilder? Just to be consistent with others.

Sure, will update.

QuncCccccc

LGTM.
carousel_test.dart might need to reformat to fix the linux_analyze test

justinmc

Thanks for writing this. I think this is a pretty cool use of Carousel and I'm glad we're going to support it.

I'm curious about what the story is here for an infinite carousel. Is it supported? I left some comments in the docs about my confusion over when itemBuilder should return null. I think knowing whether infinite carousels are supported will inform how we should explain those things in the docs. Also if they are supported, could you add a test for an infinite carousel too?

justinmc · 2025-09-03T17:07:46Z

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

+  /// The [itemBuilder] should return null if asked to build an item with an
+  /// index greater than or equal to [itemCount].


Elsewhere your docs say that this will never happen though?

Yup, forgot to update doc. This was for initial implementation.

justinmc · 2025-09-03T17:08:59Z

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

+  /// Will be called only for indices greater than or equal to zero and less than [itemCount].
+  ///
+  /// Must return a non-null widget for valid indices.


Below you say:

If null, the carousel will continue to build items until [itemBuilder] returns null.

Does that contradict these two sentences?

I think my intention was different but updating to make it simple.

justinmc · 2025-09-03T17:13:11Z

packages/flutter/test/material/carousel_test.dart

+    await tester.pump();
+
+    // Should have built new items, not the initial ones.
+    expect(builtItems.isNotEmpty, isTrue);


I think you can do something like this and get a better error message when a failure happens:

expect(builtItems, isNotEmpty);

rkishan516 · 2025-09-04T02:06:37Z

I don't think currently infinite carousel is supported, but I am planning. to add support for that once this get merged.

Piinks · 2025-09-26T22:09:59Z

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

+  /// This example shows how to create a carousel with 1000 items using lazy loading:
+  ///
+  /// ```dart
+  /// CarouselView.builder(


Could these be extracted to actual samples that have tests and are interactive in the API docs?

Sure, I have updated API docs.

Piinks

LGTM, thank you for converting those samples!

Piinks · 2025-10-07T23:26:35Z

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

+  /// This example shows how to create a carousel with 1000 items using lazy loading:
+  ///
+  /// ** See code in examples/api/lib/material/carousel/carousel.1.dart **
+  /// {@end-tool}


Nit: you could add a See also: here that refers to the other constructors.

Piinks · 2025-10-07T23:26:55Z

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

+  ///   },
+  /// )
+  /// ```
+  /// {@end-tool}


Nit: ++ for See also breadcrumbs.

Roll Flutter from 908012d58baa to e11e2c11288b (39 revisions) flutter/flutter@908012d...e11e2c1 2025-10-08 vegorov@google.com Configure FfiNative resolver on dart:io (flutter/flutter#176621) 2025-10-08 fluttergithubbot@gmail.com Marks Linux_pixel_7pro service_extensions_test to be unflaky (flutter/flutter#176700) 2025-10-08 matt.boetger@gmail.com Keyboard Animation Fix (flutter/flutter#176418) 2025-10-08 34465683+rkishan516@users.noreply.github.com Feat: Add carousel view builder (flutter/flutter#172837) 2025-10-08 engine-flutter-autoroll@skia.org Roll Skia from d10a0d877ff4 to ea7cdbc6b986 (15 revisions) (flutter/flutter#176686) 2025-10-08 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from jJr3my9C6TwYWPygi... to xrIAL91ngrd-wNr9S... (flutter/flutter#176682) 2025-10-08 bruno.leroux@gmail.com Fix InputDecoration helper/error padding is not compliant (flutter/flutter#176353) 2025-10-08 sokolovskyi.konstantin@gmail.com Fix PopupMenu does not update when PopupMenuTheme in Theme changes. (flutter/flutter#175513) 2025-10-07 iinozemtsev@google.com Roll Dart SDK to 3.10.0-290.1.beta (flutter/flutter#176629) 2025-10-07 bkonyi@google.com [ Tool ] Output `app.dtd` and `app.devTools` in machine mode (flutter/flutter#176655) 2025-10-07 15619084+vashworth@users.noreply.github.com Rename UIScene integration test projects and fix Xcode compatibility (flutter/flutter#176635) 2025-10-07 21270878+elliette@users.noreply.github.com Selecting an implementation widget with the on-device inspector opens the code location for the nearest project widget (flutter/flutter#176530) 2025-10-07 32538273+ValentinVignal@users.noreply.github.com Migrate to `WidgetStateInputBorder` (flutter/flutter#176386) 2025-10-07 34871572+gmackall@users.noreply.github.com Make it clear that you need to install clangd in VSCode intellisense c++ config (flutter/flutter#176609) 2025-10-07 paulberry@google.com Bump the customer tests to pick up an update to Zulip's tests. (flutter/flutter#176463) 2025-10-07 engine-flutter-autoroll@skia.org Roll Packages from d3ef88b to 8ca6416 (2 revisions) (flutter/flutter#176633) 2025-10-07 15619084+vashworth@users.noreply.github.com Add fallback for 'scene:willConnectToSession:options' (flutter/flutter#176580) 2025-10-07 engine-flutter-autoroll@skia.org Roll Skia from d09786dfb854 to d10a0d877ff4 (11 revisions) (flutter/flutter#176616) 2025-10-07 bkonyi@google.com [ Widget Preview ] Rework UI and theming (flutter/flutter#176581) 2025-10-07 15619084+vashworth@users.noreply.github.com Handle FlutterEngine registration when embedded in Multi-Scene apps (flutter/flutter#176490) 2025-10-07 robert.ancell@canonical.com Fix code style in Linux embedder template (flutter/flutter#176256) 2025-10-07 15619084+vashworth@users.noreply.github.com Add tooling to migrate to UIScene (flutter/flutter#176427) 2025-10-06 danny@tuppeny.com Bump customer tests.version to 986c4326b4e4bb4e37bc963c2cc2aaa10b943859 (flutter/flutter#176594) 2025-10-06 43959652+TDuffinNTU@users.noreply.github.com Fix typo in pages.dart (flutter/flutter#176438) 2025-10-06 34465683+rkishan516@users.noreply.github.com Fix: Update anchorRect for overlayBuilder when anchor moves (flutter/flutter#169814) 2025-10-06 engine-flutter-autoroll@skia.org Roll Fuchsia Linux SDK from Zm6K_3gP3VCaMy9rH... to jJr3my9C6TwYWPygi... (flutter/flutter#176591) 2025-10-06 eternalkaif@gmail.com Fix deprecated configureStatusBarForFullscreenFlutterExperience for Android 15+ (flutter/flutter#175501) 2025-10-06 30870216+gaaclarke@users.noreply.github.com updates docs for flutter engine footprint (flutter/flutter#176217) 2025-10-06 bkonyi@google.com [ Widget Preview ] Fix `WidgetInspectorService` override (flutter/flutter#176550) 2025-10-06 bruno.leroux@gmail.com Fix NavigatorBar lacks visual feedback (flutter/flutter#175182) 2025-10-06 engine-flutter-autoroll@skia.org Roll Packages from e401aeb to d3ef88b (4 revisions) (flutter/flutter#176582) 2025-10-06 engine-flutter-autoroll@skia.org Roll Dart SDK from 898380a41c90 to 6b0193498f09 (2 revisions) (flutter/flutter#176576) 2025-10-06 engine-flutter-autoroll@skia.org Roll Skia from bc7cf194f4ee to d09786dfb854 (1 revision) (flutter/flutter#176577) 2025-10-06 jason-simmons@users.noreply.github.com Roll vulkan-deps to a9e2ca3b (flutter/flutter#176322) 2025-10-06 15619084+vashworth@users.noreply.github.com Add an AppDelegate callback for implicit FlutterEngines (flutter/flutter#176240) 2025-10-06 engine-flutter-autoroll@skia.org Roll Skia from 45191c22b15c to bc7cf194f4ee (2 revisions) (flutter/flutter#176572) 2025-10-06 bkonyi@google.com [ Widget Preview ] Fix type error when retrieving flags from persistent preferences (flutter/flutter#176546) 2025-10-06 engine-flutter-autoroll@skia.org Roll Skia from 1fd0ca1f2120 to 45191c22b15c (3 revisions) (flutter/flutter#176556) 2025-10-05 engine-flutter-autoroll@skia.org Roll Dart SDK from 016a8c0045fd to 898380a41c90 (1 revision) (flutter/flutter#176549) If this roll has caused a breakage, revert this CL and stop the roller using the controls here: https://autoroll.skia.org/r/flutter-packages Please CC muhatashim@google.com,stuartmorgan@google.com on the revert to ensure that a human is aware of the problem. ...

github-actions bot added framework flutter/packages/flutter repository. See also f: labels. f: material design flutter/packages/flutter/material repository. labels Jul 28, 2025

rkishan516 force-pushed the carousel-builder branch from c7eb95c to cbe7647 Compare July 30, 2025 01:34

dkwingsmt requested a review from QuncCccccc July 30, 2025 18:37

rkishan516 force-pushed the carousel-builder branch 2 times, most recently from a7db48f to d9c0832 Compare July 31, 2025 14:42

QuncCccccc reviewed Aug 20, 2025

View reviewed changes

QuncCccccc self-requested a review August 20, 2025 20:37

QuncCccccc reviewed Aug 26, 2025

View reviewed changes

rkishan516 force-pushed the carousel-builder branch from d9c0832 to 0d208c7 Compare August 26, 2025 13:32

QuncCccccc self-requested a review August 26, 2025 16:57

QuncCccccc reviewed Sep 3, 2025

View reviewed changes

rkishan516 force-pushed the carousel-builder branch from 0d208c7 to 7c87bb4 Compare September 3, 2025 16:09

QuncCccccc approved these changes Sep 3, 2025

View reviewed changes

justinmc reviewed Sep 3, 2025

View reviewed changes

rkishan516 force-pushed the carousel-builder branch from 7c87bb4 to a504486 Compare September 4, 2025 02:05

Piinks reviewed Sep 26, 2025

View reviewed changes

rkishan516 force-pushed the carousel-builder branch from a504486 to 1041be3 Compare September 27, 2025 01:39

github-actions bot added d: api docs Issues with https://api.flutter.dev/ d: examples Sample code and demos labels Sep 27, 2025

rkishan516 force-pushed the carousel-builder branch from 1041be3 to 97f99b0 Compare September 29, 2025 04:25

dkwingsmt requested a review from Piinks October 1, 2025 18:23

Piinks approved these changes Oct 7, 2025

View reviewed changes

rkishan516 added 2 commits October 8, 2025 07:58

Feat: Add carousel view builder

a74ce6f

docs: add see also breadcrumbs

1c965c9

rkishan516 force-pushed the carousel-builder branch from 97f99b0 to 1c965c9 Compare October 8, 2025 02:42

rkishan516 added the autosubmit Merge PR when tree becomes green via auto submit App label Oct 8, 2025

auto-submit bot added this pull request to the merge queue Oct 8, 2025

Merged via the queue into flutter:master with commit 7100df2 Oct 8, 2025
78 checks passed

flutter-dashboard bot removed the autosubmit Merge PR when tree becomes green via auto submit App label Oct 8, 2025

engine-flutter-autoroll mentioned this pull request Oct 8, 2025

Roll Flutter from 908012d58baa to 7100df24f611 (36 revisions) flutter/packages#10189

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 8, 2025

7100df24f Feat: Add carousel view builder (flutter/flutter#172837)

1544672

engine-flutter-autoroll mentioned this pull request Oct 8, 2025

Roll Flutter from 908012d58baa to 3379c7f0654b (37 revisions) flutter/packages#10190

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 8, 2025

7100df24f Feat: Add carousel view builder (flutter/flutter#172837)

c6510ab

engine-flutter-autoroll mentioned this pull request Oct 8, 2025

Roll Flutter from 908012d58baa to 44c77df80a87 (38 revisions) flutter/packages#10191

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 8, 2025

7100df24f Feat: Add carousel view builder (flutter/flutter#172837)

307d9ef

engine-flutter-autoroll mentioned this pull request Oct 8, 2025

Roll Flutter from 908012d58baa to e11e2c11288b (39 revisions) flutter/packages#10192

Merged

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 8, 2025

7100df24f Feat: Add carousel view builder (flutter/flutter#172837)

c910e16

engine-flutter-autoroll mentioned this pull request Oct 8, 2025

Roll Flutter from 908012d58baa to c56e52be0710 (40 revisions) flutter/packages#10194

Closed

engine-flutter-autoroll added a commit to engine-flutter-autoroll/packages that referenced this pull request Oct 8, 2025

7100df24f Feat: Add carousel view builder (flutter/flutter#172837)

798abac

	/// Creates a scrollable carousel with items created on demand.
	/// Creates a scrollable carousel with fixed-sized items created on demand.

		? (BuildContext context, int index) => _buildCarouselItem(index)
		: (BuildContext context, int index) => _buildCarouselItem(index);

		/// The [itemBuilder] should return null if asked to build an item with an
		/// index greater than or equal to [itemCount].

Feat: Add carousel view builder #172837

Feat: Add carousel view builder #172837

Uh oh!

Conversation

rkishan516 commented Jul 28, 2025

Pre-launch Checklist

Uh oh!

QuncCccccc left a comment

Choose a reason for hiding this comment

Uh oh!

rkishan516 commented Aug 20, 2025

Uh oh!

QuncCccccc commented Aug 20, 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!

Choose a reason for hiding this comment

Uh oh!

rkishan516 commented Aug 26, 2025

Uh oh!

QuncCccccc 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!

QuncCccccc left a comment

Choose a reason for hiding this comment

Uh oh!

justinmc 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!

rkishan516 Sep 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rkishan516 commented Sep 4, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Piinks 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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

rkishan516 Sep 4, 2025 •

edited

Loading