SVG Particles
Turn an SVG path into a canvas particle field by painting it once, reading the pixels back, and animating the dots under the cursor.
- #react
- #canvas
- #particles
- #interaction
- #performance
A logo made of a few thousand dots that move out of the way when the cursor comes close, then settle back. The component paints the path onto a canvas once, reads the canvas back as pixels, and keeps the coordinates that landed inside the shape. After that every frame is arithmetic over a flat array of points, so a complicated path costs no more than a simple one.
Download
The SVG Particle component.
Sampling the shape, not the outline
getPointAtLength needs a real SVGPathElement and only walks the outline, so
a filled logo comes out as a wireframe. Path2D takes the same d string with
no DOM, and getImageData hands back every pixel it covered.
The viewBoxWidth and viewBoxHeight props set the scale, since the numbers
in a path mean nothing without the box they were drawn against. Canvas does the
drawing, so subpaths, even-odd holes, joins and caps all still work, and an
array of d strings becomes one shape.
Where the particles come from
A particle is any pixel the shape covered. The component picks a random pixel,
keeps it if its alpha is above half, and tries again up to a hundred times if
it is not. baseX and baseY are the home pixel every later frame measures
against.
Each attempt succeeds with roughly the probability that the shape covers the canvas, so a solid logo lands in a few tries while a thin stroke on a wide canvas can fail outright. The budget is 7000 particles for a 1080p frame, scaled by the square root of the area ratio, and the loop refills the field every frame. That is why a stroked shape fills in over the first second.
A particle's home is a pixel of a bitmap, so nothing survives a resize. A
ResizeObserver throws the bitmap away and builds the field again.
Scatter and spill
The two modes differ in whether a particle remembers anything between frames.
scatter does not. Position is assigned from the cursor distance, so nothing
can drift, and returnSpeed closes a fixed fraction of the way home each
frame.
spill adds up velocity instead. The cursor pushes, friction bleeds the push
off, and returnSpeed acts as a spring pulling each particle home.
Tune those two together. A strong spring with friction near 0.99 keeps the field wobbling after the cursor has gone. The documented range of 0.8 to 0.99 stays inside safe values.
Colour and lifetime
A particle is drawn in particleColor at rest and scatteredColor once it has
moved more than two pixels from home. The threshold stops the resting field
from flickering while the spring settles.
With enableParticleDeath, each particle lives 50 to 150 frames and is then
replaced somewhere else in the shape. The count stays the same but the pixels
keep changing, which looks like a slow shimmer. In spill a particle that dies
in mid-flight comes back home, so a field you pushed hard heals from the inside
while the pushed dots are still drifting back.
Cost and trade-offs
One pass over the array per frame: a distance, a few multiplications, and a
fillRect of one pixel or so. No DOM, no allocation, no layout. What it does
spend is canvas state changes, since fillStyle is set per particle rather
than per colour. If you need a higher count, sort the field and draw it in two
passes, one per colour.
- The canvas is sized in CSS pixels with no
devicePixelRatioscaling, so dots look soft on a high-density screen. For 1px dots that reads as a glow, and it cuts the number of fills by four. backgroundColoris painted opaquely every frame, so the page behind never shows through. On a themed surface, drop it and letclearRectwork alone.- Touch has its own code path. The field only reacts while a finger is down,
and the desktop check is
!("ontouchstart" in window), so a laptop with a touchscreen needs a press first.
Using it
The canvas fills its container, so give it a sized box.
A stroked shape needs the stroke props, in viewBox units, and an array of d
strings when the source SVG had more than one path element.
Props
<SVGParticles />
svgPathstring | string[]
The d attribute to sample. An array is drawn as subpaths of one shape, in order.
viewBoxWidth?number
Width of the viewBox the path was drawn against. A wrong value scales the shape wrongly; it cannot distort it.
- Default
100
viewBoxHeight?number
Height of that viewBox. Together with logoHeight it sets the scale.
- Default
100
logoHeight?number
Rendered height of the shape in pixels, on a container at least 768px wide.
- Default
120
mobileLogoHeight?number
Rendered height below a container width of 768px. Measured from the container, not the viewport.
- Default
60
particleColor?string
Colour of a particle at rest. The shape is also drawn in this colour, so it must be opaque for the alpha test to find it.
- Default
"white"
scatteredColor?string
Colour of a particle that has moved away from its home pixel.
- Default
"#00DCFF"
backgroundColor?string
Painted opaquely over the whole canvas every frame, so the page behind the field never shows through.
- Default
"black"
pathStyle?"fill" | "stroke"
Whether the path is filled or stroked when it is drawn. A fill gives the sampler far more area to hit.
- Default
"fill"
strokeWidth?number
Stroke width in viewBox units, so it scales with the shape.
- Default
1
lineJoin?CanvasLineJoin
Join style for stroke corners: miter, round or bevel.
- Default
"miter"
lineCap?CanvasLineCap
Cap style for stroke ends: butt, round or square.
- Default
"butt"
interactionMode?"scatter" | "spill"
scatter sets the position from the cursor distance each frame; spill adds up velocity with friction and a spring.
- Default
"scatter"
forceMu?number
Multiplier on the cursor's push, which falls off evenly over 240 pixels.
- Default
1
returnSpeed?number
Fraction of the remaining distance closed each frame in scatter mode; the spring strength in spill mode.
- Default
0.1
friction?number
Velocity kept each frame in spill mode. Ignored in scatter mode, which stores no velocity.
- Default
0.95
enableParticleDeath?boolean
Give each particle a 50-150 frame life and respawn it elsewhere in the shape, for a shimmer across the shape.
- Default
true
Anything else is passed to the wrapping div, including className, which is
how you give the field its size.
Supplying the path data
Open the SVG in an editor and read viewBox="0 0 24 24" off the root element
and d="…" off each <path>. Nothing else is needed.
- Area beats outline. Raise
strokeWidthbefore you raise the particle count. - Keep the shape large in the frame. Pixels outside it are thrown away, so a small shape on a wide canvas wastes attempts on empty space.
- Only
<path>elements work. Convert<circle>,<rect>and<polygon>first; most editors will do it. - This is not accessible on its own. The canvas carries an
aria-labeland nothing more, so a shape that carries meaning needs that meaning in the markup around it.
Files in this entry
Saved beside the document, and served as-is.
Related entries
useIntersectionObserver hook
Track element visibility for lazy loading, infinite scroll and scroll-spy navigation.
Virtual list
Render only the visible slice of a long list, using fixed-height windowing and an absolute spacer.
Memoization rules
A decision procedure for memo, useMemo and useCallback that avoids caching for its own sake.