fancy_stack_carousel

A highly customizable and animated stack carousel widget for Flutter, allowing for dynamic card transformations, autoplay, and programmatic control.

Showcases

✨ Features

Animated Stack Effect: Cards are stacked and transform elegantly as the user navigates.
Customizable Transforms: Control scale, rotation (Z and Y axis for 3D perspective), and translation of individual cards based on their position.
Autoplay Functionality:
- Enable or disable automatic sliding of cards.
- Set custom autoplay intervals and animation durations.
- Control autoplay direction (left, right, or alternating).
- Pause autoplay on user interaction (touch/drag) or mouse hover.
Programmatic Control: Use FancyStackCarouselController to navigate to the next or previous card.
Page Change Callbacks: Get notified when the central card changes, including the reason (timed, gesture, controller) and autoplay direction.
Flexible Item Definition: Define carousel items with unique IDs and custom child widgets.

📦 Installation

Add the following to your pubspec.yaml file:

dependencies:
  fancy_stack_carousel: ^latest_version # Replace with the actual latest version

Then, run flutter pub get in your terminal.

📚 How to Use

The fancy_stack_carousel package is designed to be straightforward to integrate into your Flutter application. Here's a step-by-step guide:

1. Import the Package

First, ensure you have added the dependency as described in the Installation section. Then, import the main package file in your Dart code:

import 'package:fancy_stack_carousel/fancy_stack_carousel.dart';

2. Create `FancyStackItem`s

Each slide or "card" in your carousel is represented by a FancyStackItem. You'll need a list of these items. Each FancyStackItem requires a unique id and a child widget, which is the actual content of your card.

List<FancyStackItem> carouselItems = [
  FancyStackItem(
    id: 1,
    child: Container(
      color: Colors.red,
      alignment: Alignment.center,
      child: const Text('Card 1', style: TextStyle(color: Colors.white, fontSize: 24)),
    ),
  ),
  FancyStackItem(
    id: 2,
    child: Container(
      color: Colors.green,
      alignment: Alignment.center,
      child: const Text('Card 2', style: TextStyle(color: Colors.white, fontSize: 24)),
    ),
  ),
  // Add more FancyStackItem instances as needed
];

3. Configure `FancyStackCarouselOptions`

The FancyStackCarouselOptions class allows you to customize the behavior and appearance of your carousel. The size property is required to define the dimensions of your carousel.

FancyStackCarouselOptions options = FancyStackCarouselOptions(
  size: const Size(280, 350), // Set the desired width and height
  autoPlay: true, // Enable autoplay
  autoPlayInterval: const Duration(seconds: 3),
  autoplayDirection: AutoplayDirection.bothSide, // Autoplay alternates directions
  onPageChanged: (index, reason, direction) {
    // Optional: Callback when the page changes
    debugPrint('Page changed to index: $index, Reason: $reason, Direction: $direction');
  },
  pauseAutoPlayOnTouch: true, // Pause autoplay when user interacts
  pauseOnMouseHover: true, // Pause autoplay on mouse hover
);

4. Use `FancyStackCarouselController` (Optional, for Programmatic Control)

If you need to control the carousel programmatically (e.g., with "Next" and "Previous" buttons), create an instance of FancyStackCarouselController and pass it to the FancyStackCarousel widget.

final FancyStackCarouselController _carouselController = FancyStackCarouselController();

// To move to the next card:
_carouselController.animateToRight();

// To move to the previous card:
_carouselController.animateToLeft();

// To toggle autoplay programmatically (e.g., from a button):
_carouselController.setAutoplay(newValue);

5. Integrate `FancyStackCarousel` into Your Widget Tree

Finally, place the FancyStackCarousel widget in your build method. Pass your list of items and your options object. If you're using programmatic control, also pass your carouselController.

FancyStackCarousel(
  items: carouselItems,
  options: options,
  carouselController: _carouselController, // Optional
),

Full Example Structure

Combining all the above, a typical implementation within a StatefulWidget would look like the example provided in the Usage section.