Flutter Route Shifter

A powerful, declarative route transition package with 18+ chainable animations, shared elements, advanced effects, deep linking, responsive animations, theme integration, and go_router support for Flutter applications.

🎥 View Live Animations: See all 17 animation demos on GitHub - GIFs show each transition in action!

---

🎬 Animation Showcase

Fade + Slide	Scale Animation	Sequenced Effects
Glass Morphism	Shared Elements	3D Perspective

---

✨ Features

🎨 Rich Animation Library 18+ Categorized Effects - Organized for easy discovery Modern Widget API - Intuitive widget extension syntax Duration Extensions - Clean 300.ms syntax 3D Transformations - Perspective, shear, and depth effects 🟢 Basic Effects (4) Essential transitions: fade, slide, scale, rotation 🟡 Advanced Effects (7) Professional UX: blur, perspective, sequenced, shared elements

🚀 Advanced Features Widget Extensions - MyWidget().routeShift().fadeIn() Chaining API - Multiple effects in sequence go_router Integration - Seamless support for declarative routing Platform Presets - Material Design & Cupertino styles Performance Optimized - Minimal overhead, smooth 60fps 🆕 v1.1.0 Features 🎨 Theme Integration - Material 3 & Cupertino adaptive animations 📱 Responsive Animations - Screen size & orientation adaptive 🔗 Deep Link Animations - URL-driven animation configuration 📦 Animation Presets - Pre-built combinations for common use cases 🎭 Custom Curve Builder - Visual curve creation with control points 🔴 Creative Effects (7) Artistic transitions: glass morphism, glitch, parallax, clip paths 📦 Clean Architecture Organized exports, tree-shaking friendly, go_router compatible

---

🚀 Quick Start

Installation

dependencies:
  flutter_route_shifter: ^1.1.0

flutter pub get

Basic Usage

import 'package:flutter_route_shifter/flutter_route_shifter.dart';

// Traditional Builder API
final route = RouteShifterBuilder()
  .fade(duration: 300.ms)  // New duration extension!
  .toRoute(page: NextPage());

Navigator.of(context).push(route);

// ✨ NEW: Widget Extension API (Modern chaining style!)
NextPage().routeShift()
  .fade(duration: 300.ms)
  .slide(beginOffset: Offset(1.0, 0.0))
  .scale(beginScale: 0.8)
  .push(context);  // Direct navigation

// ✨ NEW: Chaining with duration extensions
MyWidget().routeShift()
  .fadeIn(500.ms)
  .slideFromRight(400.ms)
  .scaleUp(300.ms)
  .toRoute();

Quick Examples

// Basic animations
LoginPage().routeShift().fadeIn(300.ms).push(context);
ProfilePage().routeShift().slideFromBottom().push(context);
SettingsPage().routeShift().scaleUp().push(context);

// Advanced combinations
DetailPage().routeShift()
  .fade(300.ms)
  .slide(beginOffset: Offset(0.3, 0), duration: 400.ms)
  .blur(beginBlur: 0, endBlur: 10, duration: 200.ms)
  .push(context);

// Creative effects
GalleryPage().routeShift()
  .glass(blur: 20.0, duration: 800.ms)
  .clipPath(clipType: ClipPathType.circle)
  .push(context);

🔗 go_router Integration

Perfect integration with the popular go_router package for declarative routing:

final GoRouter router = GoRouter(
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => HomePage(),
    ),
    GoRoute(
      path: '/details',
      pageBuilder: (context, state) {
        return RouteShifterBuilder()
          .fade(duration: 400.ms)
          .slideFromRight()
          .toPage(child: DetailsPage());
      },
    ),
    GoRoute(
      path: '/profile',
      pageBuilder: (context, state) {
        return RouteShifterBuilder()
          .glass(blur: 20.0, duration: 800.ms)
          .parallax(direction: ParallaxDirection.horizontal)
          .toPage(child: ProfilePage());
      },
    ),
  ],
);

📖 Complete go_router Integration Guide →

---

🆕 New in v1.1.0

🎨 Theme Integration

Automatically adapt animations to your app's Material 3 or Cupertino theme:

// Material 3 theme-aware animations
ProfilePage().routeShift()
  .followMaterial3()  // Uses theme colors & motion
  .fadeIn(300.ms)
  .push(context);

// Cupertino theme integration  
SettingsPage().routeShift()
  .followCupertino()
  .slideFromRight()
  .push(context);

📱 Responsive Animations

Animations that adapt to screen size and orientation:

// Different animations for different screen sizes
DetailPage().routeShift()
  .adaptive(
    mobile: () => slideFromBottom(),
    tablet: () => fade().scale(),
    desktop: () => glass(blur: 15.0),
  )
  .push(context);

// Orientation-aware animations
GalleryPage().routeShift()
  .orientationAdaptive(
    portrait: () => slideFromRight(),
    landscape: () => fade().scale(beginScale: 0.9),
  )
  .push(context);

🔗 Deep Link Animations

Configure animations through URL parameters:

// URL: /profile?animation=slide&duration=400&direction=right
GoRoute(
  path: '/profile',
  pageBuilder: (context, state) {
    return DeepLinkRouteShifter
      .fromUrl(state.uri.toString())
      .toPage(child: ProfilePage());
  },
);

// Preset URLs for common patterns
// URL: /product?preset=ecommerce
GoRoute(
  path: '/product',  
  pageBuilder: (context, state) {
    return DeepLinkRouteShifter
      .fromUrl(state.uri.toString())
      .toPage(child: ProductPage());
  },
);

📦 Animation Presets

Pre-built combinations for common use cases:

// E-commerce optimized animations
ProductPage().routeShift()
  .preset(RouteShifterPresets.ecommerce())
  .push(context);

// Social media style transitions  
FeedPage().routeShift()
  .preset(RouteShifterPresets.socialMedia())
  .push(context);

// Gaming transitions
GamePage().routeShift()
  .preset(RouteShifterPresets.gaming())
  .push(context);

🎭 Custom Curve Builder

Create custom animation curves visually:

// Build custom curves with control points
final customCurve = CustomCurveBuilder()
  .addPoint(0.2, 0.8)  // Control point
  .addSegment(CurveSegmentType.bouncy)
  .build();

DetailPage().routeShift()
  .fade(curve: customCurve)
  .push(context);

---

🎨 Animation Effects

Flutter Route Shifter organizes its 18+ effects into three categories for optimal discoverability:

� Basic Effects - Essential transitions for everyday use

Clean, performant animations that form the foundation of most app transitions.

📱 Fade Transitions

// Basic fade in
RouteShifterBuilder()
  .fade(
    duration: 300.ms,  // New duration extension!
    curve: Curves.easeInOut,
  )

// Fade with opacity control
RouteShifterBuilder()
  .fade(
    beginOpacity: 0.0,
    endOpacity: 1.0,
    duration: 500.ms,
  )

// New Widget Extension API - Modern chaining style!
MyWidget().routeShift()
  .fade(duration: 300.ms)
  .toRoute()

📱 Slide Transitions

// Slide from right
RouteShifterBuilder()
  .slide(
    beginOffset: Offset(1.0, 0.0),
    duration: 300.ms,
  )

// Convenient presets
RouteShifterBuilder().slideFromBottom()
RouteShifterBuilder().slideFromLeft()
RouteShifterBuilder().slideFromTop()

// Widget extension API
MyWidget().routeShift()
  .slideFromRight(duration: 400.ms)

📱 Scale Transitions

// Scale up from center
RouteShifterBuilder()
  .scale(
    beginScale: 0.0,
    endScale: 1.0,
    alignment: Alignment.center,
  )

// Quick presets with new API
MyWidget().routeShift()
  .scaleUp(duration: 250.ms)
  .scaleDown(duration: 250.ms)

� Rotation Transitions

// Rotate on entry
RouteShifterBuilder()
  .rotation(
    beginAngle: -0.5,
    endAngle: 0.0,
    alignment: Alignment.center,
  )

// Full spin effect with new API
MyWidget().routeShift()
  .rotation(beginAngle: -6.28, duration: 400.ms) // 2π rotation

---

🟡 Advanced Effects - Professional animations for enhanced UX

Sophisticated transitions that add depth and interactivity to your app.

🌀 Blur Transitions

// Blur effect
RouteShifterBuilder()
  .blur(
    beginBlur: 0.0,
    endBlur: 10.0,
    duration: 500.ms,
  )

// Widget extension
MyWidget().routeShift()
  .blur(endBlur: 15.0, duration: 600.ms)

🎭 Perspective 3D

// 3D perspective flip
RouteShifterBuilder()
  .perspective(
    rotationX: 0.3,
    rotationY: 0.0,
    distance: 2.0,
    duration: 700.ms,
  )

🎯 Sequenced Animations

// Precise timing control
RouteShifterBuilder()
  .sequenced(
    items: [
      SequencedItem(id: 'header', delay: 0.ms),
      SequencedItem(id: 'content', delay: 200.ms),
      SequencedItem(id: 'footer', delay: 400.ms),
    ],
    staggerDuration: 100.ms,
  )

🔄 Shear Transform

// Shear effect
RouteShifterBuilder()
  .shear(
    beginShear: Offset(0.0, 0.0),
    endShear: Offset(0.2, 0.0),
    duration: 500.ms,
  )

⭐ Shared Elements

// Hero-like shared element transitions
RouteShifterBuilder()
  .sharedElement(
    shiftIds: ['hero-image', 'hero-title'],
    flightDuration: 600.ms,
    flightCurve: Curves.fastLinearToSlowEaseIn,
  )

🌊 Stagger Effects

// Staggered child animations
RouteShifterBuilder()
  .stagger(
    interval: 100.ms,
    childSelector: (index) => index < 5, // First 5 children
    childEffect: SlideEffect(beginOffset: Offset(0, 20)),
  )

⚡ Physics Spring

// Spring physics
RouteShifterBuilder()
  .physicsSpring(
    spring: SpringDescription(
      mass: 1.0,
      stiffness: 500.0,
      damping: 20.0,
    ),
  )

---

🔴 Creative Effects - Experimental and artistic transitions

Eye-catching animations that make your app memorable and unique.

🌟 Glass Morphism

// Glass effect
RouteShifterBuilder()
  .glass(
    blur: 20.0,
    opacity: 0.1,
    duration: 800.ms,
  )

// Widget extension
MyWidget().routeShift()
  .glass(blur: 25.0, opacity: 0.15)

✂️ Clip Path

// Geometric reveal animations
RouteShifterBuilder()
  .clipPath(
    clipType: ClipPathType.circle,
    direction: ClipDirection.centerOut,
    duration: 800.ms,
  )

// Different shapes
MyWidget().routeShift()
  .clipPath(clipType: ClipPathType.diamond)
  .clipPath(clipType: ClipPathType.star)

🎨 Color Tint

// Color overlay transitions
RouteShifterBuilder()
  .colorTint(
    color: Colors.blue.withOpacity(0.3),
    blendMode: BlendMode.overlay,
    duration: 600.ms,
  )

⚡ Glitch Effect

// Digital glitch
RouteShifterBuilder()
  .glitch(
    intensity: 0.1,
    frequency: 8,
    duration: 1000.ms,
  )

🌌 Parallax

// Multi-layer parallax
RouteShifterBuilder()
  .parallax(
    direction: ParallaxDirection.horizontal,
    intensity: 0.5,
    layers: 3,
  )

🛤️ Follow Path

// Custom path animation
RouteShifterBuilder()
  .followPath(
    path: Path()
      ..moveTo(0, 0)
      ..quadraticBezierTo(100, -50, 200, 0),
    duration: 1.2.s,
  )

🎭 Mask Effect

// Mask-based reveals
RouteShifterBuilder()
  .mask(
    maskWidget: Container(
      decoration: BoxDecoration(
        gradient: RadialGradient(colors: [Colors.transparent, Colors.black]),
      ),
    ),
    duration: 800.ms,
  )

---

🔹 Advanced Effects

🌟 Sequenced Animations

// Manual timing control
RouteShifterBuilder()
  .sequenced(
    timings: {
      'header': Duration(milliseconds: 0),
      'content': Duration(milliseconds: 200),
      'footer': Duration(milliseconds: 400),
    },
    baseEffect: SlideEffect(begin: Offset(0, 0.3)),
  )

// Use with SequencedItem widgets
SequencedItem(
  id: 'header',
  child: Text('Animated Header'),
)

---

🔹 Creative Effects

⚡ Glitch Effect

// Digital glitch
RouteShifterBuilder()
  .glitch(
    intensity: 0.5,
    duration: Duration(milliseconds: 600),
  )

⚡ Color Tint

// Color overlay transition
RouteShifterBuilder()
  .colorTint(
    beginColor: Colors.blue.withOpacity(0.8),
    endColor: Colors.transparent,
  )

⚡ Mask Transition

// Mask transition
RouteShifterBuilder()
  .mask(
    shape: MaskShape.circle,
    alignment: Alignment.center,
  )

⚡ Clip Path

// Custom clip transition
RouteShifterBuilder()
  .clipPath(
    clipper: CustomClipPath(),
    duration: Duration(milliseconds: 700),
  )

---

🔹 Platform Presets

📱 Material Design

// Material 3 preset
RouteShifterBuilder()
  .materialPreset(MaterialTransition.slideUp)

// Available Material presets:
// - MaterialTransition.slideUp
// - MaterialTransition.fadeThrough  
// - MaterialTransition.sharedAxis
// - MaterialTransition.container

🍎 Cupertino (iOS)

// iOS-style preset
RouteShifterBuilder()
  .cupertinoPreset(CupertinoTransition.rightToLeft)

// Available Cupertino presets:
// - CupertinoTransition.rightToLeft
// - CupertinoTransition.bottomToTop
// - CupertinoTransition.modalPresent
// - CupertinoTransition.pageReplace

🍎 Cupertino Modal

// iOS modal presentation
RouteShifterBuilder()
  .cupertinoModal(
    presentationStyle: ModalPresentationStyle.pageSheet,
    duration: Duration(milliseconds: 400),
  )

---

🔹 Effect Combinations

🔗 Popular Combinations

// Slide + Fade
RouteShifterBuilder()
  .slideAndFade(
    slideBegin: Offset(1.0, 0.0),
    fadeBegin: 0.0,
  )

// Scale + Fade
RouteShifterBuilder()
  .scaleAndFade(
    scaleBegin: 0.8,
    fadeBegin: 0.0,
  )

// Rotation + Scale
RouteShifterBuilder()
  .rotationAndScale(
    rotationBegin: -0.5,
    scaleBegin: 0.0,
  )

// Complex combination
RouteShifterBuilder()
  .complexTransition(
    slideBegin: Offset(0.0, 1.0),
    scaleBegin: 0.8,
    fadeBegin: 0.0,
    rotationBegin: 0.1,
  )

---

🔧 Advanced Usage

Chaining Multiple Effects

// Chain multiple effects together
final route = RouteShifterBuilder()
  .fade(duration: Duration(milliseconds: 200))
  .slide(beginOffset: Offset(1.0, 0.0))
  .scale(beginScale: 0.8)
  .rotation(beginAngle: 0.1)
  .toRoute(page: NextPage());

Navigator.of(context).push(route);

Custom Timing and Curves

RouteShifterBuilder()
  .fade(
    duration: Duration(milliseconds: 800),
    curve: Curves.elasticOut,
  )
  .slide(
    duration: Duration(milliseconds: 600),
    curve: Curves.fastOutSlowIn,
  )

Interactive Dismiss Gestures

RouteShifterBuilder()
  .fade()
  .slide()
  .enableDismissGesture(
    direction: DismissDirection.horizontal,
    sensitivity: 0.3,
  )

Additional Effects

Click to see more effects

// Blur transitions
RouteShifterBuilder()
  .blur(
    beginSigma: 10.0,
    endSigma: 0.0,
    duration: Duration(milliseconds: 600),
  )

// Parallax effect
RouteShifterBuilder()
  .parallax(
    offset: Offset(0.0, 0.5),
    intensity: 0.7,
  )

// Follow path animation
RouteShifterBuilder()
  .followPath(
    path: customPath,
    duration: Duration(milliseconds: 1000),
  )

// Spring physics
RouteShifterBuilder()
  .spring(
    mass: 1.0,
    stiffness: 100.0,
    damping: 10.0,
  )

---

🎯 Performance Tips

• ✅ Use const constructors where possible
• ✅ Prefer shorter animation durations for better UX (200-400ms)
• ✅ Combine related effects rather than chaining many separate ones
• ✅ Use builder patterns for complex animations
• ✅ Test on lower-end devices to ensure smooth performance

---

📱 Platform Support

Platform	Version	Status
🤖 Android	API 16+	✅ Fully Supported
🍎 iOS	9.0+	✅ Fully Supported
🌐 Web	Modern Browsers	✅ Fully Supported
🖥️ macOS	10.11+	✅ Fully Supported
🪟 Windows	7+	✅ Fully Supported
🐧 Linux	All Distros	✅ Fully Supported

---

🤝 Contributing

We welcome contributions! Here's how you can help:

1. 🐛 Report Bugs - Found an issue? Create an issue
2. 💡 Suggest Features - Have an idea? We'd love to hear it!
3. 📝 Improve Documentation - Help make our docs better
4. 🔧 Submit Pull Requests - Read our Contributing Guide

---

📄 License

This project is licensed under the BSD 3-Clause License - see the LICENSE file for details.

---

🙏 Acknowledgments

• 💙 Flutter Team - For the incredible framework
• 🌟 Community Contributors - Thank you for your support and feedback
• 🎨 Design Inspiration - Various animation libraries and design systems

---

Made with ❤️ for the Flutter community

⭐ Star us on GitHub | 📦 View on pub.dev | 📚 Documentation