# Particles

> Drifting dots behind a section that lean toward the pointer.

## Anatomy

Particles fill the background of a section with drifting dots that lean toward the pointer.

Add a `<canvas class="particles" aria-hidden="true">`. It covers its nearest positioned ancestor and lets clicks through. Each dot drifts slowly, fades out near the edges and moves toward the pointer while it is over the canvas, some further than others. `AutoInit()` starts every `canvas.particles`.

```
<div style="position: relative; height: 320px">
  <h2>Particles</h2>
  <canvas class="particles" aria-hidden="true"></canvas>
</div>
```

## Color

The dots take the canvas's CSS `color`, which is the theme's on-surface color unless you set another. The `color` option takes any CSS color and wins over the stylesheet.

```
<canvas class="particles" aria-hidden="true" style="color: var(--md-sys-color-primary)"></canvas>
```

## Drift

Set `vx` and `vy` to push every dot the same way, in pixels per frame. When a dot leaves the canvas, a new one replaces it somewhere inside. Lower `staticity` lets the dots follow the pointer further.

```
<canvas class="particles no-autoinit" aria-hidden="true"></canvas>

<script>
const canvas = document.querySelector('canvas.particles');
Expressive.Particles.init(canvas, { quantity: 150, vy: -0.3, staticity: 20 });
</script>
```

## Accessibility

-   Particles are decoration. Mark the canvas `aria-hidden="true"` and keep the content above it readable.
-   The canvas has pointer events off, so links and buttons under it still work.
-   When the reader prefers reduced motion, the canvas draws the dots once and they stay still.
-   A canvas off screen stops drawing. Its dots fade back in over about a second once it scrolls into view.

## Options

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `quantity` | Number | `100` | Number of dots. |
| `staticity` | Number | `50` | How firmly dots hold their place against the pointer. Lower values follow further. |
| `ease` | Number | `50` | Frames a dot takes to catch up with the pointer. Higher is slower. |
| `size` | Number | `0.4` | Base radius in pixels. Each dot adds 0 or 1. |
| `color` | String | `''` | A CSS color. Empty uses the canvas's CSS `color`. |
| `vx` | Number | `0` | Horizontal drift in pixels per frame. Negative drifts left. |
| `vy` | Number | `0` | Vertical drift in pixels per frame. Negative drifts up. |

## Methods

```
const particles = Expressive.Particles.getInstance(canvas);
particles.destroy();   // stops drawing and clears the canvas
```