Flutter Parallax Scroll

A Flutter package for creating beautiful parallax scrolling effects with customizable speed and direction.

Features

• 🎯 Customizable Speed: Control the intensity of parallax effects (0.0 to 2.0)
• 🧭 Multiple Directions: Horizontal, vertical, and diagonal parallax effects with reverse option
• 🎮 Easy Integration: Simple API with extension methods for quick implementation
• 📱 Performance Optimized: Efficient scroll detection and smooth animations
• 🎨 Flexible Configuration: Fine-tune every aspect of the parallax behavior

Installation

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

dependencies:
  flutter_parallax_scroll: ^0.1.0

Then run:

flutter pub get

Quick Start

Basic Usage

import 'package:flutter_parallax_scroll/flutter_parallax_scroll.dart';

class MyHomePage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: ParallaxScrollView(
        child: ListView(
          children: [
            // Your content with parallax effects
            Container(
              height: 200,
              color: Colors.blue,
            ).asParallaxItem(
              config: ParallaxConfig(
                speed: 0.5,
                direction: ParallaxDirection.vertical,
              ),
            ),
          ],
        ),
      ),
    );
  }
}

Using Extension Methods

ListView(
  children: [
    // Apply parallax to any widget
    Image.asset('assets/background.jpg').asParallaxItem(
      config: ParallaxConfig(
        speed: 0.3,
        direction: ParallaxDirection.vertical,
        reverse: true,
      ),
    ),
    
    // Wrap scrollable content
    SingleChildScrollView().withParallax(
      config: ParallaxConfig(
        speed: 1.0,
        direction: ParallaxDirection.vertical,
      ),
    ),
  ],
)

API Reference

ParallaxConfig

Configuration class for parallax effects:

ParallaxConfig({
  double speed = 1.0,                    // Speed multiplier (0.0 to 2.0)
  ParallaxDirection direction = ParallaxDirection.horizontal,
  bool reverse = false,                   // Reverse the direction
  bool enabled = true,                   // Enable/disable effect
  Offset offset = Offset.zero,           // Additional offset
})

ParallaxDirection

Available parallax directions:

• ParallaxDirection.horizontal - Moves horizontally (left to right by default, right to left when reversed)
• ParallaxDirection.vertical - Moves vertically (up to down by default, down to up when reversed)
• ParallaxDirection.diagonal - Moves diagonally (top-left to bottom-right by default, bottom-right to top-left when reversed)

Use the reverse property in ParallaxConfig to reverse any direction.

ParallaxScrollView

Main widget for wrapping scrollable content:

ParallaxScrollView({
  required Widget child,
  ParallaxConfig config = const ParallaxConfig(),
  ParallaxScrollController? controller,
  bool enableScrollDirection = true,
  bool enableScrollState = true,
})

ParallaxScrollItem

Widget for applying parallax effects to individual items:

ParallaxScrollItem({
  required Widget child,
  ParallaxConfig config = const ParallaxConfig(),
  ParallaxScrollController? controller,
  bool horizontal = true,
  bool vertical = true,
})

ParallaxScrollController

Controller for managing parallax state:

final controller = ParallaxScrollController();

// Update configuration
controller.updateConfig(ParallaxConfig(speed: 1.5));

// Reset state
controller.reset();

Examples

Hero Section with Parallax Background

Container(
  height: 400,
  child: const Stack(
    children: [
      // Parallax background
      Positioned.fill(
        child: Image.asset(
          'assets/hero-bg.jpg',
          fit: BoxFit.cover,
        ).asParallaxItem(
          config: ParallaxConfig(
            speed: 0.3,
            direction: ParallaxDirection.vertical,
            reverse: true,
          ),
        ),
      ),
      
      // Content
      Center(
        child: Text(
          'Welcome',
          style: TextStyle(
            fontSize: 48,
            color: Colors.white,
            fontWeight: FontWeight.bold,
          ),
        ),
      ),
    ],
  ),
)

Multiple Parallax Layers

ListView(
  children: [
    // Background layer (slowest)
    Container(
      height: 300,
      child: Image.asset('assets/bg.jpg').asParallaxItem(
        config: ParallaxConfig(speed: 0.2),
      ),
    ),
    
    // Middle layer (medium speed)
    Container(
      height: 200,
      child: Image.asset('assets/middle.png').asParallaxItem(
        config: ParallaxConfig(speed: 0.5),
      ),
    ),
    
    // Foreground layer (fastest)
    Container(
      height: 150,
      child: Image.asset('assets/foreground.png').asParallaxItem(
        config: ParallaxConfig(speed: 0.8),
      ),
    ),
  ],
)

Horizontal Parallax

SingleChildScrollView(
  scrollDirection: Axis.horizontal,
  child: Row(
    children: [
      Container(
        width: 200,
        height: 300,
        color: Colors.red,
      ).asParallaxItem(
        config: ParallaxConfig(
          speed: 0.5,
          direction: ParallaxDirection.horizontal,
        ),
      ),
      // More items...
    ],
  ),
).withParallax()

Performance Tips

1. Use appropriate speeds: Lower speeds (0.1-0.5) work well for backgrounds, higher speeds (0.8-1.2) for foreground elements
2. Limit parallax items: Don't apply parallax to too many widgets simultaneously
3. Disable when not needed: Use enabled: false to disable effects when not visible
4. Optimize images: Use appropriately sized images for parallax backgrounds

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

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