flutter_custom_carousel

The scrollRatio is a value ranging from -1 to +1.

• 0: Represents the settled position of the selected item.
• Negative values: Indicate the item is scrolling towards/from a position before the selection.
• Positive values: Indicate the item is scrolling towards/from a position after the selection.

Specific values depend on your configuration of itemsBefore and itemsAfter.

The widget is primarily designed for touch input. On desktop, scroll wheel input may conflict with the settling scroll physics. To resolve this, you can:

1. Specify different physics (at the cost of snapping).
2. Enable scrolling via mouse dragging by setting a scrollBehavior.

Install the package via pub.dev to use it in your Flutter project.

# Grab it from pub.dev
# (Standard flutter pub add command)
flutter pub add flutter_custom_carousel

To change the launch screen image for the iOS version of your app, you can either replace the image files directly in the example/ios/Runner/Assets.xcassets/LaunchImage.imageset/ directory or use Xcode for a more visual approach.

Using Xcode:

1. Open the iOS project in Xcode by running open ios/Runner.xcworkspace from your terminal.
2. In the Xcode Project Navigator, navigate to Runner/Assets.xcassets.
3. Drag and drop your desired images into the asset catalog to replace the existing launch images.

The example directory contains a complete application demonstrating different implementations of the CustomCarousel widget. To understand specific implementation patterns, refer to the following files in /lib/views/ which contain fully commented code:

• card_deck_view.dart: Demonstrates a card deck style interaction.
• circular_menu_view.dart: Demonstrates a circular menu layout.
• cover_slider_view.dart: Demonstrates a cover slider layout.

The DepthOrder enum determines how items are layered in the Stack within the carousel:

• DepthOrder.forward: Items are displayed in the order they appear in children. Earlier items are drawn behind later items.
• DepthOrder.reverse: Items are displayed in the reverse order. Earlier items are drawn in front of later items.
• DepthOrder.selectedInFront: Items closer to the selected item in the children list are drawn in front of others. The selected item is always in the front.

To create a carousel, pass a list of children and an effectsBuilder function. The effectsBuilder provides the item's index, its current scrollRatio, and the child itself. You use the scrollRatio to apply transformations or animations to the child based on its position in the scroll view.

// very basic example that scrolls children vertically from -250px to +250px
CustomCarousel(
    children: [card1, card2, etc],
    effectsBuilder: (index, scrollRatio, child) =>
       Transform.translate(
            offset: Offset(0, scrollRatio * 250) ,
            child: child
       ),
)

You can integrate the flutter_animate package by using the CustomCarousel.effectsBuilderFromAnimate helper method. This allows you to define complex visual effects (fading, moving, blurs, etc.) using an EffectList that responds to the scroll position.

// very basic example that scrolls children vertically from -250px to +250px
CustomCarousel(
    children: [card1, card2, etc],
    effectsBuilder: CustomCarousel.effectsBuilderFromAnimate(
        effects: EffectList().moveY(begin: -250, end: 250),
    ),
)

By default, the widget uses CustomCarouselScrollPhysics, which enables "settling" (snapping) onto selected items.

You can customize this behavior using:

• sticky: Controls snapping behavior.
• stiffness: Adjusts the physics of the settling animation.

If you do not want snapping behavior, you can provide standard Flutter physics like BouncingScrollPhysics instead.

To enable item-oriented navigation and looping content, you must use CustomCarouselScrollController. This controller provides methods to navigate the carousel programmatically with smart defaults for animation durations and curves.

Key methods include:

• jumpToItem(int index)
• animateToItem(int index)
• nextItem()
• previousItem()

When instantiating CustomCarouselScrollPhysics, you can tune the snapping behavior using the following parameters:

• sticky (bool): If set to true, the scroll "throw" is constrained to advance by no more than a single item (similar to PageView behavior). Note that dragging can still advance through multiple items. Defaults to false.
• stiffness (double): Modifies the stiffness of the spring that controls the settling of the scroll view.
  • Values below 1 provide a looser feel.
  • Values above 1 make it snappier.
  • Recommended range: 0.5 to 5.
  • Defaults to 1.0.

// Example: A snappy, non-sticky physics configuration
const physics = CustomCarouselScrollPhysics(
  sticky: false,
  stiffness: 2.0,
);