@uibit/particles 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 UIBit Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# Particles
+
+[Interactive Demonstration](https://rawlings.github.io/uibit/components/particles)
+
+Particles provides an interactive canvas-based animation element. It renders dynamic background visuals across multiple presets—including floating nodes, snowfall, rainfall, matrix streams, vortexes, and connection grids—and supports interactive mouse proximity effects.
+
+## Value Delivery
+
+- **Immersive Backgrounds** – Adds visual depth and sophisticated atmosphere to hero sections, landers, or empty states.
+- **Micro-Interactions** – Responsive to mouse hover with options to attract, repel, or grab elements, increasing user engagement.
+- **Resource Efficient** – Utilizes requestAnimationFrame loop and high-performance HTML5 Canvas APIs to maintain clean rendering performance and steady frame rates.
+
+## Ideal Applications
+
+- **Hero & Landing Pages** – Premium background textures that sit beneath text titles and call-to-actions.
+- **Loading & State Screens** – Keeps the user engaged during asynchronous operations or application setups.
+- **Exhibits & Interactive Portfolios** – Creative visual backdrops that react to client interaction.
+
+## Further Information
+
+Detailed design guidelines, customizable attributes, and integration examples are available on our documentation site.
+
+## Changelog
+
+Please see the [Changelog](CHANGELOG.md) for version history.

package/custom-elements.json

@@ -0,0 +1,447 @@
+{
+  "schemaVersion": "1.0.0",
+  "readme": "",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "src/index.ts",
+      "declarations": [],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "default",
+          "declaration": {
+            "name": "default",
+            "module": "./particles"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "Particles",
+          "declaration": {
+            "name": "Particles",
+            "module": "./particles"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "Particle",
+          "declaration": {
+            "name": "Particle",
+            "module": "./types"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "ParticleHoverEffect",
+          "declaration": {
+            "name": "ParticleHoverEffect",
+            "module": "./types"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "EffectParticlesConfig",
+          "declaration": {
+            "name": "EffectParticlesConfig",
+            "module": "./types"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/particles.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "An interactive canvas effect element. Creates dynamic background visuals\nacross many modes: particles, abstract art, grids, flow fields, and more.",
+          "name": "Particles",
+          "cssProperties": [
+            {
+              "description": "Space or comma-separated list of colors",
+              "name": "--uibit-particles-color",
+              "default": "#6b7280"
+            },
+            {
+              "description": "Color of connecting lines",
+              "name": "--uibit-particles-line-color",
+              "default": "#e5e7eb"
+            },
+            {
+              "description": "Opacity of the canvas overlay",
+              "name": "--uibit-particles-opacity",
+              "default": "1"
+            },
+            {
+              "description": "Minimum particle size",
+              "name": "--uibit-particles-min-size",
+              "default": "0.0625rem"
+            },
+            {
+              "description": "Maximum particle size",
+              "name": "--uibit-particles-max-size",
+              "default": "0.1875rem"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "count",
+              "type": {
+                "text": "number"
+              },
+              "default": "50",
+              "description": "Number of particles / elements in the field",
+              "attribute": "count"
+            },
+            {
+              "kind": "field",
+              "name": "speed",
+              "type": {
+                "text": "number"
+              },
+              "default": "1",
+              "description": "Speed multiplier",
+              "attribute": "speed"
+            },
+            {
+              "kind": "field",
+              "name": "mode",
+              "type": {
+                "text": "ParticleMode"
+              },
+              "default": "'float'",
+              "description": "Animation mode.\n'float' | 'snow' | 'rain' | 'neural' | 'matrix' |\n'wave' | 'vortex' | 'smoke' | 'bubbles' | 'grid' | 'aurora' | 'noise' | 'rings'",
+              "attribute": "mode"
+            },
+            {
+              "kind": "field",
+              "name": "connect",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Draw constellation lines between nearby particles",
+              "attribute": "connect"
+            },
+            {
+              "kind": "field",
+              "name": "connectDistance",
+              "type": {
+                "text": "number"
+              },
+              "default": "100",
+              "description": "Max distance for connecting lines",
+              "attribute": "connect-distance"
+            },
+            {
+              "kind": "field",
+              "name": "hoverEffect",
+              "type": {
+                "text": "ParticleHoverEffect"
+              },
+              "default": "'repel'",
+              "description": "Hover interaction: 'repel' | 'attract' | 'grab' | 'none'",
+              "attribute": "hover-effect"
+            },
+            {
+              "kind": "field",
+              "name": "interactiveRadius",
+              "type": {
+                "text": "number"
+              },
+              "default": "100",
+              "description": "Radius of the mouse hover interaction zone",
+              "attribute": "interactive-radius"
+            },
+            {
+              "kind": "field",
+              "name": "_canvas",
+              "type": {
+                "text": "HTMLCanvasElement"
+              },
+              "privacy": "private"
+            },
+            {
+              "kind": "field",
+              "name": "_particles",
+              "type": {
+                "text": "Particle[]"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "_pulses",
+              "type": {
+                "text": "NetworkPulse[]"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "_mouse",
+              "type": {
+                "text": "{ x: number | null; y: number | null }"
+              },
+              "privacy": "private",
+              "default": "{ x: null, y: null }"
+            },
+            {
+              "kind": "field",
+              "name": "_ctx",
+              "type": {
+                "text": "CanvasRenderingContext2D | null"
+              },
+              "privacy": "private",
+              "default": "null"
+            },
+            {
+              "kind": "field",
+              "name": "_lineColor",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "default": "'#e5e7eb'"
+            },
+            {
+              "kind": "field",
+              "name": "_colorCheckTick",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "_matrixChars",
+              "type": {
+                "text": "string[]"
+              },
+              "privacy": "private",
+              "default": "[]"
+            },
+            {
+              "kind": "field",
+              "name": "_time",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "default": "0"
+            },
+            {
+              "kind": "field",
+              "name": "_resize",
+              "privacy": "protected",
+              "default": "new ResizeController(this, { callback: (entry) => { const { width, height } = entry.contentRect; this._resizeCanvas(width, height); } })"
+            },
+            {
+              "kind": "field",
+              "name": "_loop",
+              "privacy": "protected",
+              "default": "new LoopController(this, { autoStart: false, callback: () => this._updateAndDraw() })"
+            },
+            {
+              "kind": "method",
+              "name": "_resizeCanvas",
+              "privacy": "private",
+              "parameters": [
+                {
+                  "name": "width",
+                  "type": {
+                    "text": "number"
+                  }
+                },
+                {
+                  "name": "height",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_setupMouseListeners",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_parseColors",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string[]"
+                }
+              }
+            },
+            {
+              "kind": "method",
+              "name": "_parseSize",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "number"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "prop",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "defaultValue",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_initParticles",
+              "privacy": "private"
+            },
+            {
+              "kind": "method",
+              "name": "_updateAndDraw",
+              "privacy": "private"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "count",
+              "type": {
+                "text": "number"
+              },
+              "default": "50",
+              "description": "Number of particles / elements in the field",
+              "fieldName": "count"
+            },
+            {
+              "name": "speed",
+              "type": {
+                "text": "number"
+              },
+              "default": "1",
+              "description": "Speed multiplier",
+              "fieldName": "speed"
+            },
+            {
+              "name": "mode",
+              "type": {
+                "text": "ParticleMode"
+              },
+              "default": "'float'",
+              "description": "Animation mode.\n'float' | 'snow' | 'rain' | 'neural' | 'matrix' |\n'wave' | 'vortex' | 'smoke' | 'bubbles' | 'grid' | 'aurora' | 'noise' | 'rings'",
+              "fieldName": "mode"
+            },
+            {
+              "name": "connect",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Draw constellation lines between nearby particles",
+              "fieldName": "connect"
+            },
+            {
+              "name": "connect-distance",
+              "type": {
+                "text": "number"
+              },
+              "default": "100",
+              "description": "Max distance for connecting lines",
+              "fieldName": "connectDistance"
+            },
+            {
+              "name": "hover-effect",
+              "type": {
+                "text": "ParticleHoverEffect"
+              },
+              "default": "'repel'",
+              "description": "Hover interaction: 'repel' | 'attract' | 'grab' | 'none'",
+              "fieldName": "hoverEffect"
+            },
+            {
+              "name": "interactive-radius",
+              "type": {
+                "text": "number"
+              },
+              "default": "100",
+              "description": "Radius of the mouse hover interaction zone",
+              "fieldName": "interactiveRadius"
+            }
+          ],
+          "superclass": {
+            "name": "UIBitElement",
+            "package": "@uibit/core"
+          },
+          "tagName": "uibit-particles",
+          "customElement": true
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "Particles",
+          "declaration": {
+            "name": "Particles",
+            "module": "src/particles.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "uibit-particles",
+          "declaration": {
+            "name": "Particles",
+            "module": "src/particles.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "default",
+          "declaration": {
+            "name": "Particles",
+            "module": "src/particles.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/styles.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "styles",
+          "default": "css` :host { display: block; position: relative; width: 100%; height: 100%; min-height: 9.375rem; /* 150px equivalent */ overflow: hidden; /* Custom CSS variables for visual defaults */ --uibit-particles-color: #6b7280; --uibit-particles-line-color: #e5e7eb; --uibit-particles-opacity: 1; } .container { position: relative; width: 100%; height: 100%; } canvas { position: absolute; top: 0; left: 0; width: 100%; height: 100%; display: block; opacity: var(--uibit-particles-opacity); pointer-events: none; /* Let clicks/hovers pass through to the slot content */ } .content { position: relative; z-index: 1; width: 100%; height: 100%; } `"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "styles",
+          "declaration": {
+            "name": "styles",
+            "module": "src/styles.ts"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "src/types.ts",
+      "declarations": [],
+      "exports": []
+    }
+  ]
+}

package/dist/frameworks/angular/index.ts

@@ -0,0 +1,70 @@
+import { Component, ChangeDetectionStrategy, ElementRef, input, effect, booleanAttribute, numberAttribute } from '@angular/core';
+import '@uibit/particles';
+import type { Particles as HTMLElementClass } from '@uibit/particles';
+import type { Particle, ParticleHoverEffect, ParticleMode } from '@uibit/particles';
+
+@Component({
+  selector: 'uibit-particles',
+  template: '<ng-content></ng-content>',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  standalone: true
+})
+export class NgxParticles {
+  constructor(private el: ElementRef<HTMLElementClass>) {
+    effect(() => {
+      if (this.el.nativeElement) {
+        this.el.nativeElement.count = this.count();
+      }
+    });
+    effect(() => {
+      if (this.el.nativeElement) {
+        this.el.nativeElement.speed = this.speed();
+      }
+    });
+    effect(() => {
+      if (this.el.nativeElement) {
+        this.el.nativeElement.mode = this.mode();
+      }
+    });
+    effect(() => {
+      if (this.el.nativeElement) {
+        this.el.nativeElement.connect = this.connect();
+      }
+    });
+    effect(() => {
+      if (this.el.nativeElement) {
+        this.el.nativeElement.connectDistance = this.connectDistance();
+      }
+    });
+    effect(() => {
+      if (this.el.nativeElement) {
+        this.el.nativeElement.hoverEffect = this.hoverEffect();
+      }
+    });
+    effect(() => {
+      if (this.el.nativeElement) {
+        this.el.nativeElement.interactiveRadius = this.interactiveRadius();
+      }
+    });
+    effect(() => {
+      if (this.el.nativeElement) {
+        this.el.nativeElement._resize = this._resize();
+      }
+    });
+    effect(() => {
+      if (this.el.nativeElement) {
+        this.el.nativeElement._loop = this._loop();
+      }
+    });
+  }
+
+  readonly count = input<number, any>(50, { transform: numberAttribute });
+  readonly speed = input<number, any>(1, { transform: numberAttribute });
+  readonly mode = input<ParticleMode, any>('float');
+  readonly connect = input<boolean, any>(false, { transform: booleanAttribute });
+  readonly connectDistance = input<number, any>(100, { transform: numberAttribute });
+  readonly hoverEffect = input<ParticleHoverEffect, any>('repel');
+  readonly interactiveRadius = input<number, any>(100, { transform: numberAttribute });
+  readonly _resize = input<any, any>(new ResizeController(this, { callback: (entry) => { const { width, height } = entry.contentRect; this._resizeCanvas(width, height); } }));
+  readonly _loop = input<any, any>(new LoopController(this, { autoStart: false, callback: () => this._updateAndDraw() }));
+}

package/dist/frameworks/astro/index.d.ts

@@ -0,0 +1,10 @@
+import type { Particles as HTMLElementClass } from '@uibit/particles';
+import '@uibit/particles';
+
+declare global {
+  namespace astroHTML.JSX {
+    interface IntrinsicElements {
+      'uibit-particles': Partial<HTMLElementClass> & astroHTML.JSX.HTMLAttributes;
+    }
+  }
+}

package/dist/frameworks/nuxt/index.ts

@@ -0,0 +1,7 @@
+import { defineNuxtPlugin } from '#app';
+
+export default defineNuxtPlugin(() => {
+  if (process.client) {
+    import('@uibit/particles');
+  }
+});

package/dist/frameworks/preact/index.d.ts

@@ -0,0 +1,22 @@
+import type { JSX } from 'preact';
+import type { Particles as HTMLElementClass } from '@uibit/particles';
+import '@uibit/particles';
+import type { Particle, ParticleHoverEffect, ParticleMode } from '@uibit/particles';
+
+declare module 'preact' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'uibit-particles': JSX.HTMLAttributes<HTMLElementClass> & {
+      count?: number;
+      speed?: number;
+      mode?: ParticleMode;
+      connect?: boolean;
+      connectDistance?: number;
+      hoverEffect?: ParticleHoverEffect;
+      interactiveRadius?: number;
+      _resize?: any;
+      _loop?: any;
+      };
+    }
+  }
+}

package/dist/frameworks/qwik/index.tsx

@@ -0,0 +1,10 @@
+import { component$, Slot } from '@builder.io/qwik';
+import '@uibit/particles';
+
+export const Particles = component$<any>((props) => {
+  return (
+    <uibit-particles {...props}>
+      <Slot />
+    </uibit-particles>
+  );
+});

package/dist/frameworks/react/index.d.ts

@@ -0,0 +1,26 @@
+import type { HTMLAttributes, ClassAttributes } from 'react';
+import type { Particles as HTMLElementClass } from '@uibit/particles';
+import '@uibit/particles';
+import type { Particle, ParticleHoverEffect, ParticleMode } from '@uibit/particles';
+
+declare global {
+  namespace React {
+    namespace JSX {
+      interface IntrinsicElements {
+        'uibit-particles': ClassAttributes<HTMLElementClass> & HTMLAttributes<HTMLElementClass> & {
+          children?: React.ReactNode;
+          class?: string;
+      count?: number;
+      speed?: number;
+      mode?: ParticleMode;
+      connect?: boolean;
+      connectDistance?: number;
+      hoverEffect?: ParticleHoverEffect;
+      interactiveRadius?: number;
+      _resize?: any;
+      _loop?: any;
+        };
+      }
+    }
+  }
+}

package/dist/frameworks/solid/index.d.ts

@@ -0,0 +1,23 @@
+import type { JSX } from 'solid-js';
+import type { Particles as HTMLElementClass } from '@uibit/particles';
+import '@uibit/particles';
+import type { Particle, ParticleHoverEffect, ParticleMode } from '@uibit/particles';
+
+declare module 'solid-js' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'uibit-particles': Partial<HTMLElementClass> & JSX.HTMLAttributes<HTMLElementClass> & {
+              count?: number;
+      speed?: number;
+      mode?: ParticleMode;
+      connect?: boolean;
+      connectDistance?: number;
+      hoverEffect?: ParticleHoverEffect;
+      interactiveRadius?: number;
+      _resize?: any;
+      _loop?: any;
+
+      };
+    }
+  }
+}