ts
import { BURSTS, EMITTERS, Particles } from "@apricot/react";
import type { BurstName, BurstOptions, EmitOptions, Emitter, EmitterName, ParticlesHandle, ParticlesProps } from "@apricot/react";Particles#
| Prop | Type | Default | Description |
|---|---|---|---|
emit |
EmitterName | EmitOptions | false |
none | A stream sent out while set. Changes follow as it runs |
glow |
boolean |
false |
Adds particles to what is behind (bright on a dark scene). false draws them over it |
texture |
THREE.Texture | null |
a soft dot | A picture each particle shows, tinted by its colour (from useTexture) |
max |
number |
1000 |
The most alive at once; more reuse the oldest |
ref |
Ref<ParticlesHandle> |
Fires bursts and streams from code |
Plus transform props. Changing max, glow or texture makes a new set (streams started from code start again).
ParticlesHandle#
| Method | Description |
|---|---|
burst(burst, options?) |
Fires a burst: a name from BURSTS with options on top, or BurstOptions of your own |
emit(stream, options?) |
Starts a stream: a name from EMITTERS with options on top, or EmitOptions. Returns an Emitter |
Emitter#
| Member | Description |
|---|---|
set(options) |
Changes the stream as it goes (where, how many a second, anything a stream takes) |
stop() |
No new particles; those out finish their lives |
running |
Whether it is still sending them out |
BurstOptions#
Spread is a number or a range [min, max]: each particle gets a random value in the range.
| Option | Type | Default | Description |
|---|---|---|---|
at |
Vec3 |
[0, 0, 0] |
Where they start |
area |
Vec3 |
none | Size of a box round at they start anywhere in |
count |
number |
40 |
How many |
colors |
colours | ["#ffffff"] |
Each particle takes one |
fadeTo |
colour | none | The colour they turn to over their life |
speed |
Spread |
[1, 2] |
Metres per second |
direction |
Vec3 |
[0, 1, 0] |
The way they fly |
spread |
degrees | 180 |
How far round direction |
life |
Spread |
[0.6, 1.2] |
Seconds |
size |
Spread |
0.05 |
Metres |
grow |
number |
1 |
Size at the end against the start |
spin |
Spread |
0 |
Degrees per second |
shape |
"dot" | "square" |
"dot" |
A soft dot, or a fluttering paper square |
gravity |
number |
0 |
Metres per second² down; negative rises |
wind |
Vec3 |
[0, 0, 0] |
A steady push, metres per second² |
drag |
number |
0 |
How quickly they slow in the air |
EmitOptions#
Every BurstOptions field except count, plus:
| Option | Type | Default | Description |
|---|---|---|---|
rate |
number |
20 |
Particles a second |
Presets#
BURSTS (BurstName): sparkle, firework, pop, confetti.
EMITTERS (EmitterName): smoke, fountain, snow, sparkler.
Each is plain options: spread one and change what you like, { ...EMITTERS.snow, area: [10, 0, 10] }.