celebration_fx 🎉 #

A high-performance, physics-driven particle celebration engine for Flutter. Designed for rewards, milestones, gamification, and delight.

Features realistic gravity, air drag, wind velocity, and 3D paper flutter (tumbling flip & yaw).

✨ Features #

• 🎊 Multiple Built-in Presets:
  • CelebrationConfig.confetti(): Upward paper ribbon cannon with 3D paper flutter.
  • CelebrationConfig.fireworks(): 360° radial explosive firework bursts.
  • CelebrationConfig.coins(): Falling gold coins for fintech & game rewards.
  • CelebrationConfig.hearts(): Upward floating love hearts for likes & reactions.
  • CelebrationConfig.stars(): Twinkling celestial star bursts.
• ⚡ Physics-Driven:
  • Real velocity vector integration, gravity acceleration, air resistance drag, and horizontal wind.
• 🎯 CelebrationButton Widget:
  • Self-contained reward button that automatically explodes particles directly from its tapped coordinates.
• 🚀 Zero Dependencies: Pure Flutter custom-canvas rendering. Lightweight & Impeller-ready.

📦 Getting Started #

flutter pub add celebration_fx

Or add to pubspec.yaml:

dependencies:
  celebration_fx: ^1.0.1

🚀 Quick Start #

1. Trigger Particle Bursts Anywhere #

import 'package:flutter/material.dart';
import 'package:celebration_fx/celebration_fx.dart';

class MyPage extends StatefulWidget {
  @override
  State<MyPage> createState() => _MyPageState();
}

class _MyPageState extends State<MyPage> {
  final CelebrationController _controller = CelebrationController();

  @override
  void dispose() {
    _controller.dispose();
    super.dispose();
  }

  void _celebrate() {
    // Burst confetti from the center of the screen
    _controller.burst(
      origin: const Offset(200, 300),
      config: CelebrationConfig.confetti(),
    );
  }

  @override
  Widget build(BuildContext context) {
    return CelebrationFx(
      controller: _controller,
      child: Scaffold(
        body: Center(
          child: ElevatedButton(
            onPressed: _celebrate,
            child: const Text('Celebrate! 🎉'),
          ),
        ),
      ),
    );
  }
}

2. Instant CelebrationButton #

CelebrationButton(
  config: CelebrationConfig.coins(),
  onPressed: () {
    print('Claimed Reward!');
  },
  child: const Text('Claim Reward 🪙'),
)

⚙️ Custom Physics & Styling #

_controller.burst(
  origin: Offset(100, 200),
  config: CelebrationConfig(
    particleCount: 120,
    gravity: 400.0,
    drag: 0.97,
    wind: 50.0, // blows to the right
    spread: 120.0, // 120 degree cone
    direction: 270.0, // upward
    minVelocity: 300.0,
    maxVelocity: 800.0,
    colors: [Colors.purple, Colors.cyan, Colors.amber],
  ),
);

📄 License #

MIT License - Copyright (c) 2026 Shahzain Baloch