Workfire 🎆 #

A beautiful, performant, and customizable firework widget for Flutter applications.

Features #

• Click-through design: Fireworks won't interfere with your app's UI
• Highly customizable: Control every aspect of the firework animation
• Performance optimized: Automatic cleanup and efficient rendering
• Easy to use: Simple API for single fireworks or complex shows
• Cross-platform: Works on all Flutter-supported platforms

Installation #

Add workfire to your pubspec.yaml:

dependencies:
  workfire: ^1.0.0

Quick Start #

Single Firework #

import 'package:workfire/workfire.dart';

// Basic firework
Firework()

// Customized firework
Firework(
  particleColors: [Colors.red, Colors.blue, Colors.yellow],
  particleCount: 20,
  particleDistance: 150,
  rocketColor: Colors.white,
)

Firework Show #

FireworkShow(
  fireworks: [
    FireworkConfig(
      delay: Duration.zero,
      particleColors: [Colors.red, Colors.pink],
    ),
    FireworkConfig(
      delay: Duration(milliseconds: 500),
      particleColors: [Colors.blue, Colors.cyan],
    ),
    FireworkConfig(
      delay: Duration(seconds: 1),
      particleColors: [Colors.yellow, Colors.orange],
    ),
  ],
)

Customization Options #

Part 1: Rocket Parameters #

Part 2: Explosion Parameters #

Note: Particles travel continuously and their final distance is determined by their fade speed. When a particle completely fades out, it's removed from the animation. This creates a more realistic effect where particles don't stop moving while still visible. The gravity parameter adds realistic downward acceleration to particles, making them fall naturally over time.

Examples #

Celebration Firework #

Firework(
  particleColors: [Colors.gold, Colors.yellow, Colors.orange],
  particleCount: 25,
  particleRingGlow: true,
  ringColor: Colors.amber,
  gravity: 80.0,
)

Subtle Firework #

Firework(
  rocketIsVisible: false,
  ringThickness: 0,
  particleColors: [Colors.white],
  particleCount: 8,
  particleRingGlow: false,
  gravity: 30.0,
)

Zero Gravity Firework #

Firework(
  particleColors: [Colors.cyan, Colors.blue],
  particleCount: 15,
  gravity: 0.0,
)

Grand Finale Show #

FireworkShow(
  fireworks: List.generate(5, (index) => 
    FireworkConfig(
      delay: Duration(milliseconds: index * 200),
      startingPosition: Offset(
        MediaQuery.of(context).size.width * (0.2 + index * 0.15),
        MediaQuery.of(context).size.height,
      ),
      endingPosition: Offset(
        MediaQuery.of(context).size.width * (0.2 + index * 0.15),
        MediaQuery.of(context).size.height * (0.3 + index * 0.1),
      ),
      particleColors: [
        [Colors.red, Colors.pink],
        [Colors.blue, Colors.cyan],
        [Colors.yellow, Colors.orange],
        [Colors.green, Colors.lime],
        [Colors.purple, Colors.deepPurple],
      ][index],
      particleCount: 15 + index * 2,
    ),
  ),
)

Best Practices #

1. Performance: Always provide an onComplete callback to manage widget lifecycle
2. Positioning: Use MediaQuery.of(context).size for responsive positioning
3. Colors: Use contrasting colors for better visibility

Technical Details #

• Uses IgnorePointer to ensure click-through behavior
• Automatic cleanup of animation controllers and widgets
• Optimized rendering with conditional widget building
• Memory efficient particle system

License #

MIT License - see LICENSE file for details.

Contributing #

Contributions are welcome! Please read our contributing guidelines and submit pull requests.