You're viewing the v10 deployment.

Loading Textures

Let's load some fancy textures.

All textures used in this chapter were downloaded from ambientCG (formerly cc0textures).

Using `TextureLoader` and `useLoader`

To load the textures we will use the TextureLoader from three.js in combination with useLoader that will allow us to pass the location of the texture and get the map back.

It's better to explain with code, let's say you downloaded this texture and placed it in the public folder of your site, to get the color map from it you could do:

const colorMap = useLoader(TextureLoader, 'PavingStones092_1K_Color.jpg')

Let's then with this information create a small scene where we can use this texture:

import { Suspense } from 'react'
import { Canvas, useLoader } from '@react-three/fiber'
import { TextureLoader } from 'three'

function Scene() {
  const colorMap = useLoader(TextureLoader, 'PavingStones092_1K_Color.jpg')
  return (
    <>
      <ambientLight intensity={0.2} />
      <directionalLight />
      <mesh>
        <sphereGeometry args={[1, 32, 32]} />
        <meshStandardMaterial />
      </mesh>
    </>
  )
}

export default function App() {
  return (
    <Canvas>
      <Suspense fallback={null}>
        <Scene />
      </Suspense>
    </Canvas>
  )
}

If everything went according to plan, you should now be able to apply this texture to the sphere like so:

<meshStandardMaterial map={colorMap} />

Awesome! That works but we have a lot more textures to import and do we have to create a different useLoader for each of them?

That's the great part! You don't, the second argument is an array where you can pass all the textures you have and the maps will be returned and ready to use:

const [colorMap, displacementMap, normalMap, roughnessMap, aoMap] = useLoader(TextureLoader, [
  'PavingStones092_1K_Color.jpg',
  'PavingStones092_1K_Displacement.jpg',
  'PavingStones092_1K_Normal.jpg',
  'PavingStones092_1K_Roughness.jpg',
  'PavingStones092_1K_AmbientOcclusion.jpg',
])

Now we can place them in our mesh like so:

<meshStandardMaterial
  map={colorMap}
  displacementMap={displacementMap}
  normalMap={normalMap}
  roughnessMap={roughnessMap}
  aoMap={aoMap}
/>

The displacement will probably be too much, usually setting it to 0.2 will make it look good. Our final code would look something like:

function Scene() {
  const [colorMap, displacementMap, normalMap, roughnessMap, aoMap] = useLoader(TextureLoader, [
    'PavingStones092_1K_Color.jpg',
    'PavingStones092_1K_Displacement.jpg',
    'PavingStones092_1K_Normal.jpg',
    'PavingStones092_1K_Roughness.jpg',
    'PavingStones092_1K_AmbientOcclusion.jpg',
  ])
  return (
    <mesh>
      {/* Width and height segments for displacementMap */}
      <sphereGeometry args={[1, 100, 100]} />
      <meshStandardMaterial
        displacementScale={0.2}
        map={colorMap}
        displacementMap={displacementMap}
        normalMap={normalMap}
        roughnessMap={roughnessMap}
        aoMap={aoMap}
      />
    </mesh>
  )
}

Using `useTexture`

In v10, useTexture is built into @react-three/fiber, so there is no need to import TextureLoader or install drei for this hook. The same textures can be loaded with:

import { useTexture } from '@react-three/fiber'

...

const [colorMap, displacementMap, normalMap, roughnessMap, aoMap] = useTexture([
  'PavingStones092_1K_Color.jpg',
  'PavingStones092_1K_Displacement.jpg',
  'PavingStones092_1K_Normal.jpg',
  'PavingStones092_1K_Roughness.jpg',
  'PavingStones092_1K_AmbientOcclusion.jpg',
])

The useTexture hook from @react-three/drei still works, but is not required for v10.

You can also use object-notation which is the most convenient:

const props = useTexture({
  map: 'PavingStones092_1K_Color.jpg',
  displacementMap: 'PavingStones092_1K_Displacement.jpg',
  normalMap: 'PavingStones092_1K_Normal.jpg',
  roughnessMap: 'PavingStones092_1K_Roughness.jpg',
  aoMap: 'PavingStones092_1K_AmbientOcclusion.jpg',
})

return (
  <mesh>
    <sphereGeometry args={[1, 32, 32]} />
    <meshStandardMaterial {...props} />
  </mesh>
)

You can play with the sandbox and see how it looks:

The texture registry with `useTextures`

In v10, useTexture is built into @react-three/fiber and, by default, enrolls what it loads into a global texture registry. useTextures() lets you reach those textures from anywhere and manage their GPU lifetime, without threading refs through your component tree.

See Textures for the registry API, the cache option, refcounted disposal, and when the registry is reactive.

Edit this page