Getting Started
R3F Quick Start

R3F Quick Start

Get started with threeparticles in React Three Fiber.

Installation

npm install @threeparticles/core @react-three/fiber react three

Basic 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

PropTypeDefaultDescription
configParticlesConfigrequiredParticle system configuration
autoStartbooleantrueStart 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