# Particles

Aperveil / Light, shaped for the web.

Collection: Free, available now.

A particles background for React: dust motes drift through a beam of light in six depths, carried by slow air currents and stirred by the cursor, rendered live in WebGPU.

[Aperveil integration guide](https://www.aperveil.com/docs)

## What it does

Particles fills the air with dust motes and lets a beam of sunlight find them. Motes this size are carried by the air, not jostled by it, so neighbors turn together in slow currents; each wanders a little on its own and settles slowly. They are seen only where the beam crosses them, brightest because the light comes toward the eye, and flat flakes flash as they tumble. Six depths give the near motes size, softness and speed and the far ones fine, slow points. The cursor stirs the air into a swirl, and the room can be turned off so the particles float over your own page.

## Choose it for

Give a perfume, a film, a hotel or a luxury product a quiet, warm stillness: the beam can fall beside the heading, and with the room off the motes drift over your own photography.

## Limits

Particles draws motes in light, not a network: there are no connecting lines, no shapes and no text spelled out in particles. Each mote drifts around its own place in the air rather than travelling across the frame.

## Current look

Default. Color Looks change colors only; motion, geometry and typography remain unchanged.

[Open editor](https://www.aperveil.com/shaders/particles/edit?look=default&scene=landing)

## Landing scene

This preview uses `beamOffset`: 0.85, `beamAngle`: -0.35. The editor link carries these settings with your Look. Direct editor visits use the product defaults; Reset all restores those defaults.

## Install

Install editable source with the CLI; it installs shared dependencies automatically. Free needs no login. ZIP Export Kits are also available.

```sh
npx @aperveil/cli add shader particles --framework react
```

Every control in the editor is a typed prop. Leave a prop out to keep the value you exported; change one and the running shader updates without restarting. Give the surface a size and pass fallback for browsers without WebGPU.

```tsx
"use client";

import Particles from "./components/aperveil/particles/Particles";

export default function Hero() {
  return (
    <Particles
      className="hero-shader"
      density={0.5} background="#120c08ff"
      fallback={<div className="hero-shader-fallback" />}
    />
  );
}

// .hero-shader { width: 100%; height: 560px; }
```

Component props: `background`, `shadeColor`, `moteColor`, `beamColor`, `density`, `moteSize`, `blur`, `glitter`, `beam`, `beamAngle`, `beamWidth`, `beamOffset`, `current`, `flowSpeed`, `interaction`, `opacity`, `backgroundOpacity`, `className`, `style`, `paused`, `fallback`, `onReady`, `onError`.

### Vue and Nuxt

```sh
npx @aperveil/cli add shader particles --framework vue
```

```vue
<script setup lang="ts">
import Particles from "./components/aperveil/particles/vue/Particles.vue";
</script>

<template>
  <Particles class="hero-shader" :density="0.5" background="#120c08ff">
    <template #fallback><div class="hero-shader-fallback" /></template>
  </Particles>
</template>

<!-- .hero-shader { width: 100%; height: 560px; } -->
```

Vue 3.5 or newer, Nuxt included: it renders an empty canvas on the server and starts in the browser, so it needs no <ClientOnly>. Same props as the React component.

### Plain HTML

```html
<script type="module" src="./aperveil-particles.js"></script>

<aperveil-particles class="hero-shader" density="0.5" background="#120c08ff">
  <div slot="fallback" class="hero-shader-fallback"></div>
</aperveil-particles>

<style>
  .hero-shader { display: block; width: 100%; height: 560px; }
</style>
```

No install and no build step: keep the two files of the kit's html folder together.

### WordPress

Download `aperveil-shader-particles.zip` from the editor (Install, then WordPress) and upload it under Plugins, Add New, Upload Plugin. WordPress 6.5 or newer: a plugin with a block that holds your own content in front of the shader, and a shortcode for page builders. In the block editor, add the "Particles" block (Design) and place your blocks inside it; in a page builder, use the shortcode:

```html
[aperveil_particles height="560px" overlay="20"]
  <h2>Your headline</h2>
  <p>Your text, in front of the shader.</p>
[/aperveil_particles]
```

### Framer

Copy `Particles.tsx` from the editor (Install, then Framer); it opens on the values you chose. In Framer, add a new code file (Assets, Code), replace its sample code with the copy, then drag Particles onto the canvas: its Color Looks and every control are in the property panel. [Framer guide](https://www.aperveil.com/docs/framer).

Raw WGSL is included for a custom WebGPU host; it is not CSS. Keep semantic headings and links in HTML.

## Controls

- Room (`background`, color): The room around the beam. Its alpha, with Background opacity, sets how much room is drawn.
- Shadow (`shadeColor`, color): The darkest corner of the room, toward the bottom.
- Particles (`moteColor`, color): The color of the motes.
- Sunlight (`beamColor`, color): The beam, and the motes inside it.
- Density (`density`, slider): How many motes float in the air.
- Size (`moteSize`, slider): Size of the motes.
- Depth of field (`blur`, slider): How out of focus the nearest and farthest motes are.
- Glitter (`glitter`, slider): How often tumbling flakes flash in the light.
- Beam (`beam`, slider): Strength of the sunlight. Motes outside it stay nearly dark.
- Beam angle (`beamAngle`, slider): Slant of the beam from vertical, in radians.
- Beam width (`beamWidth`, slider): Width of the beam where it enters.
- Beam position (`beamOffset`, slider): Where the beam enters along the top edge.
- Air current (`current`, slider): How far the slow air currents carry the motes.
- Speed (`flowSpeed`, slider): Speed of the drift.
- Stir (`interaction`, slider): How strongly the cursor swirls the air.
- Opacity (`opacity`, slider): Opacity of the whole effect over the page.
- Background opacity (`backgroundOpacity`, slider): Turn the room down to float particles over your own page.

## Compatibility

WebGPU rendering requires a supported browser and secure context: Chrome and Edge (Windows, macOS and ChromeOS; Chrome on Android 12 or newer), Safari 26 (Mac, iPhone and iPad) and Firefox (Windows (from 141) and Apple silicon Macs (from 145)). Firefox on Linux, Android and Intel Macs is still rolling it out (checked October 2026). The landing shows a real poster for the selected Look when live rendering is unavailable. The standard exported component does not bundle a poster fallback. Supply your own fallback in the host layout.

## Performance

2.884 ms GPU timestamp median; p95 3.08 ms. 1440x900 @ dpr 1.25; Apple M2 (8-core GPU), Metal driver on macOS Version 26.6.2 (Build 25G83); measured 2026-10-22. This is a recorded headless sample, not a browser FPS or mobile-performance guarantee.

## Questions

### Can the particles float over my page?

Yes. Set Background opacity to zero and only the motes are drawn, over whatever lies beneath the canvas.

### What does the cursor do?

It stirs the air: motes near it swirl around it and drift outward, the nearer ones more. Stir sets how strongly.

### Why are most particles dark?

Dust is seen only where light crosses it, the Tyndall effect. Beam sets the light, and Beam angle, Beam width and Beam position place it; outside it the motes nearly vanish, as in a sunlit room.

### What happens without WebGPU?

This landing shows a still poster of your selected Color Look. The raw WGSL needs a WebGPU host. Landing posters are not bundled in the Export Kit: add your own fallback around the exported component.

### Can I use this shader commercially?

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects.

## License

Part of the Free collection for Aperveil 1.0. Public live preview and Color Looks are open. Free Export Kits do not require an account. Purchasing is not available yet. Follow the license notices supplied with the source you download. The planned Free collection permits personal and commercial interface projects.

## Related shaders

- [Particle Bloom](https://www.aperveil.com/shaders/particle-bloom)
- [Stardust Tide](https://www.aperveil.com/shaders/stardust-tide)
- [God Rays](https://www.aperveil.com/shaders/god-rays)