DOCSEARCHbyAlgolia
Submit Docs

fireworks-js

repository·master·Indexed 23 days ago

https://github.com/crashmax-dev/fireworks-js

A lightweight, zero-dependency JavaScript library for creating fireworks animations. It supports vanilla JS and provides official integrations for React, Vue, Angular, Svelte, Solid, Preact, and Web Components. The library includes a Fireworks API for controlling animation lifecycles (start, stop, pause, launch), customizable visual and physics options, mouse interactivity, and sound effect support.

Tokens
6.7K
Snippets
9
Records
44
Agent score
79%

What's inside fireworks-js

  2. Use the Fireworks component in Svelte

    master

    The Fireworks component provides a Svelte wrapper for the fireworks engine. You can bind the component instance to a variable using bind:this to access the underlying fireworks instance and control its lifecycle (e.g., starting or stopping).

    Key props:

    • bind:this: Binds the component instance to a variable.
    • autostart: Boolean determining if the fireworks start automatically.
    • options: An object of type FireworksOptions to configure the visual effects.
    • class: CSS class to apply to the fireworks container.
    <script lang="ts">
  import { Fireworks } from '@fireworks-js/svelte'
  import type { FireworksOptions } from '@fireworks-js/svelte'

  let fw: Fireworks
  let options: FireworksOptions = {
    opacity: 0.5
  }

  function toggleFireworks() {
    const fireworks = fw.fireworksInstance()
    if (fireworks.isRunning) {
      fireworks.waitStop()
    } else {
      fireworks.start()
    }
  }
</script>

<Fireworks bind:this={fw} autostart={false} {options} class="fireworks" />

  3. Install framework-specific fireworks-js components

    master

    The library provides dedicated packages for various frameworks. Install the one corresponding to your project:

    • React: npm install @fireworks-js/react
    • Preact: npm install @fireworks-js/preact
    • Solid: npm install @fireworks-js/solid
    • Vue: npm install @fireworks-js/vue
    • Svelte: npm install @fireworks-js/svelte
    • Angular: npm install @fireworks-js/angular
    • Web Components: npm install @fireworks-js/web

  4. Use fireworks-js via CDN

    master

    You can include fireworks-js directly in your HTML using a CDN. Note that when using the UMD build via CDN, you must access the constructor via Fireworks.default.

    <!-- jsDelivr  -->
<script src="https://cdn.jsdelivr.net/npm/fireworks-js@2.x/dist/index.umd.js"></script>

<!-- UNPKG -->
<script src="https://unpkg.com/fireworks-js@2.x/dist/index.umd.js"></script>

<!-- Usage -->
<script>
  const container = document.querySelector('.fireworks')
  const fireworks = new Fireworks.default(container)
  fireworks.start()
</script>

  6. Configure mouse interaction

    master

    The mouse option allows fireworks to respond to user input. It accepts an object with the following properties:

    • click (boolean): Enables fireworks on click. Default is false.
    • move (boolean): Enables fireworks on mouse movement. Default is false.
    • max (number): The maximum number of fireworks. Note that max has no effect if click is set to false.
    mouse: {
  click: false,
  move: false,
  max: 1
}

  7. Configure Fireworks options

    master

    The Fireworks constructor accepts an optional options object to customize the visual and behavioral aspects of the fireworks. Many properties accept a min and max object, which allows the engine to randomly select values within that range for variety.

    Key configuration groups include:

    • Visuals: hue, brightness, decay, opacity, lineWidth, lineStyle, traceLength, traceSpeed, flickering.
    • Physics: acceleration, friction, gravity, explosion.
    • Behavior: delay, intensity, particles, autoresize.
    • Interactivity: mouse (supports click and move).
    • Audio: sound (requires enabled: true and a files array).
    const fireworks = new Fireworks(container, {
  autoresize: true,
  opacity: 0.5,
  acceleration: 1.05,
  friction: 0.97,
  gravity: 1.5,
  particles: 50,
  traceLength: 3,
  traceSpeed: 10,
  explosion: 5,
  intensity: 30,
  flickering: 50,
  lineStyle: 'round',
  hue: {
    min: 0,
    max: 360
  },
  delay: {
    min: 30,
    max: 60
  },
  rocketsPoint: {
    min: 50,
    max: 50
  },
  lineWidth: {
    explosion: {
      min: 1,
      max: 3
    },
    trace: {
      min: 1,
      max: 2
    }
  },
  brightness: {
    min: 50,
    max: 80
  },
  decay: {
    min: 0.015,
    max: 0.03
  },
  mouse: {
    click: false,
    move: false,
    max: 1
  }
})

  8. Configure sound effects

    master

    The sound option enables audio feedback for the fireworks. It accepts an object with the following properties:

    • enabled (boolean): Whether sound is active. Default is false.
    • files (string[]): An array of paths to audio files.
    • volume (object): An object containing min and max values to randomly select the volume level.

  9. Integrate fireworks-js into an Angular application

    master
    To use fireworks in an Angular project, import the NgFireworksModule into your Angular module (usually AppModule). This module exports the FireworksDirective, which allows you to apply fireworks effects to HTML elements using a directive. You can also use the FireworksOptions type from fireworks-js to type your configuration objects.

  10. Use the fireworks-js Web Component

    master

    The @fireworks-js/web package provides a custom HTML element <fireworks-js> that allows you to embed fireworks animations directly into your HTML. The component manages its own lifecycle, starting the animation when connected to the DOM and stopping it when disconnected.

    Configuration via Attributes

    You can configure the animation and its appearance using two attributes:

    1. options: A JSON string representing a FireworksOptions object. This controls the animation parameters (e.g., particle count, colors, physics).
    2. style: A string of CSS rules applied to the internal container div. This allows you to control the size, position, or other visual aspects of the fireworks container.

    Example Usage

    <fireworks-js 
  options='{"autostart": true, "particles": 50}' 
  style='height: 500px; width: 100%;'>
</fireworks-js>

  11. Use fireworks-js in Vanilla JavaScript

    master

    To use the library in a standard JavaScript environment, import the Fireworks class, provide a DOM container, and call .start().

    import { Fireworks } from 'fireworks-js'

const container = document.querySelector('.container')
const fireworks = new Fireworks(container, { /* options */ })
fireworks.start()

  12. Use the Fireworks API

    master

    The Fireworks instance provides several methods to control the lifecycle and state of the animation:

    • .start(): Begins the fireworks animation.
    • .launch(count): Launches a specific number of fireworks. count is a number (default: 1).
    • .stop(dispose): Stops the fireworks. dispose is a boolean (default: false).
    • .waitStop(dispose): Asynchronously stops the fireworks. dispose is a boolean (default: false).
    • .pause(): Pauses or resumes the fireworks.
    • .clear(): Clears the canvas of all current fireworks.
    • .currentOptions: Returns the current configuration options.
    • .updateOptions(options): Forces an update of the fireworks options.
    • .updateSize(sizes): Forces an update of the canvas size.
    • .updateBoundaries(boundaries): Forces an update of the canvas boundaries.