Coverflow Carousel

A beautiful, highly customizable 3D coverflow-style carousel for Flutter.

Create immersive experiences with smooth perspective effects, overlapping cards, dynamic scaling, and effortless programmatic navigation.

Perfect for music apps, movie browsers, ecommerce showcases, galleries, portfolios, and modern mobile interfaces.

---

Features

🎬 Visuals & 3D Perspective	🛠️ Customization & Builders
Smooth 3D Coverflow DesignImmersive carousel layout with customizable 3D perspective, skew angles, and depth scaling.	Center Card OverlaysStack play buttons, badges, or details directly on the centered card with distance-linked fade transitions.
Layouts & Infinite LoopHorizontal or vertical scroll directions with properly oriented 3D transforms and seamless circular looping.	Fully Adjustable SpacingSet custom overlap parameters, near/far card spacing, viewport fractions, and visible card counts.
Dynamic Entry AnimationsStaggered fades, zoom scales, spacing expansions (horizontal fanning), sliding, and physical stacking effects.	Custom DimensionsSupport for explicit card width and height constraints.
Depth, Shadows & BlurReal-time drop shadow calculations, customizable elevation, and blur/obscure effects for off-center cards.	Builder-Based APIOn-demand widget creation optimizes rendering performance for large or infinite datasets.
🎮 Interactions & Input	⚡ Performance & Controller
3D Hover & Tilt EffectsInteractive pointer-tracking that tilts cards in 3D space with customizable angles and smooth deceleration.	Programmatic navigation (, , ) paired with real-time stream/notifier scroll updates.

Preview

[!NOTE] This is a demo of an application of this package. You can download the example app from the github repo to test all the features.

---

Installation

Add the package to your pubspec.yaml.

dependencies:
  coverflow_carousel: ^2.0.1

OR

Run the command in the terminal in your project root

flutter pub add coverflow_carousel

Then run:

flutter pub get

Basic Usage

[!IMPORTANT] API Change in v2.0.0: The scrollDirection parameter is now required (compulsory) in the CoverflowCarousel.builder constructor to make layout orientation explicit.

CoverflowCarousel.builder(
    itemCount: 10,
    itemWidth: 250,
    itemHeight: 320,
    scrollDirection: Axis.horizontal,
    itemBuilder: (context, index) {
        return Container(
            decoration: BoxDecoration(
                borderRadius: BorderRadius.circular(24),
                color: Colors.blue,
            ),
        );
    },
)

Controller Support

Control the carousel from anywhere in your application.

final controller = CoverflowCarouselController();

CoverflowCarousel.builder(
  controller: controller,
  itemCount: items.length,
  itemWidth: 250,
  itemHeight: 320,
  scrollDirection: Axis.horizontal,
  itemBuilder: (context, index) {
    return MyCard(index: index);
  },
)

Programmatic Navigation

controller.next();
controller.previous();
controller.animateTo(5);

Listen to Scroll Progress

You can listen to real-time scroll updates (for custom page indicators, ambient colors, animations, etc.) using streams or value notifiers:

// Notifiers (synchronous value updates)
controller.pageListenable.addListener(() {
  double currentPage = controller.page; // Normalized index in [0, itemCount)
});

controller.rawPageListenable.addListener(() {
  double rawPage = controller.rawPage; // Raw PageController values
});

// Broadcast Streams
controller.pageStream.listen((double normalizedPage) {
  // Triggers on every fractional scroll update
});

controller.rawPageStream.listen((double rawPage) {
  // Triggers on every raw scroll update
});

Make sure to call controller.dispose() when the controller is no longer needed to clean up stream subscriptions.

[!TIP] Performance Tip: For lightweight, synchronous UI bindings (e.g. customized page indicators), prefer using controller.pageListenable or controller.rawPageListenable to avoid the asynchronous overhead of streams.

Entry Animations

Make the carousel feel organic and alive when it first appears on the screen. Select from staggered fades, zoom scaling, spacing expansions, or horizontal slides.

CoverflowCarousel.builder(
  itemCount: items.length,
  itemWidth: 250,
  itemHeight: 320,
  scrollDirection: Axis.horizontal,
  entryAnimation: CoverflowEntryAnimation.stack, // Physical stacking effect fanning center-out!
  entryAnimationDuration: const Duration(milliseconds: 1000),
  entryAnimationCurve: Curves.easeOutCubic,
  itemBuilder: (context, index) {
    return MyCard(index: index);
  },
)

Available Animation Types:

• CoverflowEntryAnimation.none (Default): Instantly mounts without animation.
• CoverflowEntryAnimation.fadeIn: Staggered opacity fade-in from the center outward.
• CoverflowEntryAnimation.scaleUp: Staggered zoom scale-up from the center outward.
• CoverflowEntryAnimation.spacingExpand: Cards fan out horizontally from a center stack.
• CoverflowEntryAnimation.staggeredSlide: Staggered slides in from left/right/top.
• CoverflowEntryAnimation.fadeScale: Smooth staggered zoom and fade combined.
• CoverflowEntryAnimation.stack: Physical stacking effect where cards scale down from the front fanning center-to-outside.

---

Center Card Overlay

Stack custom widgets (like play buttons, badges, overlays) directly on the active centered card. Overlays automatically fade out smoothly as the card moves away from the center.

CoverflowCarousel.builder(
  itemCount: items.length,
  itemWidth: 250,
  itemHeight: 320,
  scrollDirection: Axis.horizontal,
  centerOverlayBuilder: (context, index) {
    return Positioned(
      bottom: 20,
      right: 20,
      child: FloatingActionButton(
        onPressed: () => print("Playing $index"),
        child: Icon(Icons.play_arrow),
      ),
    );
  },
  itemBuilder: (context, index) => MyCard(index: index),
)

3D Hover/Tilt Effect

Bring your carousel to life on web and desktop. The focused card tilts in 3D space tracking the user's mouse movements. When the mouse leaves, the card smoothly decelerates back to center.

Configure tilt support with:

• enableHoverTilt: Whether to enable 3D hover/tilt effects on the center card (defaults to true).
• maxHoverTiltAngle: The maximum rotation angle in radians (defaults to 0.15, approximately 8.5 degrees).

Mouse Scroll Wheel Navigation

Support scroll wheel and trackpad swipe movements to change pages. Navigation requests are automatically throttled relative to the transition animation duration to guarantee smooth transitions.

---

Parameters

Parameter	Type	Description
itemCount	int	Number of carousel items
itemBuilder	IndexedWidgetBuilder	Builds each carousel item
itemWidth	double	Width of the focused card
itemHeight	double	Height of the focused card
scrollDirection	Axis	Scroll direction (compulsory: Axis.horizontal or Axis.vertical)
visibleItems	int	Number of visible cards on each side of focused item (default: 3)
initialPage	int	Initial focused page index (default: 0)
nearCardSpacing	double	Spacing for adjacent cards (default: 45)
farCardSpacing	double	Spacing for distant cards (default: 50)
skewAngle	double	Card rotation angle (default: -0.35 for coverflow, 0.0 for classic)
perspective	double	3D perspective intensity (default: 0.0025)
obscure	double	Blur intensity for side cards (default: 0)
controller	CoverflowCarouselController?	External carousel controller
animationDuration	Duration	Navigation animation duration (default: 350ms)
animationCurve