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→InfiniteCarouselInfiniteCycleCarousel3D→CylindricalCarouselInfiniteCycleViewPager→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.