react-particle-text/README.md

A React component that creates interactive particle text effects using Three.js

# React Particle Text

A React component that creates interactive particle text effects using Three.js. The text is rendered as particles that respond to mouse interactions with beautiful animations.

## Features

- ✨ Interactive particle text effects
- 🎨 Customizable colors, sizes, and animations
- 🖱️ Mouse interaction with particle repulsion/attraction
- 📱 Responsive and performant
- 🎯 TypeScript support
- 🔧 Highly configurable
- 📐 Smart width detection (respects CSS classes and inline styles)
- 🎯 Automatic text centering with custom widths
- ⚡ Resource caching for multiple instances
- 🔄 Flexible sizing with fontSize prop support

## Installation

```bash
npm install react-particle-text
```

or

```bash
yarn add react-particle-text
```

## Usage

```tsx
import React from 'react';
import { ParticleText } from 'react-particle-text';

function App() {
  return (
    <div>
      <ParticleText 
        text="HELLO WORLD"
        fontSize="4rem"
        particleAmount={2000}
        particleSize={1.5}
        transparent={true}
        className="w-full" // Tailwind classes supported
      />
      {/* Your other content */}
    </div>
  );
}

export default App;
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `text` | `string` | `'STACKLOOP'` | The text to render as particles |
| `fontSize` | `string` | `'16px'` | Font size (supports px, rem, %) - automatically calculates container dimensions |
| `transparent` | `boolean` | `false` | Whether the background should be transparent |
| `particleAmount` | `number` | `1500` | Number of particles to generate |
| `particleSize` | `number` | `1` | Base size of particles |
| `particleColor` | `number` | `0xffffff` | Base color of particles (hex) |
| `textSize` | `number` | Auto-calculated | Size of the text in Three.js units (overrides fontSize calculation) |
| `area` | `number` | `250` | Mouse interaction area radius |
| `ease` | `number` | `0.05` | Animation easing factor |
| `fontUrl` | `string` | Default font | URL to custom Three.js font JSON |
| `particleImageUrl` | `string` | Default texture | URL to particle texture image |
| `className` | `string` | `''` | CSS classes (Tailwind supported, width classes respected) |
| `style` | `React.CSSProperties` | `{}` | Inline styles (custom width respected and auto-centered) |

## Styling

The component automatically calculates its dimensions based on the `fontSize` prop, but respects custom widths defined through CSS classes or inline styles. When a custom width is provided, the text is automatically centered.

### Automatic Sizing (Default)
```tsx
<ParticleText 
  text="AUTO SIZED"
  fontSize="3rem"
  transparent={true}
/>
```

### Custom Width with CSS Classes (Tailwind)
```tsx
<ParticleText 
  text="FULL WIDTH"
  fontSize="2rem"
  className="w-full h-64"
  transparent={true}
/>
```

### Custom Width with Inline Styles
```tsx
<ParticleText 
  text="CUSTOM"
  fontSize="4rem"
  style={{
    width: '50%',
    height: '300px',
    position: 'relative'
  }}
  transparent={true}
/>
```

## Custom Fonts

You can use custom fonts by providing a Three.js font JSON file:

```tsx
<ParticleText 
  text="CUSTOM FONT"
  fontUrl="/path/to/your/font.json"
/>
```

To convert TTF/OTF fonts to Three.js format, use the [Three.js Font Converter](https://gero3.github.io/facetype.js/).

## Custom Particle Texture

Customize the particle appearance with your own texture:

```tsx
<ParticleText 
  text="TEXTURED"
  particleImageUrl="/path/to/your/particle.png"
/>
```

## Examples

### Colorful Large Text
```tsx
<ParticleText 
  text="AMAZING"
  fontSize="5rem"
  particleAmount={3000}
  particleSize={2}
  particleColor={0xff6b6b}
  area={300}
  transparent={true}
/>
```

### Subtle Background Effect
```tsx
<ParticleText 
  text="BACKGROUND"
  fontSize="2rem"
  particleAmount={800}
  particleSize={0.8}
  particleColor={0x333333}
  area={150}
  ease={0.02}
  transparent={true}
/>
```

### Full Width with Tailwind
```tsx
<ParticleText 
  text="RESPONSIVE"
  fontSize="4rem"
  className="w-full h-screen"
  particleAmount={2500}
  particleColor={0x00ff88}
  transparent={true}
/>
```

### Multiple Instances (Resource Caching)
```tsx
<div>
  <ParticleText 
    text="HEADER"
    fontSize="3rem"
    className="w-full h-32"
    transparent={true}
  />
  <ParticleText 
    text="FOOTER"
    fontSize="2rem"
    className="w-full h-24"
    transparent={true}
  />
</div>
```

## Requirements

- React 16.8+
- Modern browser with WebGL support

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.