r3f-textures

React Three Fiber textures

Inspect installed Three.js, Fiber, Drei, and renderer versions first. Examples target Fiber 9 / React 19 and Three.js r185 with WebGL. Preserve correctly configured assets rather than resetting every texture.

Color versus data

Texture content	Color-space annotation
PNG/JPEG base color or emissive color	SRGBColorSpace
Roughness, metalness, normal, AO, alpha/masks	NoColorSpace
Linear HDR/EXR lighting data	Preserve loader-provided linear metadata

NoColorSpace is not another name for LinearSRGBColorSpace: scalar/vector data has no color space. Do not blanket-convert every map to sRGB.

Load a color map

Mount under Suspense inside Canvas. The file path is an application asset, not a file provided by this skill.

import { useTexture } from '@react-three/drei'
import { SRGBColorSpace } from 'three'

export default function Example() {
  const map = useTexture('/textures/checker.png', (texture) => {
    // This URL is consistently used as a color texture by all consumers.
    texture.colorSpace = SRGBColorSpace
    texture.needsUpdate = true
  })
  return (
    <mesh>
      <planeGeometry args={[3, 3]} />
      <meshStandardMaterial map={map} roughness={1} />
    </mesh>
  )
}

Fiber handles common built-in color map props, and glTF loaders set texture metadata. Explicit annotation is especially important for custom shader uniforms or manually created textures.

Cache and ownership

• useTexture/useLoader cache by loader and URL inputs. The same source can return the same Texture object. Repeat, offset, wrapping, filters, and colorSpace changes can affect every consumer.
• Clone the Texture object before per-instance configuration. Reuse the underlying image where possible; separately dispose only the clone you own. Do not dispose the cached source from an individual consumer.
• Do not clear a loader cache during render. Cache eviction and GPU disposal are separate operations and require knowing that no active consumer still needs the resource.
• Avoid replacing the uniform/texture object every frame; update offsets or owned values directly. On a demand loop, invalidate after imperative changes.

UVs and sampling

• texture.channel = 0 selects uv, 1 selects uv1, then uv2 and uv3. Choose the actual geometry attribute; AO/light maps no longer universally require copying uv into uv2.
• Repeat outside [0, 1] requires RepeatWrapping or MirroredRepeatWrapping. Offset/repeat/rotation are texture transforms; atlas animations generally do not need React state per frame.
• Wrapping, color-space, and upload configuration changes may need texture.needsUpdate. Offset/repeat changes use the texture matrix and do not normally require re-uploading image data.
• For pixel art, use nearest filtering deliberately. For minified surfaces, mipmaps reduce shimmer; cap anisotropy to the renderer's supported maximum and the scene's needs.
• Power-of-two dimensions are not a universal WebGL2 requirement. Size textures for screen coverage, memory, compression-format constraints, and quality rather than an obsolete blanket rule.
• Download size is not GPU memory size. Consider KTX2/Basis where supported; configure renderer capability detection and host decoder/transcoder assets deliberately.
• For a replacement glTF color map, match the model's UV/orientation conventions; a manually loaded texture commonly needs flipY=false. Do not flip already configured glTF maps again.

Specialized textures

• Prefer useVideoTexture when its lifecycle fits. Check autoplay/muting, CORS, user gestures, and source cleanup; changing video resolution may require a new texture. Do not promise autoplay succeeds on every browser.
• Canvas/DataTexture content changes need needsUpdate; data textures should keep data color-space semantics. Creating a texture in a frame loop leaks work/resources unless deliberately managed.
• For render targets, read offscreen rendering. Never sample from a texture while rendering into that same target.
• Keep environment maps on a lighting path (Environment/useEnvironment) rather than assigning a regular 2D image without a suitable mapping/PMREM workflow.

Verify

Test a known color swatch, data maps under changing lights, texture orientation, repeated mounts, and two consumers with different UV transforms. Inspect GPU texture counts; they are counts, not byte-accurate memory measurements.

Sources

• Color management, Texture.
• Drei useTexture, useVideoTexture.
• Fiber 9 texture changes.