infinite_cycle_carousel 1.0.0

Flutter package with configurable infinite, cylindrical, overlapping, stacked, and rotatory carousel widgets.

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.

Carousel widgets

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,
  ),
)

Infinite carousel recipes

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.