react-smoke is a powerful and flexible solution for rendering stunning smoke effects in your React applications. Built on top of React Three Fiber (R3F) and Three.js, this library leverages the power of modern WebGL to bring high-fidelity, realistic smoke simulations to the web.

Features

• Realistic Smoke Rendering: Create visually impressive smoke effects with realistic motion and appearance.
• Seamless Integration: Designed to work seamlessly within your React projects using R3F and Three.js.
• Customizable Effects: Easily adjust parameters such as density, wind, turbulence, and more to fit your needs.
• Performance Optimized: Efficient rendering techniques ensure smooth performance even with complex smoke simulations.
• Easy to Use: Simple and intuitive API makes it easy to add 3D smoke effects to your application with minimal code.

Demo

Check out the live demo (playground) to see react-smoke in action and explore its capabilities.

Installation

1npm install react-smoke three @react-three/fiber

or

1yarn add react-smoke three @react-three/fiber

Peer Dependencies

This library is designed to work alongside three.js and @react-three/fiber. These are listed as peer dependencies, meaning that it expects these packages to be present in your project:

• three.js: A JavaScript 3D library that creates and displays animated 3D computer graphics in a web browser.
• @react-three/fiber: A React renderer for three.js that brings declarative, reactive, and component-based patterns to 3D rendering.

As peer dependencies, they are not automatically installed when you install this library. You need to manually install them in your project, if not already present. This approach helps to avoid version conflicts and reduce bundle size.

Basic Usage

1// App.tsx
2import { SmokeScene } from "react-smoke";
3import { useMemo } from "react";
4import * as THREE from "three";
5
6export default function App() {
7  const smokeColor = useMemo(() => new THREE.Color("red"), []);
8  
9  return (
10    <div
11      style={{
12        width: "100vw",
13        height: "100vh",
14        position: "fixed",
15        top: 0,
16        left: 0,
17      }}
18    >
19      <SmokeScene
20        smoke={{
21          color: smokeColor,
22          density: 50,
23          enableRotation: true,
24        }} 
25      />
26    </div>
27  );
28}

This renders smoke effects using the default smoke texture. <SmokeScene/> is a wrapper around the Canvas component from @react-three/fiber. You can customize it or use it as a starting point for your own smoke effects.

Advanced Usage

If you already have a Three.js scene set up, you can use the <Smoke/> component to render smoke effects. This provides more control over the smoke effects and allows you to integrate them into existing scenes.

1// App.tsx
2import { Smoke } from "react-smoke";
3import { Canvas } from "@react-three/fiber";
4import { Suspense, useMemo } from "react";
5import * as THREE from "three";
6
7export default function App() {
8  const bgColor = useMemo(() => new THREE.Color("black"), []);
9  const smokeColor = useMemo(() => new THREE.Color("white"), []);
10
11  return (
12    <div
13      style={{
14        width: "100vw",
15        height: "100vh",
16        position: "fixed",
17        top: 0,
18        left: 0,
19      }}
20    >
21      <Canvas
22        camera={{ fov: 60, position: [0, 0, 500], far: 6000 }}
23        scene={{
24          background: bgColor,
25        }}
26      >
27        <Suspense fallback={null}>
28          <Smoke
29            color={smokeColor}
30            density={50}
31            enableRotation={true}
32            rotation={[0, 0, 0.2]}
33          />
34        </Suspense>
35      </Canvas>
36    </div>
37  );
38}

Components

• <SmokeScene/>

The <SmokeScene/> component is a wrapper around the Canvas component from @react-three/fiber. It provides a simple way to render smoke effects in your application. It is a good starting point for beginners or users who want to quickly integrate smoke effects into their applications.

Props

1/**
2 * The smoke scene properties. Supports all properties from the Canvas component.
3 */
4export type SmokeSceneProps = Omit<CanvasProps, "children"> &
5  PropsWithChildren<{
6    /**
7     * The smoke properties.
8     * This will be used to render the smoke component.
9     */
10    smoke?: SmokeProps;
11
12    /**
13     * The fallback component to display while the smoke component is loading.
14     */
15    suspenseFallback?: ReactNode;
16
17    /**
18     * Whether to disable the default lights.
19     * @default false
20     */
21    disableDefaultLights?: boolean;
22
23    /**
24     * The ambient light properties.
25     */
26    ambientLightProps?: AmbientLightProps;
27
28    /**
29     * The directional light properties.
30     */
31    directionalLightProps?: DirectionalLightProps;
32  }>;

Prop	Type	Required	Default
smoke	SmokeProps	No	Default <Smoke/> props
suspenseFallback	ReactNode	No	None
disableDefaultLights	boolean	No	false
ambientLightProps	AmbientLightProps	No	intensity=1
directionalLightProps	DirectionalLightProps	No	intensity=1 position=[-1, 0, 1]

• <Smoke/>

The <Smoke/> component is a low-level component that provides more control over the smoke effects. It is a good choice for users who want to customize the smoke effects or integrate them into existing scenes.

Props

1/**
2 * A three-axis value.
3 */
4export type ThreeAxisValue = [x: number, y: number, z: number];
5
6export type SmokeProps = {
7  /**
8   * Whether to enable frustum culling. When enabled, particles outside the camera's view will not be updated.
9   * @default true
10   */
11  enableFrustumCulling?: boolean;
12
13  /**
14   * The turbulence strength.
15   * This value determines the strength of the turbulence applied to the particles.
16   * @default [0.01, 0.01, 0.01]
17   */
18  turbulenceStrength?: ThreeAxisValue;
19
20  /**
21   * Whether to enable turbulence.
22   * @default false
23   */
24  enableTurbulence?: boolean;
25
26  /**
27   * The maximum velocity.
28   * This value determines the maximum velocity of the particles on each axis.
29   * @default [30, 30, 0]
30   */
31  maxVelocity?: ThreeAxisValue;
32
33  /**
34   * The velocity reset factor.
35   * This factor is used to reset the velocity of particles that exceed the bounds of the smoke effect particles.
36   * @default 10
37   */
38  velocityResetFactor?: number;
39
40  /**
41   * The minimum bounds.
42   * This value determines the minimum bounds of the particles.
43   * @default [-800, -800, -800]
44   */
45  minBounds?: ThreeAxisValue;
46
47  /**
48   * The maximum bounds.
49   * This value determines the maximum bounds of the particles.
50   * @default [800, 800, 800]
51   */
52  maxBounds?: ThreeAxisValue;
53
54  /**
55   * The opacity of the particles.
56   * @default 0.5
57   */
58  opacity?: number;
59
60  /**
61   * The color of the particles.
62   * @default THREE.Color(0xffffff)
63   */
64  color?: Color;
65
66  /**
67   * The density of the particles.
68   * This value determines the number of particles to generate.
69   * @default 50
70   */
71  density?: number;
72
73  /**
74   * The size of the particles.
75   * This value determines the size of each particle.
76   * @default [1000, 1000, 1000]
77   */
78  size?: ThreeAxisValue;
79
80  /**
81   * Whether to cast shadows.
82   * @default false
83   */
84  castShadow?: boolean;
85
86  /**
87   * Whether to receive shadows.
88   * @default false
89   */
90  receiveShadow?: boolean;
91
92  /**
93   * The strength of the wind.
94   * This value determines the strength of the wind applied to the particles.
95   * @default [0.01, 0.01, 0.01]
96   */
97  windStrength?: ThreeAxisValue;
98
99  /**
100   * The direction of the wind.
101   * This value determines the direction of the wind applied to the particles.
102   * @default [1, 0, 0]
103   */
104  windDirection?: ThreeAxisValue;
105
106  /**
107   * Whether to enable wind.
108   * @default false
109   */
110  enableWind?: boolean;
111
112  /**
113   * Whether to enable rotation.
114   * @default false
115   */
116  enableRotation?: boolean;
117
118  /**
119   * The rotation of the particles.
120   * This value determines the rotation of the particles on each axis.
121   * @default [0, 0, 0.1]
122   */
123  rotation?: ThreeAxisValue;
124
125  /**
126   * The paths of the textures to use for the particles.
127   * @default [defaultSmokeImage]
128   */
129  textures?: [string, ...rest: string[]];
130
131  /**
132   * The particle geometry generator function.
133   * @default getDefaultParticleGeometryGenerator()
134   */
135  particleGeometry?: ParticleGeometryGenerator;
136
137  /**
138   * The particle material generator function.
139   * @default getDefaultParticleMaterialGenerator()
140   */
141  particleMaterial?: ParticleMaterialGenerator;
142};

Prop	Type	Required	Default
enableFrustumCulling	boolean	No	true
turbulenceStrength	ThreeAxisValue	No	[0.01, 0.01, 0.01]
enableTurbulence	boolean	No	false
maxVelocity	ThreeAxisValue	No	[30, 30, 0]
velocityResetFactor	number	No	10
minBounds	ThreeAxisValue	No	[-800, -800, -800]
maxBounds	ThreeAxisValue	No	[800, 800, 800]
opacity	number	No	0.5
color	THREE.Color	No	THREE.Color(0xffffff)
density	number	No	50
size	ThreeAxisValue	No	[1000, 1000, 1000]
castShadow	boolean	No	false
receiveShadow	boolean	No	false
windStrength	ThreeAxisValue	No	[0.01, 0.01, 0.01]
windDirection	ThreeAxisValue	No	[1, 0, 0]
enableWind	boolean	No	false
enableRotation	boolean	No	false
rotation	ThreeAxisValue	No	[0, 0, 0.1]
textures	string[]	No	[defaultSmokeTexture]
particleGeometry	ParticleGeometryGenerator	No	getDefaultParticleGeometryGenerator()
particleMaterial	ParticleMaterialGenerator	No	getDefaultParticleMaterialGenerator

Particle Geometry Generator

The ParticleGeometryGenerator function is used to generate the geometry of the particles. It is a function that takes the index of the particle and the smoke properties (size and density) as arguments and returns a buffer geometry. This allows you to customize the geometry of the particles to create unique smoke effects.

1/**
2 * A particle geometry generator function.
3 * @param index The index of the particle.
4 * @param props The smoke properties.
5 *
6 * @returns A buffer geometry.
7 */
8export type ParticleGeometryGenerator = (
9  index: number,
10  props: Required<Pick<SmokeProps, "size" | "density">>,
11) => BufferGeometry;

A default implementation is provided by the library. You can use it as a starting point for your own implementations:

1/**
2 * Returns a default particle geometry generator function.
3 * This generator preserves and reuses a single geometry for all particles.
4 * @returns A particle geometry generator function.
5 */
6export const getDefaultParticleGeometryGenerator = (): ParticleGeometryGenerator => {
7    let geometry: THREE.PlaneGeometry;
8
9    return (_, { size }) => {
10      if (!geometry) {
11        geometry = new THREE.PlaneGeometry(size[0], size[1]);
12      }
13
14      return geometry;
15    };
16  };

Particle Material Generator

The ParticleMaterialGenerator function is used to generate the material of the particles. It is a function that takes the smoke properties as an argument and returns a material. This allows you to customize the material of the particles to create unique smoke effects.

1/**
2 * A particle material generator function.
3 * @param index The index of the particle.
4 * @param textures The textures to use for the materials.
5 * @param props The smoke properties.
6 *
7 * @returns A material.
8 */
9export type ParticleMaterialGenerator = (
10  index: number,
11  textures: Texture[],
12  props: Required<Pick<SmokeProps, "opacity" | "density" | "color">>,
13) => Material;

A default implementation is provided by the library. You can use it as a starting point for your own implementations:

1/**
2 * Returns a default particle material generator function.
3 * This generator creates and reuses materials based on the provided textures and color.
4 * A material is generated for each texture.
5 * @returns A particle material generator function.
6 */
7export const getDefaultParticleMaterialGenerator = (): ParticleMaterialGenerator => {
8    let materials: THREE.MeshLambertMaterial[];
9
10    return (index, textures, { opacity, color }) => {
11      if (!materials) {
12        materials = [];
13
14        for (let i = 0; i < textures.length; i++) {
15          materials.push(
16            new THREE.MeshLambertMaterial({
17              map: textures[i],
18              transparent: true,
19              opacity: opacity,
20              depthWrite: false,
21              color: color,
22              polygonOffset: true,
23              polygonOffsetFactor: 1,
24              polygonOffsetUnits: 1,
25            }),
26          );
27        }
28      }
29
30      return materials[index % materials.length];
31    };
32};

The library provides one additional particle material generator that can generate materials with different colors. This generator can be used to create more visually appealing smoke effects. The number of materials generated can be based on the provided textures count, colors count, or density:

1/**
2 * Returns a particle material generator function that generates materials with multiple colors.
3 * The total number of materials generated can be based on either the number of colors, textures, or a specified density.
4 * @param colors An array of colors to be used for the materials. At least two colors are required.
5 * @param sizeDeterminant Determines how many materials to generate based on the colors, textures, or a specified density.
6 * @returns A particle material generator function.
7 */
8export const getMultiColorParticleMaterialGenerator = (
9    colors: [THREE.Color, THREE.Color, ...rest: THREE.Color[]],
10    sizeDeterminant: "colors" | "textures" | "density" = "colors",
11  ): ParticleMaterialGenerator => {
12    let materials: THREE.MeshLambertMaterial[];
13
14    return (index, textures, { opacity, density }) => {
15      if (!materials) {
16        materials = [];
17
18        const commonProps = {
19          transparent: true,
20          opacity: opacity,
21          depthWrite: false,
22          polygonOffset: true,
23          polygonOffsetFactor: 1,
24          polygonOffsetUnits: 1,
25        };
26
27        if (sizeDeterminant === "textures") {
28          for (let i = 0; i < textures.length; i++) {
29            materials.push(
30              new THREE.MeshLambertMaterial({
31                map: textures[i],
32                color: colors[i % colors.length],
33                ...commonProps,
34              }),
35            );
36          }
37        } else if (sizeDeterminant === "colors") {
38          for (let i = 0; i < colors.length; i++) {
39            materials.push(
40              new THREE.MeshLambertMaterial({
41                map: textures[i % textures.length],
42                color: colors[i],
43                ...commonProps,
44              }),
45            );
46          }
47        } else {
48          for (let i = 0; i < density; i++) {
49            materials.push(
50              new THREE.MeshLambertMaterial({
51                map: textures[i % textures.length],
52                color: colors[i % colors.length],
53                ...commonProps,
54              }),
55            );
56          }
57        }
58      }
59
60      return materials[index % materials.length];
61    };
62  };

The in-built particle material generators can be used as a starting point for your own implementations. They provide a good foundation for creating custom smoke effects.

Contributing

Contributions are welcome! Please read our Code of Conduct and Contributing