flutter_motion_kit 🚀

A centralized, production-grade Flutter animation and loader library powered by GetX. Exposes premium loaders, custom-painted skeletons, frosted glassmorphism containers, 3D pointer-tracking cards, liquid-swipe page transitions, and interactive particle background effects under a single unified API.

Designed for high-performance (smooth 60fps/120fps), complete accessibility compliance (vestibular reduce-motion triggers), and absolute ease-of-use.

---

🌟 Key Features

• 🎯 One-Stop Animation Library — Install ONLY ONE package to fulfill all animation, loader, and visual effect needs.
• ⚡ 60fps Production Performance — Highly optimized rendering utilizing RepaintBoundary wrappers and strict ticker management.
• ♿ Full Accessibility Compliance — Integrated dynamic fallbacks supporting device-level "Reduce Motion" system configurations.
• 🎨 Dynamic Theme Presets — Fluid switching between Cyberpunk, Midnight Gold, Light/Dark Modes, and customized neon gradient borders.
• 🌊 Advanced Custom Page Transitions — Build highly custom routes including Shared Axis slides and fluid Liquid Swipes.
• 📦 Zero Boilerplate API — Simple, developer-friendly interfaces designed for maximum customization.

---

🛠️ Installation

Add flutter_motion_kit to your pubspec.yaml:

dependencies:
  flutter_motion_kit: ^1.0.0

---

🚀 Quickstart

1. Initialize the Engine — Initialize the centralized state managers inside your main.dart entry point:

   import 'package:flutter/material.dart';
   import 'package:flutter_motion_kit/flutter_motion_kit.dart';
   
   void main() async {
     WidgetsFlutterBinding.ensureInitialized();
   
     // Auto-registers accessibility, performance, and theme controllers
     await MotionConfigService.init();
   
     runApp(const MyApp());
   }
   

2. Mount the App — Wrap your MaterialApp in an Obx container to enjoy real-time neon dynamic theme switches:

   class MyApp extends StatelessWidget {
     const MyApp({super.key});
   
     @override
     Widget build(BuildContext context) {
       final themeController = Get.find<MotionThemeController>();
   
       return Obx(() {
         return MaterialApp(
           title: 'Motion App',
           theme: themeController.theme.toThemeData(),
           home: const MyDashboard(),
         );
       });
     }
   }
   

---

📐 API Showcase & Component Dictionary

Here is the complete reference dictionary covering each and every widget available in flutter_motion_kit along with their key parameters, descriptions, copy-pasteable usage examples, and their visual GIF asset paths.

---

📂 Table of Contents

1. App-wide Services & Custom Themes
2. Interactive Background Shaders
3. Ecosystem Loaders (Standard & Advanced Categories)
4. Interactive Action Controls
5. Micro-Interactions
6. Cards, Morphings, Glass & Placeholders
7. Custom Route Transitions

---

1. App-wide Services & Custom Themes

MotionConfigService

• Description: Static engine initialization service. Registers global MotionController and MotionThemeController to handle user-toggled settings like Speed Multipliers, Reduced Motion overrides, Performance Mode blurs, and presets.
• Usage:

  await MotionConfigService.init();
  

MotionTheme

• Description: Scope injector for retrieving the active cyberpunk or midnight gold neon themes. Provides dynamic colors and Typography definitions inside the widget tree.
• Usage:

  final activeTheme = MotionTheme.of(context);
  Color neonColor = activeTheme.primaryColor;
  

---

2. Interactive Background Shaders

MotionAuroraBackground

• Visual Preview:
• Description: A high-end background layer that renders floating, multi-colored liquid aurora gaseous meshes. Animates dynamically utilizing high-performance sinus shaders with low CPU load.
• Usage:

  MotionAuroraBackground(
    child: Center(
      child: Text('Floating on gaseous lights'),
    ),
  )
  

• Parameters:
  • child: Nested overlay content widgets (optional).

MotionParticleBackground

• Visual Preview:
• Description: A live particle physics field. Particles float, bounce, and drift randomly. Interactive tap inputs act as gravity points, drawing particles in before dispersing them outward.
• Usage:

  MotionParticleBackground(
    particleColor: Colors.cyanAccent.withValues(alpha:0.4),
    child: const Text('Interactive particle field'),
  )
  

• Parameters:
  • particleColor: Color override for drifting particles (default: primaryNeon).
  • child: Nested overlay content widgets.

---

3. Ecosystem Loaders

All 11 loaders can be resolved dynamically via the unified MotionLoader router or instantiated individually. They automatically adapt sizes and margins to prevent layout overflows and respect global speed settings.

MotionLoader (Unified Router)

• Visual Preview:
• Description: Centralized loading dispatcher. Resolves and returns any of the 11 loader types based on the MotionLoaderType enum.
• Usage:

  MotionLoader(
    type: MotionLoaderType.ai,
    color: Colors.purpleAccent,
    size: 48.0,
  )
  

• Parameters:
  • type: Preset loader to use (dots, typing, pulse, orbit, dna, ai, liquid, wave, futuristic, matrix, gradientRotating).
  • color: Loading graphic color.
  • size: Bounding box dimensions (width & height).
  • strokeWidth: Line stroke dimensions where applicable.

📦 Standard Loaders Grid

Exposes 11 standard high-performance loader presets. You can instantiate them directly (e.g. MotionDotsLoader(...)) or through the unified MotionLoader(type: MotionLoaderType.dots, ...) constructor.

standard/dots.gif	standard/typing.gif	standard/pulse.gif
Dots MotionDotsLoader	Typing MotionTypingIndicator	Pulse MotionPulseLoader
standard/orbit.gif	standard/DNA.gif	standard/AI.gif
Orbit MotionOrbitLoader	DNA MotionDnaLoader	AI MotionAiLoader
standard/liquid.gif	standard/wave.gif	standard/futuristic.gif
Liquid MotionLiquidLoader	Wave MotionWaveLoader	Futuristic MotionFuturisticLoader
standard/matrix.gif	standard/gradient_rotating.gif
Matrix MotionMatrixLoader	Gradient Rotating MotionGradientRotatingLoader

---

Advanced Category Loaders (60+ Premium Presets)

Exposes named category factory constructors on MotionLoader allowing direct, beautifully clean initialization of specialized category families. Below are the grids showcasing all advanced vector loaders, grouped by category.

🧠 AI Category (MotionLoader.ai)

advanced/neural_network.gif	advanced/AI_thinking.gif	advanced/quantum_warp.gif
Neural Network MotionAiStyle.neuralNetwork	AI Thinking MotionAiStyle.thinking	Quantum Warp MotionAiStyle.quantum
advanced/token_stream.gif	advanced/token_predictor.gif	advanced/neural_pulse.gif
Token Stream MotionAiStyle.tokenStream	Token Predictor MotionAiStyle.tokenPrediction	Neural Pulse MotionAiStyle.neuralPulse
advanced/tensor_data_matrix.gif	advanced/scifi_cyber_eye.gif
TensorFlow MotionAiStyle.tensorFlow	AI Cyber Eye MotionAiStyle.aiEye

🦾 Cyberpunk Category (MotionLoader.cyberpunk)

advanced/console_boot_terminal.gif	advanced/cyber_spatial_rift.gif	advanced/hud_concentric_ring.gif
Terminal Boot MotionCyberpunkStyle.terminalBoot	Glitch MotionCyberpunkStyle.glitch	Cyber Ring HUD MotionCyberpunkStyle.cyberRing
advanced/data_stream_pipes.gif	advanced/firewall_scanner_radar.gif
Data Stream MotionCyberpunkStyle.dataStream	Firewall Scanner MotionCyberpunkStyle.firewallScanner

🧲 Physics Category (MotionLoader.physics)

advanced/newton_pendulum.gif	advanced/bounce_chain.gif	advanced/gravity_orbit.gif
Pendulum MotionPhysicsStyle.pendulum	Bounce Chain MotionPhysicsStyle.bounceChain	Gravity Orbit MotionPhysicsStyle.gravityOrbit
advanced/falling_hourglass_sand.gif	advanced/magnetic_filings.gif	No Preview (Asset Missing)
Sand Simulation MotionPhysicsStyle.sandSimulation	Magnetic Field MotionPhysicsStyle.magneticField	Fluid Particle MotionPhysicsStyle.fluidParticle

📐 Geometry Category (MotionLoader.geometry)

advanced/impossible_infinity_cube.gif	advanced/honeycomb_radial_wave.gif	advanced/recursive_fractal_tree.gif
Infinite Cube MotionGeometryStyle.infiniteCube	Hexagon Swarm MotionGeometryStyle.hexagonSwarm	Fractal Tree MotionGeometryStyle.fractal
advanced/smooth_polygon_morph.gif
Polygon Morph MotionGeometryStyle.polygonMorph

💬 Social Category (MotionLoader.social)

advanced/reels_neon_progress.gif	advanced/live_broadcast_signl.gif	advanced/story_gradient_ring.gif
Reels Upload MotionSocialStyle.reelsUpload	Live Stream MotionSocialStyle.liveStream	Story Ring MotionSocialStyle.storyRing

📦 3D Category (MotionLoader.threeD)

advanced/3d_parallax_cubes.gif	advanced/stacked_isometric_block.gif	advanced/wire_sphere_landscape.gif
Floating Cube MotionThreeDStyle.floatingCube	Isometric Blocks MotionThreeDStyle.isometric	Holographic Sphere MotionThreeDStyle.holographicSphere

🎵 Audio Category (MotionLoader.audio)

advanced/equalizer_sound_freq.gif	advanced/spinning_retro_record.gif	advanced/bass_reactive_curve.gif
Equalizer MotionAudioStyle.equalizer	Retro Vinyl MotionAudioStyle.vinyl	Beat Wave MotionAudioStyle.beatWave

🎨 Artistic Category (MotionLoader.artistic)

advanced/origami_paper_crane.gif	advanced/calligraphy_infinity.gif	No Preview (Asset Missing)
Origami MotionArtisticStyle.origami	Calligraphy Stroke MotionArtisticStyle.calligraphyStroke	Zen Circle MotionArtisticStyle.zenCircle

🌌 Experimental Category (MotionLoader.experimental)

advanced/melting_time_wraop_clock.gif	advanced/sci_fi_energy_portal.gif	advanced/cyber_spatial_rift.gif
Time Warp MotionExperimentalStyle.timeWarp	Energy Portal MotionExperimentalStyle.portal	Dimensional Rift MotionExperimentalStyle.dimensionalRift
advanced/cosmic_tunnel_stars.gif
Wormhole MotionExperimentalStyle.wormhole

🌊 Liquid Category (MotionLoader.liquid)

advanced/fluid_attraction.gif	advanced/water_drop_pulse.gif	advanced/ink_spread.gif
Lava Lamp MotionLiquidStyle.lavaLamp	Water Drop MotionLiquidStyle.waterDrop	Ink Spread MotionLiquidStyle.inkSpread

🔮 Glass Category (MotionLoader.glass)

advanced/frosted_glass_orb.gif	advanced/prism_crystal.gif	advanced/aurora_mesh.gif
Glass Orb MotionGlassStyle.glassOrb	Prism Crystal MotionGlassStyle.prismCrystal	Aurora Mesh MotionGlassStyle.aurora

💎 Luxury Category (MotionLoader.luxury)

advanced/prism_shine_diamond.gif	advanced/silk_flow_gradient.gif	advanced/watch_clockwork_gear.gif
Diamond Spark MotionLuxuryStyle.diamondSpark	Silk Flow MotionLuxuryStyle.silkFlow	Premium Watch MotionLuxuryStyle.premiumWatch
No Preview (Asset Missing)
Gold Sweep MotionLuxuryStyle.goldSweep

🎮 Gaming Category (MotionLoader.gaming)

advanced/hero_xp_shield.gif	advanced/magic_runic_ring.gif	advanced/retro_crt_pixel.gif
XP Progress MotionGamingStyle.xpProgress	Boss Fight MotionGamingStyle.bossFight	Retro Pixel MotionGamingStyle.pixel

📊 SaaS Category (MotionLoader.saas)

advanced/skeleton_grid.gif	advanced/chart_analytics.gif	advanced/sync_cloud_bubbles.gif
Pulse Grid MotionSaasStyle.pulseGrid	Analytics Chart MotionSaasStyle.analytics	Cloud Sync MotionSaasStyle.cloudSync

🌿 Nature Category (MotionLoader.nature)

advanced/glowing_firefly_light.gif	advanced/wind_tornado_dust.gif	No Preview (Asset Missing)
Firefly Glow MotionNatureStyle.firefly	Tornado Vortex MotionNatureStyle.tornado	Volcano MotionNatureStyle.volcano
No Preview (Asset Missing)	No Preview (Asset Missing)
Leaf Wind MotionNatureStyle.leafWind	Solar Eclipse MotionNatureStyle.solarEclipse

🌌 Space Category (MotionLoader.space)

advanced/black_hole.gif	advanced/glaxy_spiral.gif	advanced/warp_respective.gif
Black Hole MotionSpaceStyle.blackHole	Galaxy MotionSpaceStyle.galaxy	Warp Speed MotionSpaceStyle.warpSpeed

📐 Minimal Category (MotionLoader.minimal)

advanced/lemniscate_path.gif	advanced/morphing_shapes.gif	advanced/3d_wave_ribbon.gif
Line Draw MotionMinimalStyle.lineDraw	Morph Shape MotionMinimalStyle.morphShape	Infinite Ribbon MotionMinimalStyle.infiniteRibbon

---

🎨 Compound Effect Stack System (MotionBuilder)

Exposed via MotionBuilder, this unified decorator system allows wrapping any arbitrary child widget with stackable, GPU-optimized cascading compound visual animations!

• Usage:

  MotionBuilder(
    duration: const Duration(seconds: 4),
    effects: const [
      GlowEffect(color: Colors.purple, blurRadius: 16.0),
      FloatEffect(dy: 8.0),
      OrbitEffect(radius: 20.0, speed: 1.2),
    ],
    child: Image.asset('assets/images/logo.png'),
  )
  

• Stackable Effects:
  • GlowEffect(Color color, double blurRadius, double spreadRadius) — Adds a pulsing neon bloom shadow halo behind the child.
  • FloatEffect(double dy) — Floats the child vertically up and down in smooth sinusoidal curves.
  • OrbitEffect(double radius, double speed) — Orbits the child itself (or nested markers) in a circular path.
  • RippleEffect(Color color, double maxRadius) — Shoots multiple expanding circular waves behind the child.
  • GlitchEffect(double intensity) — Trigger random RGB digital split distortions and skews for cyberpunk aesthetics.
• Parameters:
  • effects: A list of MotionEffect components to apply sequentially (applied inner-to-outer).
  • child: The target widget to compound.
  • duration: Central loop duration cycle (default: 3 seconds).

---

4. Interactive Action Controls

MotionButton

• Visual Preview:
• Description: A tactile, feedback-rich click action control. Supports magnetic physical pulls, pointer displacement springs, neon glowing blurs, scale bounces, or touch-expanding canvas custom ripples.
• Usage:

  MotionButton(
    effect: MotionButtonEffect.ripple,
    color: Colors.cyanAccent,
    onTap: () => print('Button pressed!'),
    child: const Text('Neon Ripple Button'),
  )
  

• Parameters:
  • effect: Bouncing, glowing, or ripple action profile (MotionButtonEffect).
  • color: Neon glow or ripple accent paint.
  • onTap: Callback action triggered upon tap.
  • child: Button label text or icons.

MotionExpandableFab

• Visual Preview:
• Description: Premium Speed Dial Floating Action Button. When tapped, it rolls out a modular fan list of child action options in radial orbits.
• Usage:

  MotionExpandableFab(
    distance: 90.0,
    icon: const Icon(Icons.menu),
    children: [
      IconButton(icon: const Icon(Icons.share), onPressed: () {}),
      IconButton(icon: const Icon(Icons.email), onPressed: () {}),
    ],
  )
  

• Parameters:
  • distance: Radial distance (offset radius) for child buttons.
  • icon: Center anchor floating button icon.
  • children: Stack of action buttons to expand/reveal.

MotionMorphingButton

• Visual Preview:
• Description: An advanced material-state action button. Takes an asynchronous operation, shrinks boundaries, and morphs from a standard button shape into a progress liquid-loader, and subsequently transitions into a success checkmark or error cross.
• Usage:

  MotionMorphingButton(
    width: 180,
    height: 48,
    borderRadius: 12,
    onTap: () async {
      await Future.delayed(const Duration(seconds: 2));
    },
    child: const Text('SUBMIT DISPATCH'),
  )
  

• Parameters:
  • width/height: Idle dimensions.
  • onTap: Async callback to resolve.
  • child: Center label when idle.

MotionPullToRefresh

• Description: Next-generation, high-performance pull-to-refresh wrapper exposing 20 premium visual custom-painted animations. Supports physics-based bouncing and clamping styles, custom hold delays, haptics, and adaptive dark/light themes.
• Usage:

  MotionPullToRefresh(
    animation: MotionRefreshAnimation.liquidMorph,
    onRefresh: () async {
      await Future.delayed(const Duration(seconds: 2));
    },
    child: ListView.builder(
      itemCount: 20,
      itemBuilder: (context, index) => ListTile(title: Text('Item $index')),
    ),
  )
  

• Parameters:
  • onRefresh: The asynchronous callback task triggered upon release.
  • animation: The active MotionRefreshAnimation layout preset indicator to render.
  • refreshDuration: The minimum duration the indicator remains visible (defaults to 3 seconds).
  • collapseDuration: The duration taken to smoothly slide up/collapse after refresh completes.
  • style: The visual layout style (bouncing or clamping).
  • showStatusText: Toggles rendering of helper text (e.g. "PULL TO REFRESH").
  • enableHaptics: Toggles vibration feedback.

---

🎨 20 Refresh Indicator Animations Preview

🌊 Fluid & Nature Preset Grid

Liquid Morph	Tornado	Ink Spread
liquidMorph	tornado	inkSpread
Crystal Growth	Phoenix Rebirth
crystalGrowth	phoenixRebirth

🌌 Cosmic & Gravitational Preset Grid

Black Hole	Planet Orbit	Magnetic Orb
blackHole	planetOrbit	magneticOrb
Portal
portal

🦾 Technical & Flagship Preset Grid

Rocket Launch	DNA Helix	Jelly Bounce
rocketLaunch	dnaHelix	jellyBounce
Infinity Symbol	Neural Network	Clockwork
infinitySymbol	neuralNetwork	clockwork
Origami Bird	Lightning Charge	Fireworks
origamiBird	lightningCharge	fireworks
Hologram	Signature
hologram	signature

---

5. Micro-Interactions

MotionLikeButton

• Visual Preview:
• Description: Popping interaction button. Tapping scale-bounces the heart icon and shoots dynamic paint droplets outwards in a circular splash burst.
• Usage:

  MotionLikeButton(
    initialLiked: false,
    size: 32.0,
    onChanged: (liked) => print('Liked status: $liked'),
  )
  

• Parameters:
  • initialLiked: Initial state boolean.
  • size: Graphic width and height bounds.
  • onChanged: Callback reporting new state value.

MotionAnimatedCheckmark

• Visual Preview:
• Description: Smooth vector checkmark draw interaction. Tapping paints a circular baseline and animates the completion of the vector check icon stroke dynamically.
• Usage:

  MotionAnimatedCheckmark(
    size: 40.0,
    color: Colors.greenAccent,
  )
  

• Parameters:
  • size: Width/height dimensions.
  • color: Stroke outline color.

MotionLiquidToggle

• Visual Preview:
• Description: An organic toggle switch. Sliding changes background colors and applies gaseous liquid distortion filters to boundary shapes as they drag.
• Usage:

  MotionLiquidToggle(
    value: false,
    onChanged: (val) => print('Toggle value: $val'),
  )
  

• Parameters:
  • value: True/false state.
  • onChanged: Callback reporting updated boolean.

MotionBookmarkButton

• Visual Preview:
• Description: An elastic ribbon selector interaction. Tapping slides the ribbon down and morphs its geometry from an outline flag to a filled block.
• Usage:

  MotionBookmarkButton(
    initialBookmarked: false,
    size: 26.0,
  )
  

---

6. Cards, Morphings, Glass & Placeholders

MotionCard

• Visual Preview:
• Description: A 3D pointer-tracking perspective card. Listens to drag gestures (on mobile) or hover movements (on web/desktop) and tilts boundaries in three-dimensional space, projecting a glowing sweeping light reflection.
• Usage:

  MotionCard(
    maxTiltAngleX: 12.0,
    maxTiltAngleY: 12.0,
    shadowColor: Colors.purple.withValues(alpha:0.2),
    child: const CustomCardView(),
  )
  

• Parameters:
  • maxTiltAngleX/Y: Maximum tilt threshold limits in degrees.
  • shadowColor: Directional backing shadow color.

MotionMorphContainer

• Visual Preview:
• Description: Interactive geometric container. Animates its boundary sizes, border radii, linear gradients, and back shadows cleanly when layout structures change.
• Usage:

  MotionMorphContainer(
    width: isExpanded ? 240.0 : 100.0,
    height: isExpanded ? 140.0 : 100.0,
    decoration: BoxDecoration(
      borderRadius: BorderRadius.circular(isExpanded ? 16 : 50),
      color: Colors.indigo,
    ),
    child: widget,
  )
  

• Parameters:
  • width/height: Layout targets to morph.
  • decoration: Backing border decoration targets.
  • child: Internal child node to swap.

MotionGlassContainer

• Visual Preview:
• Description: A high-end glassmorphic panel. Implements a frosted backdrop filter and paints dynamic sweeping neon borders. Automatically turns off frosted blurs on low-performance devices to guarantee high refresh rates.
• Usage:

  MotionGlassContainer(
    borderRadius: 16.0,
    blur: 12.0,
    opacity: 0.1,
    borderColors: const [Colors.cyanAccent, Colors.purpleAccent],
    child: const Text('Frosted panel'),
  )
  

• Parameters:
  • borderRadius: Rounded boundary radius.
  • blur: Frosted backdrop blur filter intensity.
  • opacity: Backing background opacity scale.
  • borderColors: Neon sweeping border gradient array.

MotionSkeleton

• Visual Preview:

• Description: Place-holder loading block designed for skeletons. Pulses high-performance neon highlights smoothly.

• Usage:

  // Circular profile
  const MotionSkeleton.circular(size: 40)
  
  // Rounded rectangle profile
  const MotionSkeleton.rectangle(width: 200, height: 16)
  

MotionShimmer

• Visual Preview:
• Description: Slide sweeping shimmer light. Casts linear sliding highlights from left to right over any widget tree child.
• Usage:

  MotionShimmer(
    child: Container(color: Colors.white, width: 80, height: 12),
  )
  

---

7. Custom Route Transitions

MotionTransition

• Visual Preview:

• Description: Helper containing static custom routing transition methods. Swaps scaffolding routes smoothly.

• Usage:

  // 1. Sinusoidal liquid sweeping page transition
  Navigator.push(context, MotionTransition.liquidSwipe(page: const TargetPage()));
  
  // 2. Sliding Shared Axis page transition
  Navigator.push(context, MotionTransition.sharedAxis(page: const TargetPage(), vertical: true));
  
  // 3. Frosted glass page overlay transition
  Navigator.push(context, MotionTransition.glassOverlay(page: const TargetPage()));
  

---

⚙️ Core Controllers & Accessibility

flutter_motion_kit manages global settings dynamically through highly performant services:

• MotionController
  • reducedMotion: Listens to OS level indicators or manual toggles to reduce physics complexity.
  • performanceMode: Disables expensive blurs or high-density particles to maintain high refresh rates on low-end hardware.
  • speedMultiplier: Multiplies durations dynamically (e.g. 0.5x slow-mo or 2.0x rapid speed).
• MotionThemeController
  • toggleTheme(): Swaps between dark/light states.
  • Preset applicators for Cyberpunk, Midnight Gold, and Ultra Violet neon modes.

---

🤝 Contributing

We welcome contributions! Please review our Contributing Guidelines to maintain standard naming conventions, architecture layouts, and complete verification checklists.

---

📄 License

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

---

👤 Author

Ajeet Kumar Sah

• GitHub: @ajeetkumarsah

---

☕ Support the Project

If you love this package and find it helpful, consider supporting the developer:

• Buy me a Chai or Coffee ☕
• UPI ID: 7761826600@kotak811

Every cup helps keep the screen bright and the code clean!