React Particles Text

A lightweight and interactive React component that renders text as a field of animated particles on a canvas. Customize particle behavior, style, and interactivity to create visually engaging experiences for your website or application.

---

Table of Contents

• Features
• Installation
• Usage
• API Reference
• Storybook Documentation
• Examples
• Contributing
• License

---

Features

• Interactive Particles: Particles react to mouse movement, creating a dynamic and engaging effect.
• Customizable Appearance: Adjust particle sizes, densities, colors, and more.
• Multiple Modes: Easily switch between different visual styles (e.g., dark mode, colorful, subtle background).
• Responsive Design: Automatically adapts to container dimensions.
• Storybook Documentation: Comprehensive examples and live demos available via Storybook.

---

Installation

Install the package via npm or yarn:

npm install react-particles-text
# or
yarn add react-particles-text

Usage

Import and use the <ParticleText /> component in your React project:

import React from 'react';
import ParticleText from 'react-particles-text';

const App = () => {
  return (
    <div style={{ width: '100vw', height: '100vh' }}>
      <ParticleText
        text="HELLO WORLD"
        font="bold 60px Arial"
        textColor="#ffffff"
        bgParticleColor="rgba(255, 255, 255, 0.5)"
        offset={60}
        textParticleSize={1.5}
        bgParticleSize={[0.5, 1.5]}
        interactionDistance={100}
        returnSpeed={10}
        particleDensity={3}
        bgParticleDensity={1}
        backgroundColor="transparent"
      />
    </div>
  );
};

export default App;

This component uses an HTML canvas to render the particles, with interactive behavior that responds to mouse movement.

Storybook Documentation

For live previews and comprehensive examples, check out the Storybook Documentation. The Storybook project includes several pre-configured stories that demonstrate different use cases and visual styles, including:

• Dark Mode: Light text on a dark background.
• Colorful: Vibrant particle colors with custom interaction settings.
• Multiple Words: Displaying multi-word text with customizable spacing.
• Large Particles: Emphasized particle sizes with stronger mouse interaction.
• Subtle Background: A gentle background effect with a lower particle density.
• Dense Particles: Highly populated particles for a detailed visual effect.
• Custom Font: Using a custom font style for the text particles.

API Reference

Prop Name	Type	Default	Description
text	string	—	Text to display as particles.
offset	number	60	Vertical spacing between words when multiple words are present.
font	string	"bold 60px Arial"	Font used to render the text particles.
textColor	string	"white"	Color of the text particles.
bgParticleColor	string	"rgba(255, 255, 255, 0.5)"	Color of the background particles.
textParticleSize	number	1.5	Size of the text particles.
bgParticleSize	[number, number]	[0.5, 1.5]	Range for the size of background particles.
interactionDistance	number	100	Distance at which particles react to the mouse.
returnSpeed	number	10	Speed at which particles return to their original position.
particleDensity	number	3	Density of particles sampled from text (smaller values create more particles).
bgParticleDensity	number	1	Number of background particles per 5000px² of canvas.
className	string	"w-full h-full"	Custom className for the canvas container.
style	React.CSSProperties	{}	Inline style object for the canvas container.
width	number, string	—	Canvas width (defaults to container width).
height	number, string	—	Canvas height (defaults to container height).
backgroundColor	string	"transparent"	Background color of the canvas.

Contributing

Contributions are welcome! If you have ideas for improvements, bug fixes, or new features, please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Commit your changes with clear commit messages.
4. Open a pull request explaining your changes.

Please ensure that your code adheres to the project’s coding standards.