CurvedListWheel brings a dynamic and engaging user experience to your app, perfect for pickers, onboarding screens, and showcasing items in a visually appealing way. It supports vertical/horizontal scrolling, infinite loops, and gives you full control over item styling based on their position.

✨ Demos #

📚 Table of Contents #

• Features
• Installation
• Quick Start: Basic Usage
• Deep Dive: Customization
  • ⚙️ Wheel Geometry & Feel (CurvedListWheelSettings)
  • 🎨 Styling Items (itemBuilder & CurvedListItemState)
    • Using CurvedListWheelTextItem Helper
    • Building Custom Widgets
  • ↔️ Scroll Direction & Curve Side (CurvedListWheelSide)
  • 🔁 Infinite Scrolling
  • 🕹️ Programmatic Control (FixedExtentScrollController)
• 🚀 Advanced Example Showcase
• API Reference
• Contributing
• License

🌟 Features #

• Beautiful Curved Path Scrolling: Items animate along a quadratic Bézier curve.
• Multi-Axis Support: Configure the curve on the left, right, top, or bottom.
• State-Driven UI: itemBuilder provides CurvedListItemState (isSelected, distance) for powerful conditional styling and animations.
• Infinite Scrolling: Loop the list indefinitely for continuous picking.
• Rich Customization: Use CurvedListWheelSettings to control item extent, curve tightness, highlight box, and more.
• Helper Widgets: Includes CurvedListWheelTextItem and CurvedListWheelTextStyle for effortless, distance-based text styling.
• Controller Support: Natively works with FixedExtentScrollController for programmatic control.
• Highly Performant: Built on top of Flutter's efficient ListWheelScrollView.

📦 Installation #

Add the package to your pubspec.yaml file:

dependencies:
  curved_list_wheel: ^1.0.0 # Check pub.dev for the latest version

Then, install it by running the command in your terminal:

flutter pub get

🚀 Quick Start: Basic Usage #

Import the package and create a simple CurvedListWheel with a list of strings.

import 'package:flutter/material.dart';
import 'package:curved_list_wheel/curved_list_wheel.dart';

class PlanetPicker extends StatefulWidget {
  @override
  _PlanetPickerState createState() => _PlanetPickerState();
}

class _PlanetPickerState extends State<PlanetPicker> {
  final _items = ['Mercury', 'Venus', 'Earth', 'Mars', 'Jupiter'];
  int _selectedIndex = 2;

  @override
  Widget build(BuildContext context) {
    return CurvedListWheel<String>(
      items: _items,
      initialItem: _selectedIndex,
      onSelectedItemChanged: (index) {
        setState(() {
          _selectedIndex = index;
        });
      },
      // The itemBuilder provides state information for dynamic styling.
      itemBuilder: (context, index, item, itemState) {
        // Use the helper for easy, beautiful text styling.
        return CurvedListWheelTextItem(
          text: item,
          itemState: itemState,
          style: const CurvedListWheelTextStyle(),
        );
      },
    );
  }
}

🛠️ Deep Dive: Customization #

Unlock the full potential of CurvedListWheel by customizing its appearance and behavior.

⚙️ Wheel Geometry & Feel (CurvedListWheelSettings) #

The settings property lets you control the core mechanics of the wheel.

final settings = CurvedListWheelSettings(
    // The height of each item in the list.
    itemExtent: 80.0,
    // A larger value creates a more pronounced curve.
    pathCurveFactor: 0.8,
    // Show or hide the central highlight box.
    showHighlight: true,
    highlightColor: Colors.deepPurple.withAlpha(50),
    // For vertical lists, this is a fraction of the available width.
    highlightWidthFactor: 0.7,
    highlightBorderRadius: BorderRadius.circular(16),
);

CurvedListWheel(
    // ...
    settings: settings,
);

🎨 Styling Items (itemBuilder & CurvedListItemState) #

This is the most powerful feature. The itemBuilder gives you CurvedListItemState, which contains:

• bool isSelected: true if the item is in the center.
• int distance: The absolute distance from the selected item (0 for selected, 1 for immediate neighbors, etc.).

Using CurvedListWheelTextItem Helper

For text wheels, this is the easiest way to get great results. CurvedListWheelTextStyle allows you to define styles for different states.

const textStyle = CurvedListWheelTextStyle(
  // Style for the centered item
  selectedStyle: TextStyle(
    fontSize: 24,
    fontWeight: FontWeight.bold,
    color: Colors.deepPurple,
  ),
  // Default style for all other items
  unselectedStyle: TextStyle(
    fontSize: 18,
    color: Colors.black54,
  ),
  // Override styles for items at a specific distance from the center
  distanceSpecificStyles: {
    1: TextStyle(fontSize: 22, color: Colors.black87, fontWeight: FontWeight.w600),
    2: TextStyle(fontSize: 20, color: Colors.black45),
  },
);

// Inside itemBuilder:
return CurvedListWheelTextItem(
    text: item,
    itemState: itemState,
    style: textStyle,
);

Building Custom Widgets

You are not limited to text. Build any widget you want and use itemState to apply conditional styling.

// Inside itemBuilder:
return AnimatedOpacity(
  duration: const Duration(milliseconds: 200),
  opacity: itemState.isSelected ? 1.0 : 0.4,
  child: AnimatedScale(
    duration: const Duration(milliseconds: 200),
    scale: itemState.isSelected ? 1.0 : 0.7,
    child: MyCustomPlanetWidget(itemData: item),
  ),
);

↔️ Scroll Direction & Curve Side (CurvedListWheelSide) #

Control the scroll direction and where the curve appears using the side property.

• CurvedListWheelSide.left (Default): Vertical scroll, curve on the left.
• CurvedListWheelSide.right: Vertical scroll, curve on the right.
• CurvedListWheelSide.top: Horizontal scroll, curve on the top.
• CurvedListWheelSide.bottom: Horizontal scroll, curve on the bottom.

CurvedListWheel(
  // ...
  side: CurvedListWheelSide.right,
);

🔁 Infinite Scrolling #

Set isInfinite: true to create a list that wraps around seamlessly. This is perfect for pickers like a birth year selector.

CurvedListWheel(
  // ...
  isInfinite: true,
);

🕹️ Programmatic Control (FixedExtentScrollController) #

Pass your own FixedExtentScrollController to control the wheel programmatically.

// In your State class
final _scrollController = FixedExtentScrollController(initialItem: 10);

// In your build method
CurvedListWheel(
  // ...
  controller: _scrollController,
);

// Later, to jump to an item:
_scrollController.animateToItem(
  20,
  duration: const Duration(milliseconds: 500),
  curve: Curves.easeInOut,
);

🚀 Advanced Example Showcase #

By combining the features of CurvedListWheel with other Flutter widgets, you can create stunning and responsive UIs like our advanced onboarding example.

This screen demonstrates:

• isInfinite: true for the year picker.
• Custom CurvedListWheelTextStyle for responsive font sizes.
• FixedExtentScrollController to listen to scroll offsets.
• Combining with other animated widgets, like the rotating background pattern whose rotation is tied to the scroll offset.
• A fully responsive layout that adapts to different screen sizes.

📝 API Reference #

❤️ Contributing #

Contributions are welcome! If you find a bug or have a feature request, please file an issue. If you want to contribute code, please open a pull request.

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

📜 License #

This project is licensed under the MIT License - see the LICENSE file for details.