Particles
particlesAnimates a canvas particle field with pointer repulsion and theme-aware foreground color.
Usage
Basic usage
Put it into the relative container. Particles comes with absolute and inset-0. If color is not transferred, the theme foreground color will be used, and the mouse will be magnetically displaced when approaching it.
<div className="relative h-48 w-80 overflow-hidden rounded-xl border border-border bg-surface">
<Particles quantity={120} />
<div className="grid h-full place-items-center text-sm text-muted">Particles</div>
</div>Still and slow motion
staticity The bigger the particle is, the less likely it is to follow the mouse. The larger ease is, the slower it will follow, creating a more restrained atmosphere.
<div className="relative h-48 w-80 overflow-hidden rounded-xl border border-border bg-surface">
<Particles quantity={80} staticity={80} ease={80} />
</div>Specify color
Pass color (#hex / rgb()) to fix the particle color and no longer follow the theme.
<div className="relative h-48 w-80 overflow-hidden rounded-xl border border-border bg-surface">
<Particles quantity={100} color="#6366f1" />
</div>Particle size and drift
size increases the single particle radius, and vx / vy gives a constant drift speed to form a directional flow.
<div className="relative h-48 w-80 overflow-hidden rounded-xl border border-border bg-surface">
<Particles quantity={50} size={2} vx={0.3} vy={0.1} />
</div>When to Use
Use it when you need a stardust/particle background that interacts with the mouse (technical Hero, login page). Based on canvas, it has mouse rejection and drift interaction, which is more dynamic but more expensive than pure CSS Aurora; if you only want a static color gradient background, use Aurora; if you want regular dot matrix/grid shading, use DotPattern / GridPattern.
Import
import { Particles } from "@hulianui/ui"Props
| Name | Type | Default | Description |
|---|---|---|---|
| quantity | number | 100 | Number of particles |
| staticity | number | 50 | Static coefficient, the larger it is, the less likely it is to follow the mouse (displacement = mouseOffset / (staticity/magnetism)) |
| ease | number | 50 | Easing coefficient, the larger it is, the slower it is (translateX += (target-current)/ease) |
| size | number | 0.4 | Particle base radius (px), finally random in [size, size+2] |
| color | string | --color-foreground | Particle color. When omitted, the component reads the theme token and responds to data-theme; explicit values accept #rrggbb, #rgb, or rgb(r,g,b) |
| vx | number | 0 | X-axis constant drift speed (px/frame) |
| vy | number | 0 | Y-axis constant drift speed (px/frame) |
| refresh | boolean | number | string | — | Refresh signal - force redrawing of particles when the value changes (equivalent to MagicUI refresh) |
| className | string | — | Additional class name for the container div |
Usage Guidelines
- Canvas color prop only accepts
#rrggbb/#rgb/rgb()parsing format, cannot directly pass `var(--token)` or oklch string - if you want a theme color, do not passcolorand let it read--color-foregroundinternally, or parse it into rgb first and then pass it (see [[oklch-css-var-color-must-parse-via-offscreen-canvas]]). - Based on canvas, client rendering is required; the parent container requires
relative+overflow-hidden. - There is a performance cost to redrawing frame by frame if the quantity is too large (quantity is hundreds or more), and the background layer should be controlled as appropriate.
Related
DotPattern · GridPattern · StripedPattern · Spotlight · RetroGrid · Ripple
Playground
<div className="relative overflow-hidden">
<Particles
quantity={100}
staticity={50}
ease={50}
size={0.4}
/>
</div>