# Particles

> Reference for Particles: its props, the ParticlesHandle (burst, emit), Emitter, BurstOptions, EmitOptions, and the ready-made BURSTS and EMITTERS.

```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] }`.

## Related

- [Particles guide](https://matthiasbrandolin.dev/apricot/guides/particles).