seasonal_decor #

⭐ One line of code… and your Flutter app celebrates. 🎉

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

Install with one command: flutter pub add seasonal_decor

🌍 Live Demo #

Try it now: https://tamourax.github.io/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()
• SeasonalPreset.none()

🎬 Preset GIF Previews #

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

Ramadan	Ramadan Lights	Eid al-Fitr

Eid al-Adha	Christmas	Valentine

New Year	Halloween	Football

🎛 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 ? #

📦 Installation #

Add this to your pubspec.yaml:

dependencies:
  seasonal_decor: ^1.3.4

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(),
  showBackdrop: true,
  presetShapes: const <ParticleShape>[], // disable particle styles
  // Optional (best performance): keep backdrop static without animation ticks.
  // enabled: false,
  // showBackdropWhenDisabled: 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),
  text: 'Eid Mubarak',
  textStyle: const TextStyle(
    fontSize: 36,
    fontWeight: FontWeight.w700,
  ),
  textDisplayDuration: const Duration(seconds: 2),
  textAnimationDuration: const Duration(milliseconds: 550),
  child: const HomeScreen(),
);

Text visibility rules:

• showText: false + non-empty text: hidden.
• showText: true + empty text: preset default greeting appears.
• omitted showText + non-empty text: custom text appears.
• omitted showText + empty text: hidden.
• with repeatEvery, greeting text appears once per enabled run series.

Text animation behavior (v1.3.4):

• The greeting now finishes its enter animation first, then stays visible for textDisplayDuration, then exits.
• The first greeting starts after the first frame for smoother app startup.
• Pause/resume now keeps text timing steady to avoid bounce/reverse artifacts.

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.