R3F Quick Start
Get started with threeparticles in React Three Fiber.
Installation
npm install @threeparticles/core @react-three/fiber react threeBasic Example
import * as THREE from "three/webgpu";
import { Canvas } from "@react-three/fiber";
import { Particles } from "@threeparticles/core/react";
function App() {
return (
<Canvas
gl={async (props) => {
const renderer = new THREE.WebGPURenderer({ ...props, antialias: true });
await renderer.init();
return renderer;
}}
camera={{ position: [0, 0, 5], fov: 75 }}
>
<Particles
config={{
particles: {
count: 10000,
intensity: 2,
colors: [
[
{ color: "cyan", stop: 0 },
{ color: "purple", stop: 1 },
],
],
},
render: {
blendingMode: THREE.AdditiveBlending,
},
emitter: {
loop: true,
rate: 1000,
lifetime: [2, 4],
speed: [0.5, 1],
size: [0.05, 0.4],
directionMin: [-1, -1, -1],
directionMax: [1, 1, 1],
},
}}
/>
</Canvas>
);
}WebGPU Requirement
threeparticles uses WebGPU with TSL shaders, so you must configure R3F to use WebGPURenderer. The async gl prop pattern shown above handles the renderer initialization.
Component Props
| Prop | Type | Default | Description |
|---|---|---|---|
config | ParticlesConfig | required | Particle system configuration |
autoStart | boolean | true | Start emitting on mount |
position | [x, y, z] | [0, 0, 0] | Position in 3D space |
rotation | [x, y, z] | [0, 0, 0] | Rotation in radians |
Ref Access
Access the underlying Particles instance for imperative control:
import { useRef } from "react";
import { Particles } from "@threeparticles/core/react";
import type { Particles as ParticlesCore } from "@threeparticles/core";
function ControlledParticles() {
const particlesRef = useRef<ParticlesCore>(null);
const handleBurst = () => {
particlesRef.current?.start();
};
return (
<>
<Particles ref={particlesRef} config={config} autoStart={false} />
<button onClick={handleBurst}>Burst</button>
</>
);
}Next Steps
- React Integration - Performance tips, manual integration, and advanced patterns
- Basic Concepts - Understanding particle configuration