CarouselView class

A Material Design carousel widget.

The CarouselView presents a scrollable list of items, each of which can dynamically change size based on the chosen layout.

Material Design 3 introduced 4 carousel layouts:

• Multi-browse: This layout shows at least one large, medium, and small carousel item at a time. This layout is supported by CarouselView.weighted.
• Uncontained (default): This layout show items that scroll to the edge of the container. This layout is supported by CarouselView.
• Hero: This layout shows at least one large and one small item at a time. This layout is supported by CarouselView.weighted.
• Full-screen: This layout shows one edge-to-edge large item at a time and scrolls vertically. The full-screen layout can be supported by both constructors.

The default constructor implements the uncontained layout model. It shows items that scroll to the edge of the container, behaving similarly to a ListView where all children are a uniform size. CarouselView.weighted enables dynamic item sizing. Each item is assigned a weight that determines the portion of the viewport it occupies. This constructor helps to create layouts like multi-browse, and hero. In order to have a full-screen layout, if CarouselView is used, then set the itemExtent to screen size; if CarouselView.weighted is used, then set the flexWeights to only have one integer in the array.

Scaffold(
  body: CarouselView(
    scrollDirection: Axis.vertical,
    itemExtent: double.infinity,
    children: List<Widget>.generate(10, (int index) {
      return Center(child: Text('Item $index'));
    }),
  ),
),

// ...

Scaffold(
  body: CarouselView.weighted(
    scrollDirection: Axis.vertical,
    flexWeights: const <int>[1], // Or any positive integers as long as the length of the array is 1.
    children: List<Widget>.generate(10, (int index) {
      return Center(child: Text('Item $index'));
    }),
  ),
),

In CarouselView.weighted, weights are relative proportions. For example, if the layout weights is [3, 2, 1], it means the first visible item occupies 3/6 of the viewport; the second visible item occupies 2/6 of the viewport; the last visible item occupies 1/6 of the viewport. As the carousel scrolls, the size of the latter one gradually changes to the size of the former one. As a result, when the first visible item is completely off-screen, the following items will follow the same layout as before. Using CarouselView.weighted helps build the multi-browse, hero, center-aligned hero and full-screen layouts, as indicated in Carousel sepcs.

The CarouselController is used to control the CarouselController.initialItem, which determines the first fully expanded item when the CarouselView or CarouselView.weighted is initially displayed. This is straightforward for CarouselView because each item in the view has fixed size. In CarouselView.weighted, for instance, if the layout weights are [1, 2, 3, 2, 1] and the initial item is 4 (the fourth item), the view will display items 2, 3, 4, 5, and 6 with weights 1, 2, 3, 2 and 1 respectively.

The CarouselView.itemExtent property must be non-null and defines the base size of items. While items typically maintain this size, the first and last visible items may be slightly compressed during scrolling. The shrinkExtent property controls the minimum allowable size for these compressed items.

See also:

• CarouselController, which controls the first fully visible item in the view.
• PageView, which is a scrollable list that works page by page.