npm - canvasparticles-js - Versions diffs - 3.5.0 → 3.5.3 - Mend

canvasparticles-js 3.5.0 → 3.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -11,6 +11,7 @@ Creating a fun and interactive background. Colors, interaction and gravity can b
 [Showcase](#showcase)<br>
 [Implementation](#implementation)<br>
+[Class instantiation](#class-instantiation)<br>
 [Options](#options)<br>
 [One pager example](#one-pager-example)
@@ -24,13 +25,13 @@ If you dont like reading documentation this website is for you:<br>
 Particles will be drawn onto this `<canvas>` element
 ```html
-<canvas id="canvas-particles"></canvas>
+<canvas id="my-canvas"></canvas>
 ```
 Resize the `<canvas>` so it covers the whole page and place it behind all elements.
 ```css
-#canvas-particles {
+#my-canvas {
   position: fixed;
   top: 0;
   left: 0;
@@ -60,7 +61,7 @@ Inside _initParticles.js_:
 ```js
 import CanvasParticles from 'canvasparticles-js'
-const selector = '#canvas-particles' // Query Selector for the canvas
+const selector = '#my-canvas' // Query Selector for the canvas
 const options = { ... } // See #options
 new CanvasParticles(selector, options).start()
 ```
@@ -99,7 +100,7 @@ Inside _initParticles.js_:
 ```js
 import CanvasParticles from './canvasParticles.mjs'
-const selector = '#canvas-particles' // Query Selector for the canvas
+const selector = '#my-canvas' // Query Selector for the canvas
 const options = { ... } // See #options
 new CanvasParticles(selector, options).start()
 ```
@@ -124,7 +125,7 @@ Add an inline `<script>` element at the very bottom of the `<body>`.
   <script>
     const initParticles = () => {
-      const selector = '#canvas-particles' // Query Selector for the canvas
+      const selector = '#my-canvas' // Query Selector for the canvas
       const options = { ... } // See #options
       new CanvasParticles(selector, options).start()
     }
@@ -141,7 +142,7 @@ Add an inline `<script>` element at the very bottom of the `<body>`.
 ### Start animating
 ```js
-const selector = '#canvas-particles' // Query Selector for the canvas
+const selector = '#my-canvas' // Query Selector for the canvas
 const options = { ... } // See #options
 new CanvasParticles(selector, options).start()
 ```
@@ -152,6 +153,58 @@ new CanvasParticles(selector, options).start()
 const particles = new CanvasParticles(selector, options)
 particles.start()
 particles.stop()
+particles.stop({ clear: false }) // Default: true
+```
+## Class instantiation
+### Valid ways to instantiate `CanvasParticles`
+```js
+const selector = '#my-canvas'
+const options = {}
+const myCanvas = document.querySelector(selector)
+let instance, canvas
+// Basic instantiation
+instance = new CanvasParticles(selector)
+instance = new CanvasParticles(myCanvas)
+// Instantiation with custom options
+instance = new CanvasParticles(selector, options)
+instance = new CanvasParticles(myCanvas, options)
+```
+### Chaining methods
+You can chain .start() for a cleaner syntax:
+```js
+instance = new CanvasParticles(selector).start()
+// Access the canvas directly
+canvas = new CanvasParticles(selector).canvas
+canvas = new CanvasParticles(selector).start().canvas
+```
+### Without chaining
+If you prefer not to chain methods, you can instantiate first and start later:
+```js
+instance = new CanvasParticles(selector)
+instance.start()
+canvas = instance.canvas
+```
+### Incorrect usage
+The following will not return the expected value because `CanvasParticles` only supports method chaining for `.start()`:
+```js
+instance = new CanvasParticles(selector).anyOtherMethod()
+canvas = new CanvasParticles(selector).anyOtherMethod().canvas
 ```
 ## Options
@@ -190,9 +243,10 @@ const options = {
   /** @param {Object} [options.mouse] - Mouse interaction settings. */
   mouse: {
     /** @param {0|1|2} [options.mouse.interactionType=1] - The type of interaction the mouse will have with particles.
-     * 0 = No interaction.
-     * 1 = The mouse can visually shift the particles.
-     * 2 = The mouse can move the particles.
+     *
+     * CanvasParticles.interactionType.NONE = 0 = No interaction.
+     * CanvasParticles.interactionType.SHIFT = 1 = The mouse can visually shift the particles.
+     * CanvasParticles.interactionType.MOVE = 2 = The mouse can move the particles.
      * @note mouse.distRatio should be less than 1 to allow dragging, closer to 0 is easier to drag
      */
     interactionType: 2,
@@ -365,7 +419,7 @@ particles.setOptions(options)
       const options = {
         background: 'hsl(125, 42%, 35%)',
         mouse: {
-          interactionType: 2,
+          interactionType: CanvasParticles.interactionType.MOVE, // === 2
         },
         particles: {
           color: 'rgba(150, 255, 105, 0.95)',

package/canvasParticles.js CHANGED Viewed

@@ -1,5 +1,5 @@
 // Copyright (c) 2022–2025 Kyle Hoeckman, MIT License
-// https://github.com/Khoeckman/canvasParticles/blob/main/LICENSE
+// https://github.com/Khoeckman/canvasparticles-js/blob/main/LICENSE
 'use strict'
 ;((root, factory) =>
@@ -9,36 +9,47 @@
   typeof self !== 'undefined' ? self : this,
   () =>
     class CanvasParticles {
-      static version = '3.5.0'
+      static version = '3.5.3'
-      // Start or stop the animation when the canvas enters or exits the viewport
+      // Mouse interaction with the particles.
+      static interactionType = Object.freeze({
+        NONE: 0, // No interaction
+        SHIFT: 1, // Visually shift the particles
+        MOVE: 2, // Actually move the particles
+      })
+      // Start or stop the animation when the canvas enters or exits the viewport.
       static canvasObserver = new IntersectionObserver(entry => {
         entry.forEach(change => {
-          // CanvasParticles instance of the target canvas
-          const instance = change.target.instance
+          const canvas = change.target
+          const instance = canvas.instance // The 'CanvasParticles' instance bound to 'canvas'.
-          if (change.isIntersecting) instance.options.animation.startOnEnter && instance.start()
-          else instance.options.animation.stopOnLeave && instance.stop({ clear: false })
+          if ((canvas.inViewbox = change.isIntersecting)) instance.options.animation.startOnEnter && instance.start({ auto: true })
+          else instance.options.animation.stopOnLeave && instance.stop({ auto: true, clear: false })
         })
       })
       /**
        * Creates a new CanvasParticles instance.
-       * @param {string} [selector] - The CSS selector for the canvas element.
+       * @param {string} [selector] - The CSS selector to the canvas element or the HTMLCanvasElement itself.
        * @param {Object} [options={}] - Object structure: https://github.com/Khoeckman/canvasParticles?tab=readme-ov-file#options
        */
       constructor(selector, options = {}) {
-        // Find and initialize canvas
-        if (typeof selector !== 'string') throw new TypeError('selector is not a string')
-        this.canvas = document.querySelector(selector)
-        if (!(this.canvas instanceof HTMLCanvasElement)) throw new Error('selector does not point to a canvas')
+        // Find the HTMLCanvasElement and assign it to 'this.canvas'.
+        if (selector instanceof HTMLCanvasElement) this.canvas = selector
+        else {
+          if (typeof selector !== 'string') throw new TypeError('selector is not a string and neither a HTMLCanvasElement itself')
-        this.canvas.instance = this
+          this.canvas = document.querySelector(selector)
+          if (!(this.canvas instanceof HTMLCanvasElement)) throw new Error('selector does not point to a canvas')
+        }
+        this.canvas.instance = this // Circular assignment to find the instance bound to this canvas inside the static 'canvasObserver' callback.
+        this.canvas.inViewbox = true
-        // Get 2d drawing functions
+        // Get 2d drawing methods.
         this.ctx = this.canvas.getContext('2d')
+        this.enableAnimating = false
         this.animating = false
         this.particles = []
         this.setOptions(options)
@@ -48,19 +59,16 @@
         this.#setupEventHandlers()
       }
-      // Helper function
-      #defaultIfNaN(value, defaultValue) {
-        return isNaN(+value) ? defaultValue : +value
-      }
       #setupEventHandlers() {
         const updateMousePos = event => {
-          if (!this.animating) return
+          if (!this.enableAnimating) return
           if (event instanceof MouseEvent) {
             this.clientX = event.clientX
             this.clientY = event.clientY
           }
+          // On scroll, the mouse position remains the same, but since the canvas position changes, 'left' and 'top' must be recalculated.
           const { left, top } = this.canvas.getBoundingClientRect()
           this.mouseX = this.clientX - left
           this.mouseY = this.clientY - top
@@ -94,7 +102,7 @@
       }
       /**
-       * Update the target number of particles based on the current canvas size and 'options.particles.ppm'
+       * Update the target number of particles based on the current canvas size and 'options.particles.ppm'.
        * Capped at 'options.particles.max'.
        *
        * @private
@@ -151,7 +159,7 @@
       #updateParticleBounds() {
         this.particles.map(
           particle =>
-            // Within these bounds the particle is considered visible
+            // Within these bounds the particle is considered visible.
             (particle.bounds = {
               top: -particle.size,
               right: this.canvas.width + particle.size,
@@ -180,7 +188,7 @@
           for (let i = 0; i < len; i++) {
             for (let j = i + 1; j < len; j++) {
-              // Code in this scope runs [particles ** 2 / 2] times!
+              // Code in this scope runs [particleCount ** 2 / 2] times!
               const particleA = this.particles[i]
               const particleB = this.particles[j]
@@ -192,7 +200,7 @@
               let angle, grav
               if (dist < maxRepulsiveDist) {
-                // Apply repulsive force on all particles close together
+                // Apply repulsive force on all particles closer than 'dist' / 2.
                 angle = Math.atan2(particleB.posY - particleA.posY, particleB.posX - particleA.posX)
                 grav = (1 / dist) ** 1.8
                 const gravMult = Math.min(maxGrav, grav * gravRepulsiveMult)
@@ -206,7 +214,7 @@
               if (!isPullingEnabled) continue
-              // Apply pulling force on all particles not close together
+              // Apply pulling force on all particles.
               if (angle === undefined) {
                 angle = Math.atan2(particleB.posY - particleA.posY, particleB.posX - particleA.posX)
                 grav = (1 / dist) ** 1.8
@@ -231,7 +239,7 @@
        * */
       #updateParticles() {
         for (let particle of this.particles) {
-          // Moving the particle
+          // Slightly, randomly change the particle's direction and move it in that direction.
           particle.dir = (particle.dir + Math.random() * this.options.particles.rotationSpeed * 2 - this.options.particles.rotationSpeed) % (2 * Math.PI)
           particle.velX *= this.options.gravity.friction
           particle.velY *= this.options.gravity.friction
@@ -241,8 +249,8 @@
           const distX = particle.posX + this.offX - this.mouseX
           const distY = particle.posY + this.offY - this.mouseY
-          // Mouse events
-          if (this.options.mouse.interactionType !== 0) {
+          // If the 'interactionType' is not 'NONE', calculate how much to move the particle away from the mouse.
+          if (this.options.mouse.interactionType !== CanvasParticles.interactionType.NONE) {
             const distRatio = this.options.mouse.connectDist / Math.hypot(distX, distY)
             if (this.options.mouse.distRatio < distRatio) {
@@ -253,18 +261,20 @@
               particle.offY -= particle.offY / 4
             }
           }
+          // Visually shift the particles
           particle.x = particle.posX + particle.offX
           particle.y = particle.posY + particle.offY
-          if (this.options.mouse.interactionType === 2) {
-            // Make the mouse actually move the particles
+          // Actually move the particles if 'interactionType' is 'MOVE'.
+          if (this.options.mouse.interactionType === CanvasParticles.interactionType.MOVE) {
             particle.posX = particle.x
             particle.posY = particle.y
           }
           particle.x += this.offX
           particle.y += this.offY
-          particle.gridPos = this.#gridPos(particle) // The location of the particle relative to the visible center of the canvas
+          particle.gridPos = this.#gridPos(particle)
           particle.isVisible = particle.gridPos.x === 1 && particle.gridPos.y === 1
         }
       }
@@ -307,10 +317,10 @@
        * @returns {boolean} - True if the line crosses the visible center, false otherwise.
        */
       #isLineVisible(particleA, particleB) {
-        // Visible if either particle is in the center
+        // Visible if either particle is in the center.
         if (particleA.isVisible || particleB.isVisible) return true
-        // Not visible if both particles are in the same vertical or horizontal line but outside the center
+        // Not visible if both particles are in the same vertical or horizontal line but outside the center.
         return !(
           (particleA.gridPos.x === particleB.gridPos.x && particleA.gridPos.x !== 1) ||
           (particleA.gridPos.y === particleB.gridPos.y && particleA.gridPos.y !== 1)
@@ -319,11 +329,11 @@
       /**
        * Precomputes and caches stroke style strings for a given base color and all possible alpha values (0–255).
-       * This is necessary because the rendering process involves up to [particles ** 2 / 2] lookups per frame.
+       * This is necessary because the rendering process involves up to [particleCount ** 2 / 2] lookups per frame.
        *
        * @private
-       * @param {string} color - The base color in the format `#rrggbb`.
-       * @returns {Object} - A lookup table mapping each alpha value (0–255) to its corresponding stroke style string in the format `#rrggbbaa`.
+       * @param {string} color - The base color in the format '#rrggbb'.
+       * @returns {Object} - A lookup table mapping each alpha value (0–255) to its corresponding stroke style string in the format '#rrggbbaa'.
        *
        * @example
        * const strokeStyleTable = this.#generateStrokeStyleTable("#abcdef");
@@ -331,9 +341,8 @@
        * strokeStyleTable[255] -> "#abcdefff"
        *
        * Notes:
-       * - This function precomputes all possible stroke styles by appending a two-character
-       *   hexadecimal alpha value (0x00–0xFF) to the base color.
-       * - The table is stored in `this.strokeStyleTable` for quick lookups.
+       * - This function precomputes all possible stroke styles by appending a two-character hexadecimal alpha value (0x00–0xFF) to the base color.
+       * - The table is stored in 'this.strokeStyleTable' for quick lookups.
        */
       #generateStrokeStyleTable(color) {
         const table = {}
@@ -354,7 +363,8 @@
       #renderParticles() {
         for (let particle of this.particles) {
           if (particle.isVisible) {
-            // Draw the particle as a square if the size is smaller than 1 pixel (±183% faster than drawing only circles, using default settings)
+            // Draw the particle as a square if the size is smaller than 1 pixel.
+            // This is ±183% faster than drawing all particle's as circles.
             if (particle.size > 1) {
               // Draw circle
               this.ctx.beginPath()
@@ -362,7 +372,7 @@
               this.ctx.fill()
               this.ctx.closePath()
             } else {
-              // Draw square (±335% faster than circle)
+              // Draw square
               this.ctx.fillRect(particle.x - particle.size, particle.y - particle.size, particle.size * 2, particle.size * 2)
             }
           }
@@ -384,22 +394,23 @@
           let particleWork = 0
           for (let j = i + 1; j < len; j++) {
-            // Code in this scope runs [particles ** 2 / 2] times!
+            // Code in this scope runs [particleCount ** 2 / 2] times!
             const particleA = this.particles[i]
             const particleB = this.particles[j]
             if (!(drawAll || this.#isLineVisible(particleA, particleB))) continue
-            // Draw a line only if will be visible
+            // Draw a line only if it's visible.
             const distX = particleA.x - particleB.x
             const distY = particleA.y - particleB.y
             const dist = Math.sqrt(distX * distX + distY * distY)
+            // Don't connect the 2 particles with a line if their distance is greater than 'options.particles.connectDist'.
             if (dist > this.options.particles.connectDist) continue
-            // Connect the 2 particles with a line only if the distance is small enough
-            // Calculate the transparency of the line and lookup the stroke style
+            // Calculate the transparency of the line and lookup the stroke style.
+            // This is the heaviest task of the entire animation process.
             if (dist > this.options.particles.connectDist / 2) {
               const alpha = ~~(Math.min(this.options.particles.connectDist / dist - 1, 1) * this.options.particles.opacity)
               this.ctx.strokeStyle = this.strokeStyleTable[alpha]
@@ -407,12 +418,13 @@
               this.ctx.strokeStyle = this.options.particles.colorWithAlpha
             }
-            // Draw the line
+            // Draw the line.
             this.ctx.beginPath()
             this.ctx.moveTo(particleA.x, particleA.y)
             this.ctx.lineTo(particleB.x, particleB.y)
             this.ctx.stroke()
+            // Stop drawing lines from this particles if it has already drawn to many.
             if ((particleWork += dist) >= maxWorkPerParticle) break
           }
         }
@@ -457,22 +469,39 @@
       /**
        * Starts the particle animation.
-       * Does nothing if already animating.
        *
-       * @returns {CanvasParticles} - The current instance.
+       * - If the animation is already running, do nothing.
+       * - If the canvas is not within the viewbox and 'startOnEnter' is enabled, animation will be stopped until it enters the viewbox.
+       *
+       * @param {Object} [options] - Optional configuration for starting the animation.
+       * @param {boolean} [options.auto] - If true, indicates that the request comes from 'CanvasParticles.canvasObserver'.
+       * @returns {CanvasParticles} The current instance for method chaining.
        */
-      start() {
-        if (!this.animating) {
+      start(options) {
+        if (!this.animating && (!options?.auto || this.enableAnimating)) {
+          this.enableAnimating = true
           this.animating = true
           requestAnimationFrame(() => this.#animation())
         }
+        // Stop animating because it will start automatically once the canvas enters the viewbox.
+        if (!this.canvas.inViewbox && this.options.animation.startOnEnter) this.animating = false
         return this
       }
       /**
-       * Stops the particle animation and clears the canvas.
+       * Stops the particle animation and optionally clears the canvas.
+       *
+       * - If 'options.clear' is not strictly false, the canvas will be cleared.
+       *
+       * @param {Object} [options] - Optional configuration for stopping the animation.
+       * @param {boolean} [options.auto] - If true, indicates that the request comes from 'CanvasParticles.canvasObserver'.
+       * @param {boolean} [options.clear] - If strictly false, prevents clearing the canvas-.
+       * @returns {boolean} `true` when the animation is successfully stopped.
        */
       stop(options) {
+        if (!options?.auto) this.enableAnimating = false
         this.animating = false
         if (options?.clear !== false) this.canvas.width = this.canvas.width
@@ -488,9 +517,10 @@
        * @param {Object} options - Object structure: https://github.com/Khoeckman/canvasParticles?tab=readme-ov-file#options
        */
       setOptions(options) {
-        const parse = this.#defaultIfNaN
+        // Returns 'defaultValue' if 'value' is NaN, else returns 'value'.
+        const parse = (value, defaultValue) => (isNaN(+value) ? defaultValue : +value)
-        // Format and store options
+        // Format or default all options.
         this.options = {
           background: options.background ?? false,
           framesPerUpdate: parse(Math.max(1, parseInt(options.framesPerUpdate)), 1),
@@ -527,12 +557,15 @@
       }
       /**
-       * Set canvas background.
-       * @param {string} background - The style of the background. Can be any CSS supported background format.
+       * Sets the canvas background.
+       *
+       * @param {string} background - The style of the background. Can be any CSS-supported background value.
+       * @throws {TypeError} If background is not a string.
        */
       setBackground(background) {
-        if (typeof background === 'string') return (this.canvas.style.background = this.options.background = background), true
-        return false
+        if (background === false) return
+        if (typeof background !== 'string') throw new TypeError('background is not a string')
+        this.canvas.style.background = this.options.background = background
       }
       /**
@@ -542,7 +575,7 @@
        * @example 0.8 connectDistMult * 150 particles.connectDistance = 120 pixels
        */
       setMouseConnectDistMult(connectDistMult) {
-        this.options.mouse.connectDist = this.options.particles.connectDist * this.#defaultIfNaN(connectDistMult, 2 / 3)
+        this.options.mouse.connectDist = this.options.particles.connectDist * (isNaN(connectDistMult) ? 2 / 3 : connectDistMult)
       }
       /**
@@ -558,16 +591,17 @@
           // JavaScript's 'ctx.fillStyle' ensures the color will otherwise be in rgba format (e.g., "rgba(136, 244, 255, 0.25)")
           // Extract the alpha value (0.25) from the rgba string, scale it to the range 0x00 to 0xff,
-          // and convert it to an integer. This value represents the opacity as a 2-character hex string
+          // and convert it to an integer. This value represents the opacity as a 2-character hex string.
           this.options.particles.opacity = ~~(this.ctx.fillStyle.split(',').at(-1).slice(1, -1) * 255)
-          // Example: extract 136, 244 and 255 from rgba(136, 244, 255, 0.25) and convert to hexadecimal '#rrggbb' format
+          // Example: extract 136, 244 and 255 from rgba(136, 244, 255, 0.25) and convert to hexadecimal '#rrggbb' format.
           this.ctx.fillStyle = this.ctx.fillStyle.split(',').slice(0, -1).join(',') + ', 1)'
         }
         this.options.particles.color = this.ctx.fillStyle
         this.options.particles.colorWithAlpha = this.options.particles.color + this.options.particles.opacity.toString(16)
-        this.strokeStyleTable = this.#generateStrokeStyleTable(this.options.particles.color) // Recalculate the stroke style table
+        // Recalculate the stroke style table.
+        this.strokeStyleTable = this.#generateStrokeStyleTable(this.options.particles.color)
       }
     }
 )

package/canvasParticles.mjs CHANGED Viewed

@@ -1,37 +1,48 @@
 // Copyright (c) 2022–2025 Kyle Hoeckman, MIT License
-// https://github.com/Khoeckman/canvasParticles/blob/main/LICENSE
+// https://github.com/Khoeckman/canvasparticles-js/blob/main/LICENSE
 export default class CanvasParticles {
-  static version = '3.5.0'
+  static version = '3.5.3'
-  // Start or stop the animation when the canvas enters or exits the viewport
+  // Mouse interaction with the particles.
+  static interactionType = Object.freeze({
+    NONE: 0, // No interaction
+    SHIFT: 1, // Visually shift the particles
+    MOVE: 2, // Actually move the particles
+  })
+  // Start or stop the animation when the canvas enters or exits the viewport.
   static canvasObserver = new IntersectionObserver(entry => {
     entry.forEach(change => {
-      // CanvasParticles instance of the target canvas
-      const instance = change.target.instance
+      const canvas = change.target
+      const instance = canvas.instance // The 'CanvasParticles' instance bound to 'canvas'.
-      if (change.isIntersecting) instance.options.animation.startOnEnter && instance.start()
-      else instance.options.animation.stopOnLeave && instance.stop({ clear: false })
+      if ((canvas.inViewbox = change.isIntersecting)) instance.options.animation.startOnEnter && instance.start({ auto: true })
+      else instance.options.animation.stopOnLeave && instance.stop({ auto: true, clear: false })
     })
   })
   /**
    * Creates a new CanvasParticles instance.
-   * @param {string} [selector] - The CSS selector for the canvas element.
+   * @param {string} [selector] - The CSS selector to the canvas element or the HTMLCanvasElement itself.
    * @param {Object} [options={}] - Object structure: https://github.com/Khoeckman/canvasParticles?tab=readme-ov-file#options
    */
   constructor(selector, options = {}) {
-    // Find and initialize canvas
-    if (typeof selector !== 'string') throw new TypeError('selector is not a string')
-    this.canvas = document.querySelector(selector)
-    if (!(this.canvas instanceof HTMLCanvasElement)) throw new Error('selector does not point to a canvas')
+    // Find the HTMLCanvasElement and assign it to 'this.canvas'.
+    if (selector instanceof HTMLCanvasElement) this.canvas = selector
+    else {
+      if (typeof selector !== 'string') throw new TypeError('selector is not a string and neither a HTMLCanvasElement itself')
-    this.canvas.instance = this
+      this.canvas = document.querySelector(selector)
+      if (!(this.canvas instanceof HTMLCanvasElement)) throw new Error('selector does not point to a canvas')
+    }
+    this.canvas.instance = this // Circular assignment to find the instance bound to this canvas inside the static 'canvasObserver' callback.
+    this.canvas.inViewbox = true
-    // Get 2d drawing functions
+    // Get 2d drawing methods.
     this.ctx = this.canvas.getContext('2d')
+    this.enableAnimating = false
     this.animating = false
     this.particles = []
     this.setOptions(options)
@@ -41,19 +52,16 @@ export default class CanvasParticles {
     this.#setupEventHandlers()
   }
-  // Helper function
-  #defaultIfNaN(value, defaultValue) {
-    return isNaN(+value) ? defaultValue : +value
-  }
   #setupEventHandlers() {
     const updateMousePos = event => {
-      if (!this.animating) return
+      if (!this.enableAnimating) return
       if (event instanceof MouseEvent) {
         this.clientX = event.clientX
         this.clientY = event.clientY
       }
+      // On scroll, the mouse position remains the same, but since the canvas position changes, 'left' and 'top' must be recalculated.
       const { left, top } = this.canvas.getBoundingClientRect()
       this.mouseX = this.clientX - left
       this.mouseY = this.clientY - top
@@ -87,7 +95,7 @@ export default class CanvasParticles {
   }
   /**
-   * Update the target number of particles based on the current canvas size and 'options.particles.ppm'
+   * Update the target number of particles based on the current canvas size and 'options.particles.ppm'.
    * Capped at 'options.particles.max'.
    *
    * @private
@@ -144,7 +152,7 @@ export default class CanvasParticles {
   #updateParticleBounds() {
     this.particles.map(
       particle =>
-        // Within these bounds the particle is considered visible
+        // Within these bounds the particle is considered visible.
         (particle.bounds = {
           top: -particle.size,
           right: this.canvas.width + particle.size,
@@ -173,7 +181,7 @@ export default class CanvasParticles {
       for (let i = 0; i < len; i++) {
         for (let j = i + 1; j < len; j++) {
-          // Code in this scope runs [particles ** 2 / 2] times!
+          // Code in this scope runs [particleCount ** 2 / 2] times!
           const particleA = this.particles[i]
           const particleB = this.particles[j]
@@ -185,7 +193,7 @@ export default class CanvasParticles {
           let angle, grav
           if (dist < maxRepulsiveDist) {
-            // Apply repulsive force on all particles close together
+            // Apply repulsive force on all particles closer than 'dist' / 2.
             angle = Math.atan2(particleB.posY - particleA.posY, particleB.posX - particleA.posX)
             grav = (1 / dist) ** 1.8
             const gravMult = Math.min(maxGrav, grav * gravRepulsiveMult)
@@ -199,7 +207,7 @@ export default class CanvasParticles {
           if (!isPullingEnabled) continue
-          // Apply pulling force on all particles not close together
+          // Apply pulling force on all particles.
           if (angle === undefined) {
             angle = Math.atan2(particleB.posY - particleA.posY, particleB.posX - particleA.posX)
             grav = (1 / dist) ** 1.8
@@ -224,7 +232,7 @@ export default class CanvasParticles {
    * */
   #updateParticles() {
     for (let particle of this.particles) {
-      // Moving the particle
+      // Slightly, randomly change the particle's direction and move it in that direction.
       particle.dir = (particle.dir + Math.random() * this.options.particles.rotationSpeed * 2 - this.options.particles.rotationSpeed) % (2 * Math.PI)
       particle.velX *= this.options.gravity.friction
       particle.velY *= this.options.gravity.friction
@@ -234,8 +242,8 @@ export default class CanvasParticles {
       const distX = particle.posX + this.offX - this.mouseX
       const distY = particle.posY + this.offY - this.mouseY
-      // Mouse events
-      if (this.options.mouse.interactionType !== 0) {
+      // If the 'interactionType' is not 'NONE', calculate how much to move the particle away from the mouse.
+      if (this.options.mouse.interactionType !== CanvasParticles.interactionType.NONE) {
         const distRatio = this.options.mouse.connectDist / Math.hypot(distX, distY)
         if (this.options.mouse.distRatio < distRatio) {
@@ -246,18 +254,20 @@ export default class CanvasParticles {
           particle.offY -= particle.offY / 4
         }
       }
+      // Visually shift the particles
       particle.x = particle.posX + particle.offX
       particle.y = particle.posY + particle.offY
-      if (this.options.mouse.interactionType === 2) {
-        // Make the mouse actually move the particles
+      // Actually move the particles if 'interactionType' is 'MOVE'.
+      if (this.options.mouse.interactionType === CanvasParticles.interactionType.MOVE) {
         particle.posX = particle.x
         particle.posY = particle.y
       }
       particle.x += this.offX
       particle.y += this.offY
-      particle.gridPos = this.#gridPos(particle) // The location of the particle relative to the visible center of the canvas
+      particle.gridPos = this.#gridPos(particle)
       particle.isVisible = particle.gridPos.x === 1 && particle.gridPos.y === 1
     }
   }
@@ -300,10 +310,10 @@ export default class CanvasParticles {
    * @returns {boolean} - True if the line crosses the visible center, false otherwise.
    */
   #isLineVisible(particleA, particleB) {
-    // Visible if either particle is in the center
+    // Visible if either particle is in the center.
     if (particleA.isVisible || particleB.isVisible) return true
-    // Not visible if both particles are in the same vertical or horizontal line but outside the center
+    // Not visible if both particles are in the same vertical or horizontal line but outside the center.
     return !(
       (particleA.gridPos.x === particleB.gridPos.x && particleA.gridPos.x !== 1) ||
       (particleA.gridPos.y === particleB.gridPos.y && particleA.gridPos.y !== 1)
@@ -312,11 +322,11 @@ export default class CanvasParticles {
   /**
    * Precomputes and caches stroke style strings for a given base color and all possible alpha values (0–255).
-   * This is necessary because the rendering process involves up to [particles ** 2 / 2] lookups per frame.
+   * This is necessary because the rendering process involves up to [particleCount ** 2 / 2] lookups per frame.
    *
    * @private
-   * @param {string} color - The base color in the format `#rrggbb`.
-   * @returns {Object} - A lookup table mapping each alpha value (0–255) to its corresponding stroke style string in the format `#rrggbbaa`.
+   * @param {string} color - The base color in the format '#rrggbb'.
+   * @returns {Object} - A lookup table mapping each alpha value (0–255) to its corresponding stroke style string in the format '#rrggbbaa'.
    *
    * @example
    * const strokeStyleTable = this.#generateStrokeStyleTable("#abcdef");
@@ -324,9 +334,8 @@ export default class CanvasParticles {
    * strokeStyleTable[255] -> "#abcdefff"
    *
    * Notes:
-   * - This function precomputes all possible stroke styles by appending a two-character
-   *   hexadecimal alpha value (0x00–0xFF) to the base color.
-   * - The table is stored in `this.strokeStyleTable` for quick lookups.
+   * - This function precomputes all possible stroke styles by appending a two-character hexadecimal alpha value (0x00–0xFF) to the base color.
+   * - The table is stored in 'this.strokeStyleTable' for quick lookups.
    */
   #generateStrokeStyleTable(color) {
     const table = {}
@@ -347,7 +356,8 @@ export default class CanvasParticles {
   #renderParticles() {
     for (let particle of this.particles) {
       if (particle.isVisible) {
-        // Draw the particle as a square if the size is smaller than 1 pixel (±183% faster than drawing only circles, using default settings)
+        // Draw the particle as a square if the size is smaller than 1 pixel.
+        // This is ±183% faster than drawing all particle's as circles.
         if (particle.size > 1) {
           // Draw circle
           this.ctx.beginPath()
@@ -355,7 +365,7 @@ export default class CanvasParticles {
           this.ctx.fill()
           this.ctx.closePath()
         } else {
-          // Draw square (±335% faster than circle)
+          // Draw square
           this.ctx.fillRect(particle.x - particle.size, particle.y - particle.size, particle.size * 2, particle.size * 2)
         }
       }
@@ -377,22 +387,23 @@ export default class CanvasParticles {
       let particleWork = 0
       for (let j = i + 1; j < len; j++) {
-        // Code in this scope runs [particles ** 2 / 2] times!
+        // Code in this scope runs [particleCount ** 2 / 2] times!
         const particleA = this.particles[i]
         const particleB = this.particles[j]
         if (!(drawAll || this.#isLineVisible(particleA, particleB))) continue
-        // Draw a line only if will be visible
+        // Draw a line only if it's visible.
         const distX = particleA.x - particleB.x
         const distY = particleA.y - particleB.y
         const dist = Math.sqrt(distX * distX + distY * distY)
+        // Don't connect the 2 particles with a line if their distance is greater than 'options.particles.connectDist'.
         if (dist > this.options.particles.connectDist) continue
-        // Connect the 2 particles with a line only if the distance is small enough
-        // Calculate the transparency of the line and lookup the stroke style
+        // Calculate the transparency of the line and lookup the stroke style.
+        // This is the heaviest task of the entire animation process.
         if (dist > this.options.particles.connectDist / 2) {
           const alpha = ~~(Math.min(this.options.particles.connectDist / dist - 1, 1) * this.options.particles.opacity)
           this.ctx.strokeStyle = this.strokeStyleTable[alpha]
@@ -400,12 +411,13 @@ export default class CanvasParticles {
           this.ctx.strokeStyle = this.options.particles.colorWithAlpha
         }
-        // Draw the line
+        // Draw the line.
         this.ctx.beginPath()
         this.ctx.moveTo(particleA.x, particleA.y)
         this.ctx.lineTo(particleB.x, particleB.y)
         this.ctx.stroke()
+        // Stop drawing lines from this particles if it has already drawn to many.
         if ((particleWork += dist) >= maxWorkPerParticle) break
       }
     }
@@ -450,22 +462,39 @@ export default class CanvasParticles {
   /**
    * Starts the particle animation.
-   * Does nothing if already animating.
    *
-   * @returns {CanvasParticles} - The current instance.
+   * - If the animation is already running, do nothing.
+   * - If the canvas is not within the viewbox and 'startOnEnter' is enabled, animation will be stopped until it enters the viewbox.
+   *
+   * @param {Object} [options] - Optional configuration for starting the animation.
+   * @param {boolean} [options.auto] - If true, indicates that the request comes from 'CanvasParticles.canvasObserver'.
+   * @returns {CanvasParticles} The current instance for method chaining.
    */
-  start() {
-    if (!this.animating) {
+  start(options) {
+    if (!this.animating && (!options?.auto || this.enableAnimating)) {
+      this.enableAnimating = true
       this.animating = true
       requestAnimationFrame(() => this.#animation())
     }
+    // Stop animating because it will start automatically once the canvas enters the viewbox.
+    if (!this.canvas.inViewbox && this.options.animation.startOnEnter) this.animating = false
     return this
   }
   /**
-   * Stops the particle animation and clears the canvas.
+   * Stops the particle animation and optionally clears the canvas.
+   *
+   * - If 'options.clear' is not strictly false, the canvas will be cleared.
+   *
+   * @param {Object} [options] - Optional configuration for stopping the animation.
+   * @param {boolean} [options.auto] - If true, indicates that the request comes from 'CanvasParticles.canvasObserver'.
+   * @param {boolean} [options.clear] - If strictly false, prevents clearing the canvas-.
+   * @returns {boolean} `true` when the animation is successfully stopped.
    */
   stop(options) {
+    if (!options?.auto) this.enableAnimating = false
     this.animating = false
     if (options?.clear !== false) this.canvas.width = this.canvas.width
@@ -481,9 +510,10 @@ export default class CanvasParticles {
    * @param {Object} options - Object structure: https://github.com/Khoeckman/canvasParticles?tab=readme-ov-file#options
    */
   setOptions(options) {
-    const parse = this.#defaultIfNaN
+    // Returns 'defaultValue' if 'value' is NaN, else returns 'value'.
+    const parse = (value, defaultValue) => (isNaN(+value) ? defaultValue : +value)
-    // Format and store options
+    // Format or default all options.
     this.options = {
       background: options.background ?? false,
       framesPerUpdate: parse(Math.max(1, parseInt(options.framesPerUpdate)), 1),
@@ -520,12 +550,15 @@ export default class CanvasParticles {
   }
   /**
-   * Set canvas background.
-   * @param {string} background - The style of the background. Can be any CSS supported background format.
+   * Sets the canvas background.
+   *
+   * @param {string} background - The style of the background. Can be any CSS-supported background value.
+   * @throws {TypeError} If background is not a string.
    */
   setBackground(background) {
-    if (typeof background === 'string') return (this.canvas.style.background = this.options.background = background), true
-    return false
+    if (background === false) return
+    if (typeof background !== 'string') throw new TypeError('background is not a string')
+    this.canvas.style.background = this.options.background = background
   }
   /**
@@ -535,7 +568,7 @@ export default class CanvasParticles {
    * @example 0.8 connectDistMult * 150 particles.connectDistance = 120 pixels
    */
   setMouseConnectDistMult(connectDistMult) {
-    this.options.mouse.connectDist = this.options.particles.connectDist * this.#defaultIfNaN(connectDistMult, 2 / 3)
+    this.options.mouse.connectDist = this.options.particles.connectDist * (isNaN(connectDistMult) ? 2 / 3 : connectDistMult)
   }
   /**
@@ -551,15 +584,16 @@ export default class CanvasParticles {
       // JavaScript's 'ctx.fillStyle' ensures the color will otherwise be in rgba format (e.g., "rgba(136, 244, 255, 0.25)")
       // Extract the alpha value (0.25) from the rgba string, scale it to the range 0x00 to 0xff,
-      // and convert it to an integer. This value represents the opacity as a 2-character hex string
+      // and convert it to an integer. This value represents the opacity as a 2-character hex string.
       this.options.particles.opacity = ~~(this.ctx.fillStyle.split(',').at(-1).slice(1, -1) * 255)
-      // Example: extract 136, 244 and 255 from rgba(136, 244, 255, 0.25) and convert to hexadecimal '#rrggbb' format
+      // Example: extract 136, 244 and 255 from rgba(136, 244, 255, 0.25) and convert to hexadecimal '#rrggbb' format.
       this.ctx.fillStyle = this.ctx.fillStyle.split(',').slice(0, -1).join(',') + ', 1)'
     }
     this.options.particles.color = this.ctx.fillStyle
     this.options.particles.colorWithAlpha = this.options.particles.color + this.options.particles.opacity.toString(16)
-    this.strokeStyleTable = this.#generateStrokeStyleTable(this.options.particles.color) // Recalculate the stroke style table
+    // Recalculate the stroke style table.
+    this.strokeStyleTable = this.#generateStrokeStyleTable(this.options.particles.color)
   }
 }

package/package.json CHANGED Viewed

@@ -1,59 +1,56 @@
-{
-  "name": "canvasparticles-js",
-  "version": "3.5.0",
-  "description": "In an HTML canvas, a bunch of interactive particles connected with lines when they approach each other.",
-  "main": "canvasParticles.js",
-  "module": "canvasParticles.mjs",
-  "types": "canvasParticles.d.ts",
-  "type": "module",
-  "files": [
-    "./canvasparticles.d.ts",
-    "./canvasParticles.js",
-    "./canvasParticles.mjs"
-  ],
-  "exports": {
-    ".": {
-      "require": "./canvasParticles.js",
-      "import": "./canvasParticles.mjs"
-    }
-  },
-  "engines": {
-    "node": ">=14"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Khoeckman/canvasParticles.git"
-  },
-  "author": "Kyle Hoeckman",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/Khoeckman/canvasParticles/issues"
-  },
-  "homepage": "https://canvasparticleshomepage.onrender.com/",
-  "keywords": [
-    "front-end",
-    "frontend",
-    "canvas",
-    "particle",
-    "particles",
-    "jsparticles",
-    "js-particles",
-    "particles.js",
-    "particles-js",
-    "xparticles",
-    "background",
-    "animation",
-    "animated",
-    "interactive",
-    "interaction",
-    "web",
-    "webdesign",
-    "web-design",
-    "javascript",
-    "js",
-    "ecmascript",
-    "module",
-    "html5",
-    "html"
-  ]
-}
+{
+  "name": "canvasparticles-js",
+  "version": "3.5.3",
+  "description": "In an HTML canvas, a bunch of interactive particles connected with lines when they approach each other.",
+  "main": "canvasParticles.js",
+  "module": "canvasParticles.mjs",
+  "types": "canvasParticles.d.ts",
+  "type": "module",
+  "files": [
+    "./canvasparticles.d.ts",
+    "./canvasParticles.js",
+    "./canvasParticles.mjs"
+  ],
+  "exports": {
+    ".": {
+      "require": "./canvasParticles.js",
+      "import": "./canvasParticles.mjs"
+    }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Khoeckman/canvasparticles-js.git"
+  },
+  "author": "Kyle Hoeckman",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/Khoeckman/canvasparticles-js/issues"
+  },
+  "homepage": "https://canvasparticleshomepage.onrender.com/",
+  "keywords": [
+    "front-end",
+    "frontend",
+    "canvas",
+    "particle",
+    "particles",
+    "jsparticles",
+    "js-particles",
+    "particles.js",
+    "particles-js",
+    "xparticles",
+    "background",
+    "animation",
+    "animated",
+    "interactive",
+    "interaction",
+    "web",
+    "webdesign",
+    "web-design",
+    "javascript",
+    "js",
+    "ecmascript",
+    "module",
+    "html5",
+    "html"
+  ]
+}