Infinite Cycle Carousel

A Flutter package containing five reusable carousel widgets. It includes a configurable 2D infinite carousel and specialized cylindrical, overlapping, stacked, and rotatory layouts.

Widget Purpose
InfiniteCarousel General-purpose 2D carousel
CylindricalCarousel 3D carousel arranged around a cylinder
OverlappingCarousel ViewPager-style carousel with overlapping cards
StackedCarousel Finite carousel showing a glimpse of the next card
RotatoryInfiniteCarousel Infinite rotary carousel with depth, drag, and snap

CarouselIndicator is a companion widget, not a separate carousel.

Examples versus implementations

The example app shows nine demonstrations, but the package does not contain nine separate carousel implementations.

Examples 1–5 use the same InfiniteCarousel widget with different options:

Example What changes
Basic autoplay autoPlay: true
Indicator A shared controller and CarouselIndicator
Center enlarged viewportFraction and enlargeCenterPage
Controlled An external controller with next/previous buttons
Vertical scrollDirection: Axis.vertical

Examples 6–9 demonstrate the four specialized carousel widgets.

Installation

Add the package to pubspec.yaml:

dependencies:
  infinite_cycle_carousel: ^1.0.0

Then run:

flutter pub get

Quick start

import 'package:infinite_cycle_carousel/infinite_cycle_carousel.dart';

InfiniteCarousel(
  items: const [
    ColoredBox(color: Colors.red),
    ColoredBox(color: Colors.blue),
    ColoredBox(color: Colors.green),
  ],
  options: const CarouselOptions(
    height: 200,
    viewportFraction: 0.85,
    autoPlay: true,
  ),
)

Indicators

Use the same controller for the carousel and indicator:

final controller = InfiniteCycleCarouselController();

Column(
  children: [
    InfiniteCarousel(
      controller: controller,
      items: items,
      options: const CarouselOptions(height: 200),
    ),
    CarouselIndicator(
      controller: controller,
      itemCount: items.length,
    ),
  ],
)

Enlarged center card

InfiniteCarousel(
  items: items,
  options: const CarouselOptions(
    height: 220,
    viewportFraction: 0.82,
    enlargeCenterPage: true,
    enlargeFactor: 0.25,
  ),
)

Programmatic control

final controller = InfiniteCycleCarouselController();

InfiniteCarousel(
  controller: controller,
  items: items,
  options: CarouselOptions(
    height: 200,
    onPageChanged: (index) => print('Page $index'),
  ),
)

controller.nextPage();
controller.previousPage();
controller.jumpToPage(2);

Vertical direction

InfiniteCarousel(
  items: items,
  options: const CarouselOptions(
    height: 300,
    scrollDirection: Axis.vertical,
  ),
)

Specialized carousels

All builder-based carousels receive a normalized item index.

CylindricalCarousel(
  itemCount: items.length,
  itemBuilder: (context, index) => items[index],
)

OverlappingCarousel(
  itemCount: items.length,
  config: const InfiniteCycleConfig(autoScroll: true),
  itemBuilder: (context, index) => items[index],
)

StackedCarousel(
  itemCount: items.length,
  itemBuilder: (context, index) => items[index],
)

RotatoryInfiniteCarousel(
  itemCount: items.length,
  itemBuilder: (context, index) => items[index],
  onPageChanged: (index) => print('Page $index'),
  onItemTap: (index) => print('Tapped $index'),
)

Important CarouselOptions

Option Default Purpose
height null Fixed carousel height
aspectRatio 16 / 9 Size when height is not supplied
enableInfiniteScroll true Enables continuous scrolling
autoPlay false Advances pages automatically
autoPlayInterval 3 seconds Delay between automatic changes
viewportFraction 1.0 Fraction of the viewport used by a page
enlargeCenterPage false Enlarges the selected page
scrollDirection Axis.horizontal Horizontal or vertical movement
enableTouchInteraction true Enables swipe gestures
onPageChanged null Reports the normalized item index

See CarouselOptions in the API for the complete configuration list.

Compatibility names

The following old names remain temporarily available as deprecated aliases:

  • CycleCarousel → InfiniteCarousel
  • InfiniteCycleCarousel3D → CylindricalCarousel
  • InfiniteCycleViewPager → OverlappingCarousel

New code should use the names on the right.

Run the example

cd example
flutter run

The complete gallery is in example/lib/main.dart.

License

This project is available under the MIT License.