seasonal_decor #

Drop-in seasonal decorative overlays for Flutter apps. Ships with a lightweight CustomPainter + Ticker particle engine and ready-to-use presets for Ramadan, Eid, Christmas, New Year, Valentine, Halloween, and Sport Event.

Installation #

Add this to your pubspec.yaml:

dependencies:
  seasonal_decor: ^1.1.4

Then run:

flutter pub get

Or simply:

flutter pub add seasonal_decor

Quick Start #

SeasonalDecor(
  preset: SeasonalPreset.ramadan(),
  intensity: DecorIntensity.medium,
  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(),
);

Options #

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 Notes #

• Fixed-size particle pool with reuse.
• Adaptive density scaling based on screen area.
• RepaintBoundary isolates the overlay.
• Optional pause on inactive lifecycle states.

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.