@H0N3YC4T/react-particles

A lightweight, high-performance, and framework-agnostic React background particle animation component. Zero external dependencies. Renders an interactive, customizable <canvas> element that automatically scales to the viewport and tracks mouse interactions.

Installation

Install via NPM:
```bash
npm install @H0N3YC4T/react-particles

Alternatively, install directly from GitHub:

npm install github:H0N3YC4T/react-particles

Quick Start

Drop the component anywhere in your React app. It automatically positions itself as a fixed background layer (z-index: 0 with pointer-events: none).

Make sure your foreground content has a higher z-index (e.g., position: relative; z-index: 1;) so it sits above the particles.

import ReactParticles from '@H0N3YC4T/react-particles';

export default function App() {
  return (
    <main>
      {/* Background Particles */}
      <ReactParticles 
        color="#ff0055" 
        particleCount={150} 
        speed={0.5} 
        enableLines={false}
      />
      
      {/* Foreground Content */}
      <div style={{ position: 'relative', zIndex: 1 }}>
        <h1>Mental not found.</h1>
        <p>The path you followed has led you astray...</p>
      </div>
    </main>
  );
}

Props API

All props are completely optional. The component provides sensible defaults if omitted.

Prop	Type	Default	Description
color	string	"#8b5cf6"	The hex color code for both particles and connecting lines.
opacity	number	0.55	The base opacity of the particles (0.0 to 1.0).
speed	number	2.25	The movement speed multiplier. Use < 1 for a slow dust effect.
particleCount	number	120	The target density of particles rendered on the screen.
enableLines	boolean	true	Whether to draw connecting lines between nearby particles.
lineLinkedDistance	number	110	The maximum pixel distance required to draw connecting lines.
grabDistance	number	160	The pixel radius for mouse hover interactions and line grabbing.
pulseOpacity	boolean	false	Enables a slow breathing/fading effect for individual particles.
scrollFadeHeight	number	null	The scroll distance (in pixels) before the canvas fades to invisible.
direction	string	"none"	Set a base falling velocity. Options: 'top', 'top-right', 'right', 'bottom-right', 'bottom', 'bottom-left', 'left', 'top-left', or 'none'.
outMode	string	"bounce"	Edge behavior. Options: 'bounce' (deflects off edges) or 'out' (wraps around seamlessly).

Framework Compatibility

Because this component does not rely on hidden DOM CSS observers, it is 100% compatible with any CSS framework (Material-UI, Tailwind CSS, Bootstrap, raw CSS).

If you are using a theme provider (like MUI), extract your theme's hex code and pass it directly into the component:

import { useTheme } from "@mui/material";

export default function ThemedApp() {
  const theme = useTheme();
  
  return <ReactParticles color={theme.palette.text.accent} />;
}

Credits

Inspired by and adapted from the original particles.js by Vincent Garreau.