✨ NGX SparkleFall

Angular directive and component for SparkleFall - Beautiful, customizable falling sparkle animations.

📦 Installation

npm install ngx-sparklefall sparklefall
# If using a bundler (Angular CLI), also import the CSS once in your global styles or in component:
# styles.css: @import 'sparklefall/styles.css';
# or
yarn add ngx-sparklefall sparklefall

🚀 Quick Start

Using the Component

import { SparkleFallComponent } from 'ngx-sparklefall';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [SparkleFallComponent],
  template: `
    <sparkle-fall>
      <h1>✨ Sparkly Content!</h1>
    </sparkle-fall>
  `
})
export class AppComponent {}

Using the Directive

import { SparkleFallDirective } from 'ngx-sparklefall';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [SparkleFallDirective],
  template: `
    <div sparkleFall [sparkleFallEnabled]="true">
      <h1>✨ Sparkly Content!</h1>
    </div>
  `
})
export class AppComponent {}

Using the Module (for non-standalone components)

import { SparkleFallModule } from 'ngx-sparklefall';

@NgModule({
  imports: [SparkleFallModule],
  // ...
})
export class AppModule {}

🎨 Examples

Component with Custom Options

@Component({
  template: `
    <sparkle-fall
      [sparkles]="['✨', '⭐', '💫', '🌟']"
      [interval]="800"
      [maxSparkles]="50"
      [wind]="0.3"
      [colors]="['#FFD700', '#FFA500', '#FF8C00']"
    >
      <div>Your content here</div>
    </sparkle-fall>
  `
})
export class SparklyComponent {}

Directive with Binding

@Component({
  template: `
    <div 
      sparkleFall
      [sparkleFallEnabled]="isSparkly"
      [sparkleFallWind]="windStrength"
      [sparkleFallMaxSparkles]="100"
    >
      <button (click)="toggleSparkles()">Toggle Sparkles</button>
    </div>
  `
})
export class DirectiveExample {
  isSparkly = true;
  windStrength = 0.5;
  
  toggleSparkles() {
    this.isSparkly = !this.isSparkly;
  }
}

Controlled Animation

@Component({
  template: `
    <sparkle-fall
      #sparkleComponent
      [paused]="isPaused"
      (sparkleStart)="onStart()"
      (sparkleStop)="onStop()"
    >
      <div>Controlled sparkles!</div>
    </sparkle-fall>
    
    <button (click)="sparkleComponent.burst(20)">Burst!</button>
    <button (click)="isPaused = !isPaused">Toggle Pause</button>
  `
})
export class ControlledSparkles {
  isPaused = false;
  
  onStart() {
    console.log('Sparkles started!');
  }
  
  onStop() {
    console.log('Sparkles stopped!');
  }
}

📋 Component Properties

| Input | Type | Default | Description | |-------|------|---------|-------------| | enabled | boolean | true | Enable/disable sparkles | | sparkles | string[] | ['✨', '⭐', '💫', '🌟'] | Array of sparkle characters | | colors | string[] \| null | null | Custom colors (null for emoji colors) | | interval | number | 800 | Time between new sparkles (ms) | | minSize | number | 10 | Minimum sparkle size (px) | | maxSize | number | 30 | Maximum sparkle size (px) | | minDuration | number | 2 | Minimum fall duration (seconds) | | maxDuration | number | 5 | Maximum fall duration (seconds) | | wind | number | 0 | Wind effect (-1 to 1) | | spin | boolean | true | Enable rotation | | maxSparkles | number | 50 | Max sparkles on screen | | autoStart | boolean | true | Start automatically | | paused | boolean | false | Pause/resume sparkles | | wrapperClass | string | '' | CSS class for wrapper div | | wrapperStyles | object | {} | Inline styles for wrapper |

Component Outputs

| Output | Type | Description | |--------|------|-------------| | sparkleStart | EventEmitter<void> | Emits when sparkles start | | sparkleStop | EventEmitter<void> | Emits when sparkles stop |

Component Methods

• start() - Start sparkle animation
• stop() - Stop spawning new sparkles
• clear() - Remove all sparkles
• burst(count: number) - Create a burst of sparkles

📋 Directive Properties

All directive inputs are prefixed with sparkleFall:

• sparkleFallEnabled - Enable/disable sparkles
• sparkleFallInterval - Time between sparkles
• sparkleFallSparkles - Array of sparkle characters
• sparkleFallColors - Custom colors
• sparkleFallWind - Wind effect
• etc.

🎯 Use Cases

Hero Section

@Component({
  template: `
    <sparkle-fall
      [maxSparkles]="100"
      [wrapperStyles]="{ minHeight: '100vh' }"
    >
      <app-hero-content />
    </sparkle-fall>
  `
})
export class HeroComponent {}

Celebration Mode

@Component({
  template: `
    <button (click)="celebrate()">🎉 Celebrate!</button>
    
    <sparkle-fall
      *ngIf="celebrating"
      [sparkles]="['🎉', '🎊', '🎈', '🎆', '✨']"
      [interval]="200"
      [maxSparkles]="100"
      [wrapperStyles]="{
        position: 'fixed',
        inset: 0,
        pointerEvents: 'none',
        zIndex: 10000
      }"
    />
  `
})
export class CelebrationComponent {
  celebrating = false;
  
  celebrate() {
    this.celebrating = true;
    setTimeout(() => this.celebrating = false, 5000);
  }
}

Button Click Effect

@Component({
  template: `
    <button 
      #sparkleBtn
      sparkleFall
      [sparkleFallEnabled]="false"
      [sparkleFallMaxSparkles]="30"
      (click)="handleClick(sparkleBtn)"
    >
      Click Me!
    </button>
  `
})
export class SparkleButton {
  handleClick(directive: any) {
    directive.burst(30);
    setTimeout(() => directive.clear(), 3000);
  }
}

Form Success

@Component({
  template: `
    <form (ngSubmit)="onSubmit()">
      <sparkle-fall
        [enabled]="showSuccess"
        [sparkles]="['✅', '🎉', '✨']"
        [maxSparkles]="50"
      >
        <input type="text" />
        <button type="submit">Submit</button>
      </sparkle-fall>
    </form>
  `
})
export class FormComponent {
  showSuccess = false;
  
  onSubmit() {
    this.showSuccess = true;
    setTimeout(() => this.showSuccess = false, 3000);
  }
}

🔧 Configuration Tips

Performance

// Reduce sparkles on mobile
@Component({
  template: `
    <sparkle-fall
      [maxSparkles]="isMobile ? 20 : 50"
      [interval]="isMobile ? 1200 : 800"
    >
      <app-content />
    </sparkle-fall>
  `
})
export class ResponsiveSparkles {
  isMobile = window.innerWidth < 768;
}

Dynamic Themes

@Component({
  template: `
    <sparkle-fall [sparkles]="currentTheme.sparkles" [colors]="currentTheme.colors">
      <app-content />
    </sparkle-fall>
  `
})
export class ThemedSparkles {
  themes = {
    holiday: {
      sparkles: ['❄️', '🎄', '🎅', '🎁'],
      colors: null
    },
    gold: {
      sparkles: ['●', '◆', '■'],
      colors: ['#FFD700', '#FFA500']
    }
  };
  
  currentTheme = this.themes.holiday;
}

📝 License

MIT

🔗 Links

• SparkleFall Core Library
• Live Demo
• React Version
• NPM Package

Made with ✨ by Theresa Summa