Workfire 🎆

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

🚀 Try the Interactive Demo

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.2

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,
    ),
  ),
)

API Reference

Core Classes

• Firework - The main widget for creating single firework animations
• FireworkShow - Widget for orchestrating multiple fireworks in sequence
• FireworkConfig - Configuration class for customizing firework properties in shows

Key Features

• Realistic Physics: Gravity effects and natural particle movement
• Spiral Rocket Paths: Configurable spiral trajectories with intensity and frequency controls
• Performance Optimized: Efficient rendering with automatic cleanup
• Fully Customizable: Every aspect of the animation can be configured
• Click-through Design: Won't interfere with your app's touch interactions

For detailed API documentation, see the API docs.

🎆 Interactive Demo - Try all features live in your browser!

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.