seasonal_decor #

[Seasonal Decor Logo]

Add beautiful seasonal animations and festive overlays to your Flutter app with one line of code.

Bring Ramadan vibes, Christmas magic, Valentine effects, New Year celebrations, and more instantly.

Install with one command: flutter pub add seasonal_decor

✨ Features #

• 🎄 Christmas snow and festive decorations
• 🌙 Ramadan lanterns and crescents
• 🎉 Eid balloons and sparkles
• 🎃 Halloween particles and spooky mood
• ❤️ Valentine hearts
• 🎆 New Year fireworks and confetti
• ⚽ Football celebration mode
• 🌗 Light and dark theme adaptation
• 📱 Android, iOS, Web, Windows, macOS, Linux
• 🎛 Control intensity, speed, size, and backdrop layers
• 💬 Animated greeting text (showText, text, textOpacity)

🚀 Quick Start #

SeasonalDecor(
  preset: SeasonalPreset.ramadan(),
  intensity: DecorIntensity.medium,
  child: const HomeScreen(),
);

That is it. Instant festive UI.

✅ Recommended Setup #

SeasonalDecor(
  preset: SeasonalPreset.ramadan(),
  intensity: DecorIntensity.high,
  playDuration: const Duration(seconds: 8),
  repeatEvery: const Duration(minutes: 2),
  showBackdrop: true,
  showText: true,
  textOpacity: 0.5,
  particleSpeedMultiplier: 1.1,
  adaptColorsToTheme: true,
  child: const HomeScreen(),
);

Recommended defaults for most apps:

• Keep respectReduceMotion: true (default)
• Keep pauseWhenInactive: true (default)
• Use intensity: DecorIntensity.medium/high for daily screens
• Use high/extraHigh/max only for short celebration moments

🎮 Interactive Demo Controls #

In the advanced example app (example/lib/advanced_main.dart), users can interact with:

• Preset picker and intensity controls
• repeatEvery and play duration
• Backdrop visibility by layer (background/decorative)
• Greeting text toggle, text input, and text animation controls
• Reduce-motion behavior and simulation

🎨 Available Presets #

• SeasonalPreset.ramadan()
• SeasonalPreset.ramadan(variant: RamadanVariant.hangingLanterns) (new)
• SeasonalPreset.eid()
• SeasonalPreset.christmas()
• SeasonalPreset.newYear()
• SeasonalPreset.valentine()
• SeasonalPreset.halloween()
• SeasonalPreset.football() (sportEvent() still works as alias)
• SeasonalPreset.none()

🎬 Preset GIF Previews #

If GIFs do not render in your mirror/CDN, open files directly from assets/gif/.

🎛 Customization #

SeasonalDecor(
  preset: SeasonalPreset.christmas(),
  intensity: DecorIntensity.high,
  particleSpeedMultiplier: 1.2,
  particleSizeMultiplier: 1.1,
  showBackdrop: true,
  showBackgroundBackdrops: true,
  showDecorativeBackdrops: true,
  showText: true,
  textOpacity: 0.5,
  repeatEvery: const Duration(minutes: 2),
  child: const HomeScreen(),
);

⚔️ Why Not Just Confetti ? #

🌍 Live Demo #

Live Demo

📦 Installation #

Add this to your pubspec.yaml:

dependencies:
  seasonal_decor: ^1.3.1

Then run:

flutter pub get

Or simply:

flutter pub add seasonal_decor

🧪 Quick Recipes #

Confetti only (disable fireworks in New Year):

SeasonalDecor(
  preset: SeasonalPreset.newYear(),
  presetEnableFireworks: false,
  child: const HomeScreen(),
);

Backdrop only:

SeasonalDecor(
  preset: SeasonalPreset.ramadan(),
  presetShapes: const <ParticleShape>[],
  showBackdrop: true,
  child: const HomeScreen(),
);

Greeting text with default seasonal message:

SeasonalDecor(
  preset: SeasonalPreset.ramadan(),
  showText: true,
  textOpacity: 0.5, // default
  child: const HomeScreen(),
);

Custom message:

SeasonalDecor(
  preset: SeasonalPreset.eid(variant: EidVariant.adha),
  showText: true,
  text: 'Eid Mubarak',
  textStyle: const TextStyle(
    fontSize: 36,
    fontWeight: FontWeight.w700,
  ),
  textDisplayDuration: const Duration(seconds: 2),
  textAnimationDuration: const Duration(milliseconds: 550),
  child: const HomeScreen(),
);

Custom background backdrop widget:

SeasonalDecor(
  preset: SeasonalPreset.ramadan(),
  showBackdrop: true,
  backgroundBackdrop: Align(
    alignment: const Alignment(0.85, -0.7),
    child: Icon(Icons.nightlight_round, size: 180, color: Color(0x66FFE2A6)),
  ),
  child: const HomeScreen(),
);

⚙️ Core Options (Full Table) #

🧪 Example #

Run example app:

flutter run -t example/lib/main.dart

Run advanced demo:

flutter run -t example/lib/advanced_main.dart

📄 License #

MIT License. See LICENSE.