seasonal_decor #

Seasonal overlays for Flutter apps - Ramadan, Eid, Christmas, New Year, Valentine, Halloween, and more.

Add beautiful seasonal particle effects to your Flutter app in one line of code.

Try the Live Demo above or install with one line: flutter pub add seasonal_decor

Live Demo #

Live Demo Published from the live-demo branch to keep the package branch lightweight.

Releases #

• GitHub Releases: https://github.com/tamourax/seasonal_decor/releases
• Latest release notes draft: release_notes/v1.1.5.md

Installation #

Add this to your pubspec.yaml:

dependencies:
  seasonal_decor: ^1.1.5

Then run:

flutter pub get

Or simply:

flutter pub add seasonal_decor

Quick Start #

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

Examples #

Basic #

SeasonalDecor(
  preset: SeasonalPreset.christmas(),
  child: const HomeScreen(),
);

Medium (Common Controls) #

SeasonalDecor(
  preset: SeasonalPreset.eid(variant: EidVariant.fitr),
  intensity: DecorIntensity.high,
  particleSpeedMultiplier: 1.3,
  showBackdrop: true,
  adaptColorsToTheme: true,
  child: const HomeScreen(),
);

Advanced (Preset Overrides) #

SeasonalDecor(
  preset: SeasonalPreset.ramadan(),
  intensity: DecorIntensity.max,
  presetShapes: const [ParticleShape.lantern, ParticleShape.crescent],
  presetShapeSpeedMultipliers: const {
    ParticleShape.lantern: 1.25,
  },
  presetBackdropType: BackdropType.crescent,
  presetBackdropAnchor: const Offset(0.8, 0.2),
  presetBackdropSizeFactor: 0.3,
  repeatEvery: const Duration(minutes: 10),
  child: const HomeScreen(),
);

Quick Comparison #

Comparison against a typical confetti package (exact features vary by package/version):

Quick Recipes #

Confetti only (disable fireworks in New Year preset):

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

Backdrop only (no particles):

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

Double speed:

SeasonalDecor(
  preset: SeasonalPreset.christmas(),
  particleSpeedMultiplier: 2.0,
  child: const HomeScreen(),
);

Static backdrop mode (keep decor while animation is disabled):

SeasonalDecor(
  preset: SeasonalPreset.eid(variant: EidVariant.adha),
  enabled: false,
  showBackdrop: true,
  showBackdropWhenDisabled: true,
  child: const HomeScreen(),
);

Easy Usage #

Basic overlay:

SeasonalDecor(
  preset: SeasonalPreset.christmas(),
  child: const HomeScreen(),
);

No overlay (render child only):

SeasonalDecor(
  preset: SeasonalPreset.none(),
  child: const HomeScreen(),
);

Control intensity and opacity:

SeasonalDecor(
  preset: SeasonalPreset.eid(),
  intensity: DecorIntensity.max,
  opacity: 0.9,
  child: const HomeScreen(),
);

Control speed and theme-aware colors:

SeasonalDecor(
  preset: SeasonalPreset.newYear(),
  intensity: DecorIntensity.extraHigh,
  particleSpeedMultiplier: 1.4,
  adaptColorsToTheme: true,
  child: const HomeScreen(),
);

Timed playback with optional auto-repeat:

SeasonalDecor(
  preset: SeasonalPreset.sportEvent(),
  playDuration: const Duration(seconds: 8),
  repeatEvery: const Duration(minutes: 10),
  settleOnDisable: true,
  showBackdrop: true,
  child: const HomeScreen(),
);

Customize particle shapes and backdrops:

final preset = SeasonalPreset.eid(variant: EidVariant.fitr).withOverrides(
  shapes: [ParticleShape.balloon],
  shapeSpeedMultipliers: {ParticleShape.balloon: 1.3},
  backdropType: BackdropType.bunting,
  backdropAnchor: const Offset(0.5, 0.12), // position (x,y)
  backdropSizeFactor: 0.08, // size
);

SeasonalDecor(
  preset: preset,
  child: const HomeScreen(),
);

Widget-level preset overrides (directly in SeasonalDecor):

SeasonalDecor(
  preset: SeasonalPreset.ramadan(),
  presetShapes: const [ParticleShape.lantern, ParticleShape.crescent],
  presetShapeSpeedMultipliers: const {
    ParticleShape.lantern: 1.25,
  },
  presetBackdropType: BackdropType.crescent,
  presetBackdropAnchor: const Offset(0.8, 0.2),
  presetBackdropSizeFactor: 0.3,
  child: const HomeScreen(),
);

Advanced Example #

SeasonalDecor(
  preset: SeasonalPreset.sportEvent(),
  playDuration: const Duration(seconds: 8),
  repeatEvery: const Duration(minutes: 10),
  settleOnDisable: true,
  showBackdrop: true,
  child: const HomeScreen(),
);

Core Options (Quick Table) #

Full Options Reference #

Notes:

• Use playDuration: Duration.zero for continuous animation.

Option Details #

child The widget you want to decorate. The overlay is painted on top of this widget.

preset Pick a ready-made style like Ramadan, Eid, Christmas, New Year, Valentine, Halloween, or Sport Event. Presets include shapes, colors, and backdrops.

You can use SeasonalPreset.none() to render the child without any decoration.

enabled Turn the overlay on or off. When false, particles stop rendering. Backdrops can still show if showBackdropWhenDisabled is true.

intensity Controls how many particles spawn and how fast they move. Use low for subtle effects, high for celebrations. Available levels: low, medium, high, extraHigh, max.

opacity Overall overlay opacity. Use lower values to keep UI readable.

respectReduceMotion If the system has Reduce Motion enabled, the overlay renders a static decoration instead of animating.

pauseWhenInactive Stops the animation when the app is paused or inactive to save resources.

ignorePointer If true, the overlay does not block touches. Your UI remains fully interactive.

playDuration How long each animation cycle runs. Use Duration.zero to keep it running continuously.

settleOnDisable When stopping, existing particles keep moving and fall out naturally instead of disappearing instantly.

repeatEvery Automatically replays the animation after the given time. Set to null to disable auto-repeat.

showBackdrop Show or hide decorative backdrops like crescents, trees, garlands, or stadium elements.

showBackdropWhenDisabled If enabled is false, this keeps the backdrop visible while particles remain hidden.

particleSpeedMultiplier Adds direct speed control for particle falling/movement. Use values above 1.0 to speed up animation and below 1.0 to slow it down.

adaptColorsToTheme When enabled, particle and backdrop colors are tuned for the current light/dark platform brightness to keep contrast and visibility consistent.

Preset Overrides #

All presets can be customized using withOverrides(...) to swap shapes or backdrops.

You can also apply the same override controls directly from SeasonalDecor(...) using: presetShapes, presetStyles, presetShapeSpeedMultipliers, presetBackdrop, presetBackdrops, presetBackdropType, presetBackdropAnchor, presetBackdropSizeFactor, presetBackdropColor, presetBackdropOpacity, and presetEnableFireworks.

Examples:

• Replace all particle shapes with balloons or sheep.
• Change the backdrop type (crescent/tree/garland/bunting/mosque/trophy).
• Change backdrop alignment using backdropAnchor (0..1) and size using backdropSizeFactor.

Presets #

• Ramadan (classic, night)
• Eid al-Fitr (fitr) - bunting + balloons
• Eid al-Adha (adha) - mosque + sheep + fireworks
• Christmas (classic) - snow with detailed tree, candy garland, ornaments, gifts
• New Year (fireworks, gold) - fireworks with confetti
• Valentine (hearts, minimal) - floating hearts with sparkles
• Halloween (spooky, pumpkin) - bats/pumpkins with moon
• Sport Event (worldCup, teamColors) - trophy + celebration

Preset Previews #

Ramadan #

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

Eid al-Fitr #

SeasonalDecor(
  preset: SeasonalPreset.eid(variant: EidVariant.fitr),
  child: const HomeScreen(),
);

Eid al-Adha #

SeasonalDecor(
  preset: SeasonalPreset.eid(variant: EidVariant.adha),
  child: const HomeScreen(),
);

Christmas #

SeasonalDecor(
  preset: SeasonalPreset.christmas(),
  child: const HomeScreen(),
);

New Year #

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

Valentine #

SeasonalDecor(
  preset: SeasonalPreset.valentine(),
  child: const HomeScreen(),
);

None #

SeasonalDecor(
  preset: SeasonalPreset.none(),
  child: const HomeScreen(),
);

Performance #

• Uses CustomPainter.
• Reuses particle pool.
• Respects Reduce Motion.
• Pauses when inactive.

Accessibility #

• If respectReduceMotion is true and MediaQuery.disableAnimations is enabled, the overlay renders a static decoration instead of animating.

Supported Platforms #

• Android
• iOS
• Web
• Windows
• macOS
• Linux

Example #

See example/lib/main.dart for a simple demo.

For the full demo with presets and controls:

flutter run -t example/lib/advanced_main.dart

License #

MIT License. See LICENSE.