timeline_carousel_pakage 1.0.0

A beautiful and customizable timeline carousel widget for Flutter. Display events, milestones, or any data in an elegant timeline format with smooth carousel navigation.

Timeline Carousel

A beautiful and customizable timeline carousel widget for Flutter. Perfect for displaying events, milestones, project timelines, or any chronological data in an elegant and interactive format.

✨ Features

• 📱 Beautiful Design: Modern, clean timeline interface with smooth animations
• 🎨 Highly Customizable: Customize colors, sizes, animations, and layout
• 🔄 Auto-play Support: Optional automatic progression through timeline items
• 🎯 Interactive Navigation: Touch navigation with optional arrow controls
• 📅 Date Support: Built-in date formatting and display
• 🎭 Icon Support: Custom icons and icon widgets for timeline points
• 🎨 Theme Support: Adapts to your app's theme and supports custom styling
• 📱 Responsive: Works great on all screen sizes
• ⚡ Performance: Smooth 60fps animations with optimized rendering

📸 Screenshots

[Add your package screenshots here]

🚀 Getting Started

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  timeline_carousel: ^1.0.0

Then run:

flutter pub get

Import

import 'package:timeline_carousel/timeline_carousel.dart';

📖 Usage

Basic Usage

TimelineCarousel(
  height: 300,
  items: [
    TimelineItem(
      title: "Project Started",
      subtitle: "Initial planning phase",
      dateTime: DateTime(2024, 1, 15),
      child: Text("The project began with extensive research and planning."),
      icon: Icons.play_arrow,
    ),
    TimelineItem(
      title: "Development Phase",
      subtitle: "Core development",
      dateTime: DateTime(2024, 3, 20),
      child: Text("Main development work commenced."),
      icon: Icons.build,
    ),
    TimelineItem(
      title: "Testing & QA",
      subtitle: "Quality assurance",
      dateTime: DateTime(2024, 5, 10),
      child: Text("Comprehensive testing and bug fixes."),
      icon: Icons.bug_report,
    ),
  ],
)

Advanced Usage with Controller

class TimelineExample extends StatefulWidget {
  @override
  _TimelineExampleState createState() => _TimelineExampleState();
}

class _TimelineExampleState extends State<TimelineExample> {
  final TimelineCarouselController _controller = TimelineCarouselController();

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          TimelineCarousel(
            controller: _controller,
            height: 400,
            autoPlay: true,
            autoPlayInterval: Duration(seconds: 4),
            timelineColor: Colors.deepPurple,
            activeDotColor: Colors.deepPurple,
            cardBorderRadius: 16,
            showArrows: true,
            items: _buildTimelineItems(),
            onItemChanged: (index) {
              print("Timeline item changed to: $index");
            },
          ),
          Row(
            mainAxisAlignment: MainAxisAlignment.spaceEvenly,
            children: [
              ElevatedButton(
                onPressed: () => _controller.previous(),
                child: Text("Previous"),
              ),
              ElevatedButton(
                onPressed: () => _controller.next(),
                child: Text("Next"),
              ),
            ],
          ),
        ],
      ),
    );
  }

  List<TimelineItem> _buildTimelineItems() {
    return [
      TimelineItem.image(
        imageUrl: "https://example.com/image1.jpg",
        title: "Beautiful Sunset",
        subtitle: "Captured at the beach",
        dateTime: DateTime.now().subtract(Duration(days: 30)),
        icon: Icons.camera_alt,
      ),
      TimelineItem.text(
        text: "This is a custom text timeline item with rich formatting.",
        title: "Text Content",
        subtitle: "Rich text support",
        dateTime: DateTime.now().subtract(Duration(days: 15)),
        icon: Icons.text_fields,
        textStyle: TextStyle(fontSize: 16, fontStyle: FontStyle.italic),
      ),
    ];
  }
}

Customization Options

TimelineCarousel(
  height: 350,
  items: items,
  
  // Styling
  timelineColor: Colors.blue,
  activeDotColor: Colors.blue,
  inactiveDotColor: Colors.grey,
  backgroundColor: Colors.grey[50],
  cardBorderRadius: 20,
  
  // Layout
  timelineOnRight: false, // Timeline on left by default
  showTimeline: true,
  showArrows: true,
  padding: EdgeInsets.all(20),
  
  // Animation
  animationDuration: Duration(milliseconds: 500),
  animationCurve: Curves.easeInOutCubic,
  
  // Auto-play
  autoPlay: true,
  autoPlayInterval: Duration(seconds: 3),
  
  // Callbacks
  onItemChanged: (index) {
    // Handle item change
  },
)

🎨 TimelineItem Options

Basic Constructor

TimelineItem(
  child: Widget,                    // Required: Main content
  title: String?,                   // Optional: Item title
  subtitle: String?,                // Optional: Item subtitle
  dateTime: DateTime?,              // Optional: Date/time
  icon: IconData?,                  // Optional: Icon
  iconWidget: Widget?,              // Optional: Custom icon widget
  backgroundColor: Color?,          // Optional: Background color
  borderColor: Color?,              // Optional: Border color
  dotColor: Color?,                 // Optional: Timeline dot color
  onTap: VoidCallback?,             // Optional: Tap handler
  tag: String?,                     // Optional: Identifier
)

Factory Constructors

// Text-based item
TimelineItem.text(
  text: "Your text content",
  textStyle: TextStyle(...),
  // ... other parameters
)

// Image-based item
TimelineItem.image(
  imageUrl: "https://example.com/image.jpg",
  height: 200,
  fit: BoxFit.cover,
  // ... other parameters
)

🎛️ Controller Methods

final controller = TimelineCarouselController();

// Navigate to specific index
await controller.animateToIndex(2);

// Navigate to next/previous
await controller.next();
await controller.previous();

// Get current index
int currentIndex = controller.currentIndex;

🎯 Parameters

Parameter	Type	Default	Description
items	List<TimelineItem>	required	List of timeline items to display
controller	TimelineCarouselController?	null	Optional controller for programmatic control
height	double	300	Height of the carousel
showArrows	bool	true	Whether to show navigation arrows
autoPlay	bool	false	Enable automatic progression
autoPlayInterval	Duration	3 seconds	Interval between auto-play transitions
timelineColor	Color	Colors.blue	Color of the timeline line
activeDotColor	Color	Colors.blue	Color of the active timeline dot
inactiveDotColor	Color	Colors.grey	Color of inactive timeline dots
lineThickness	double	2.0	Thickness of the timeline line
dotSize	double	12.0	Size of timeline dots
showTimeline	bool	true	Whether to show the timeline
animationCurve	Curve	Curves.easeInOut	Animation curve for transitions
animationDuration	Duration	300ms	Duration of animations
onItemChanged	ValueChanged<int>?	null	Callback when active item changes
padding	EdgeInsetsGeometry	EdgeInsets.all(16)	Padding around the carousel
backgroundColor	Color?	null	Background color of the carousel
cardBorderRadius	double	12.0	Border radius of timeline cards
cardShadow	List<BoxShadow>?	null	Custom shadow for timeline cards
timelineOnRight	bool	false	Whether timeline should be on the right side

🎨 Examples

Check out the /example folder for complete example applications demonstrating various use cases.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 Changelog

[1.0.0] - 2024-06-04

• Initial release
• Timeline carousel widget with customizable styling
• Auto-play functionality
• Controller support for programmatic navigation
• Multiple timeline item types (text, image, custom)
• Responsive design and smooth animations

📄 License

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

💖 Support

If this package helped you, please ⭐ star the repo and consider supporting the project:

• 👍 Like the package on pub.dev
• 🐛 Report issues on GitHub
• 💡 Request features or improvements

📞 Contact

• GitHub: @aqibtufail7546
• Email: [e-mail]

---

Made with ❤️ for the Flutter community