CarouselView.builder constructor

const CarouselView.builder({ Key? key, EdgeInsets? padding, Color? backgroundColor, double? elevation, ShapeBorder? shape, Clip? itemClipBehavior, WidgetStateProperty<Color?>? overlayColor, bool itemSnapping = false, double shrinkExtent = 0.0, CarouselController? controller, Axis scrollDirection = Axis.horizontal, bool reverse = false, ValueChanged<int>? onTap, bool enableSplash = true, required double itemExtent, required NullableIndexedWidgetBuilder? itemBuilder, int? itemCount, ValueChanged<int>? onIndexChanged, bool infinite = false, })

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

This constructor allows lazy loading of carousel items. Only items that are visible (or about to be visible) are built, improving performance when dealing with large numbers of items.

The itemBuilder callback will be called only with indices greater than or equal to zero and less than itemCount.

This example shows how to create a carousel with 1000 items using lazy loading:

To see it in action, copy and run this code snippet on DartPad.

import 'package:material_ui/material_ui.dart';

/// Flutter code sample for [CarouselView.builder].

void main() => runApp(const CarouselBuilderExampleApp());

class CarouselBuilderExampleApp extends StatelessWidget {
  const CarouselBuilderExampleApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      home: Scaffold(
        appBar: AppBar(title: const Text('CarouselView.builder Sample')),
        body: const CarouselBuilderExample(),
      ),
    );
  }
}

class CarouselBuilderExample extends StatelessWidget {
  const CarouselBuilderExample({super.key});

  @override
  Widget build(BuildContext context) {
    return Center(
      child: ConstrainedBox(
        constraints: const BoxConstraints(maxHeight: 200),
        child: CarouselView.builder(
          itemExtent: 350,
          itemCount: 1000,
          itemBuilder: (BuildContext context, int index) {
            return ColoredBox(
              color: Colors.primaries[index % Colors.primaries.length],
              child: Center(
                child: Text(
                  'Item $index',
                  style: const TextStyle(
                    color: Colors.white,
                    fontSize: 24,
                    fontWeight: .bold,
                  ),
                ),
              ),
            );
          },
        ),
      ),
    );
  }
}

See also:

• CarouselView.new, which creates a carousel with explicit children.
• CarouselView.weighted, which creates a carousel with weighted items.
• CarouselView.weightedBuilder, which creates a carousel with weighted items using lazy loading.

Implementation

// TODO(framework): Replace the following block with a @dartpad directive
// when it's supported. https://github.com/dart-lang/dartdoc/issues/4123
/// {@macro material_ui.dartpad_guide}
///
/// {@example /example/lib/carousel/carousel.1.dart#body}
///
/// </callout-box>
///
/// See also:
///
///  * [CarouselView.new], which creates a carousel with explicit children.
///  * [CarouselView.weighted], which creates a carousel with weighted items.
///  * [CarouselView.weightedBuilder], which creates a carousel with weighted
///    items using lazy loading.
const CarouselView.builder({
  super.key,
  this.padding,
  this.backgroundColor,
  this.elevation,
  this.shape,
  this.itemClipBehavior,
  this.overlayColor,
  this.itemSnapping = false,
  this.shrinkExtent = 0.0,
  this.controller,
  this.scrollDirection = Axis.horizontal,
  this.reverse = false,
  this.onTap,
  this.enableSplash = true,
  required double this.itemExtent,
  required this.itemBuilder,
  this.itemCount,
  this.onIndexChanged,
  this.infinite = false,
}) : consumeMaxWeight = true,
     flexWeights = null,
     children = const <Widget>[];