ParticleImage.svelte

A Svelte 5 component that converts any image into an interactive particle animation with mouse interaction, auto-shuffling, and customizable scaling.

✨ Features

• 🎨 Convert any image to animated particles
• 🖱️ Interactive mouse repulsion effects
• 🎭 Monochrome or full-color modes
• 📏 Multiple image scaling modes (cover, contain, fill)
• 🔄 Auto-shuffle animations
• ⚡ High-performance canvas rendering
• 📱 Fully responsive
• 🎯 Built with Svelte 5 runes

🚀 Installation

Option 1: Copy Component

1. Copy ParticleImage.svelte to your project's component directory
2. Import and use it in your Svelte components

Option 2: NPM Package (if published)

npm install svelte-particle-image

📖 Basic Usage

<script>
import ParticleImage from './ParticleImage.svelte';
</script>

<ParticleImage imageSrc="/path/to/image.png" />

🎛️ Props Reference

Required Props

Prop	Type	Default	Description
imageSrc	string	-	Path or URL to the image

Layout Props

Prop	Type	Default	Description
width	string	'100%'	Container width (CSS value: px, %, vw)
height	string	'192px'	Container height (CSS value: px, vh, %)
backgroundColor	string	'transparent'	Background color behind particles (hex, rgb, rgba)

Particle Appearance Props

Prop	Type	Default	Description
particleSize	number	1	Size of each particle in pixels (1-10 recommended)
particleGap	number	0	Gap between sampled pixels (0 = dense, 5 = very sparse)
monochrome	boolean	false	Use single color instead of image colors
monochromeColor	string	'#00ff96'	Color when monochrome is enabled (hex format)

Particle Behavior Props

Prop	Type	Default	Description
restless	boolean	true	Particles have subtle random movement
mouseForce	number	10000	Mouse repulsion strength (0 = disabled, 50000 = very strong)

Animation Props

Prop	Type	Default	Description
autoShuffle	boolean	false	Automatically scatter and reform particles
shuffleInterval	number	5000	Time between shuffles in milliseconds

Image Scaling Props

Prop	Type	Default	Description
imageScale	'cover' | 'contain' | 'fill' | 'none'	'cover'	How image scales to canvas
imageFit	'center' | 'top' | 'bottom' | 'left' | 'right'	'center'	Image position within canvas

Image Scale Modes Explained:

• cover: Scales image to fill entire canvas, cropping if needed (like CSS background-size: cover)
• contain: Scales image to fit within canvas without cropping (like CSS background-size: contain)
• fill: Stretches image to exactly fill canvas (may distort aspect ratio)
• none: Uses original image size without scaling

💡 Usage Examples

Example 1: Full-Screen Hero with Cover

<ParticleImage
  imageSrc="/hero-image.jpg"
  width="100%"
  height="100vh"
  imageScale="cover"
  backgroundColor="#000000"
  particleSize={2}
  particleGap={1}
/>

Example 2: Logo with Monochrome Effect

<ParticleImage
  imageSrc="/logo.png"
  height="300px"
  monochrome={true}
  monochromeColor="#00ff96"
  backgroundColor="#000000"
  imageScale="contain"
  imageFit="center"
/>

Example 3: Photo Gallery Item

<ParticleImage
  imageSrc="/photo.jpg"
  width="600px"
  height="400px"
  monochrome={false}
  particleGap={1}
  particleSize={2}
  imageScale="cover"
  mouseForce={15000}
/>

Example 4: Minimal Particles, No Interaction

<ParticleImage
  imageSrc="/icon.png"
  particleGap={3}
  particleSize={4}
  mouseForce={0}
  restless={false}
  imageScale="contain"
  backgroundColor="#f0f0f0"
/>

Example 5: Auto-Shuffling Animation

<ParticleImage
  imageSrc="/artwork.png"
  autoShuffle={true}
  shuffleInterval={3000}
  backgroundColor="rgba(0,0,0,0.8)"
  particleSize={2}
  restless={true}
/>

Example 6: High-Performance Mode (Large Images)

<ParticleImage
  imageSrc="/large-image.png"
  particleGap={3}
  particleSize={2}
  mouseForce={5000}
  imageScale="cover"
/>

Example 7: Responsive Viewport Height

<ParticleImage
  imageSrc="/banner.jpg"
  width="100%"
  height="50vh"
  imageScale="cover"
  imageFit="center"
  particleSize={2}
/>

🎮 User Interactions

• Hover: Mouse cursor repels nearby particles (if mouseForce > 0)
• Click: Scatter all particles and watch them reform the image
• Window Resize: Component automatically adjusts to new container dimensions

⚡ Performance Tips

Optimize for Large Images

1. Increase particleGap: Use 2-4 for large images to reduce particle count
2. Adjust particleSize: Use 2-3 on high-DPI screens for better visibility
3. Lower mouseForce: Reduce to 5000-8000 for smoother performance
4. Disable restless: Set to false if you have many particle instances

Calculate Particle Count

Approximate number of particles generated:

particles ≈ (imageWidth × imageHeight) / ((particleGap + 1)²)

Recommendations:

• Keep total particles under 10,000 for smooth 60fps animation
• For 1920×1080 images: use particleGap={3} → ~130,000 pixels / 16 = ~8,125 particles ✓
• For 4K images: use particleGap={5} → ~230,000 pixels / 36 = ~6,400 particles ✓

Image Format Tips

• Use PNG for images with transparency
• Use JPG for photos (smaller file size)
• Use SVG for logos and icons (scalable)
• Compress images before use for faster loading

🌐 Browser Support

Requires modern browsers with:

• Canvas API
• requestAnimationFrame
• ES6+ JavaScript features

Supported Browsers:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Opera 76+

Not supported:

• Internet Explorer (any version)

🛠️ Development

Run Demo Locally

# Clone the repository
git clone https://github.com/yourusername/svelte-particle-image.git
cd svelte-particle-image

# Install dependencies
npm install

# Run development server
npm run dev

# Open http://localhost:5173

Build for Production

npm run build

📁 Project Structure

svelte-particle-image/
├── src/
│   ├── lib/
│   │   └── ParticleImage.svelte       # Main component
│   └── routes/
│       └── +page.svelte                # Interactive demo page
├── static/
│   └── demo-images/                    # Sample images
├── README.md
├── LICENSE
├── package.json
├── svelte.config.js
└── vite.config.ts

🎨 Styling Tips

Custom Container Styling

<div class="my-container">
  <ParticleImage
    imageSrc="/image.png"
    width="100%"
    height="100%"
  />
</div>

<style>
  .my-container {
    border-radius: 12px;
    overflow: hidden;
    box-shadow: 0 10px 30px rgba(0,0,0,0.2);
  }
</style>

Responsive Design

<ParticleImage
  imageSrc="/image.png"
  width="100%"
  height="50vh"
  imageScale="cover"
/>

🐛 Troubleshooting

Image Not Showing

• Check that imageSrc path is correct
• Verify image is accessible (check browser console for 404 errors)
• For external images, ensure CORS is properly configured
• Images should be in the static/ folder for SvelteKit projects

Performance Issues

• Reduce particle count by increasing particleGap
• Disable restless mode
• Lower mouseForce value
• Use smaller/compressed images

Height Not Working with Percentages

• Use vh units instead: height="50vh" (50% of viewport height)
• Or ensure parent container has defined height
• Percentages require parent element to have explicit height

Particles Look Pixelated

• Increase particleSize from 1 to 2 or 3
• Check if image resolution is too low
• Try different imageScale modes

📄 License

MIT License

Copyright (c) 2024

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.

🙏 Credits

Inspired by the ParticleSlider concept by Tamino Martinius

Built with ❤️ using Svelte 5

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📮 Support

If you have any questions or issues:

• Open an issue on GitHub
• Check existing issues for solutions
• Review the troubleshooting section above