/r3f-materials

name: r3f-materials
description: Choose and configure React Three Fiber surface materials, PBR, transparency, and transmission. Use for mesh appearance and material cost; use shader guidance for custom GLSL or TSL code.

React Three Fiber materials

Inspect the installed renderer, Three.js, Fiber, and Drei versions first. Examples use Fiber 9 / React 19 with WebGL. Do not assume Drei shader-based materials work unchanged with WebGPU.

Choose the least complex material that fits

| Need | Starting point | Constraint | | --- | --- | --- | | Unlit artwork or UI surface | `meshBasicMaterial` | Still participates in output color/tone-mapping policy | | Ordinary PBR surface | `meshStandardMaterial` | Metals especially need an environment or suitable lights | | Clearcoat, transmission, sheen | `meshPhysicalMaterial` | Enable only needed features; more shader work | | Stylized lighting | `meshToonMaterial` | Needs lights; gradient maps need appropriate filtering | | Normal debugging | `meshNormalMaterial` | Useful for geometry/normal inspection | | Custom shading | ShaderMaterial or node material | Match WebGL/GLSL versus WebGPU/TSL |

PBR surface with environment lighting

Mount below Canvas. This small procedural environment avoids a remote preset dependency.

import { Environment, Lightformer } from '@react-three/drei'

export default function Example() {
  return (
    <>
      <Environment resolution={64} frames={1}>
        <Lightformer position={[0, 3, 2]} scale={[5, 5, 1]} intensity={3} />
      </Environment>
      <mesh>
        <sphereGeometry args={[1, 32, 24]} />
        <meshStandardMaterial color="goldenrod" metalness={1} roughness={0.3} />
      </mesh>
    </>
  )
}

PBR and color decisions

• Use metalness near 0 for dielectrics and near 1 for bare metals; intermediate values usually describe mixtures or texture filtering. Roughness controls microsurface response, not opacity.
• Color/albedo and emissive textures use sRGB; roughness, metalness, normal, AO, and masks use `NoColorSpace`. Preserve correctly loaded glTF texture metadata.
• Maps multiply scalar settings: a metalness map with `metalness={0}` has no effect; an emissive map needs a nonblack emissive color.
• A normal map alters shading; a displacement map alters vertices and needs enough geometry subdivisions. Normal maps do not alter the silhouette.
• An emissive surface does not illuminate nearby geometry or automatically produce a halo. Add appropriate lighting and a bloom pipeline when those effects are required.
• PBR appearance changed across recent Three.js releases. Validate with controlled lighting/exposure; do not blindly compensate for an upgrade with extra lights or color conversion.

Transparency and glass

• `opacity < 1` needs `transparent` for ordinary alpha blending. For cutout foliage or decals, consider `alphaTest` to avoid sorting artifacts; choose soft transparency only when required.
• `depthWrite={false}` can help some transparent layers but is not a universal fix. Test overlap order, backfaces, and intersection with opaque objects.
• Use physical transmission for glass, generally with opacity 1 and a meaningful `thickness`/IOR. Transmission is not equivalent to ordinary transparency.
• Drei `MeshTransmissionMaterial` and `MeshReflectorMaterial` add scene renders. Start with low resolution/samples, and measure before enabling backside passes or one independent buffer per object.
• A shared transmission sampler is cheaper in some scenes but cannot reproduce all visibility between transparent/transmissive objects. Read the helper's documentation before choosing it.
• Do not enable `DoubleSide` everywhere: it changes rendering cost and may hide incorrect winding or normals.

Lifetime and updates

• Share materials when objects should share appearance. Clone before changing one instance's color, maps, or uniforms; a cached glTF material may be used elsewhere.
• R3F owns declarative material children. Externally allocated/shared materials need explicit lifecycle ownership. Disposing a material does not dispose its textures.
• Animate ordinary material properties through typed refs. Value changes such as roughness or color do not require `needsUpdate`; shader feature changes such as adding/removing a map can require recompilation.
• Material arrays require matching geometry groups. An array alone does not assign arbitrary materials to faces.

Verify

Render under the intended lighting and output pipeline, then test transparent overlaps, shadows, and repeated mount/unmount. Compare GPU cost before adding transmission or reflection passes.

Sources

• [MeshStandardMaterial](https://threejs.org/docs/#MeshStandardMaterial), [MeshPhysicalMaterial](https://threejs.org/docs/#MeshPhysicalMaterial), [Material](https://threejs.org/docs/#Material).
• [Drei transmission material](https://drei.docs.pmnd.rs/shaders/mesh-transmission-material), [reflector material](https://drei.docs.pmnd.rs/shaders/mesh-reflector-material).
• [Color management](https://threejs.org/manual/en/color-management.html), [Three.js migration guide](https://github.com/mrdoob/three.js/wiki/Migration-Guide).