<Detailed>

<Detailed> is an abstraction around Three.js’ LOD. A common technique to improve performance is to swap out high-detail models or meshes for low-detail ones at large distances.

Show Code

• App.svelte
• Scene.svelte

<script lang="ts">
  import { Canvas } from '@threlte/core'
  import Scene from './Scene.svelte'
</script>

<div>
  <Canvas>
    <Scene />
  </Canvas>
</div>

<style>
  div {
    height: 100%;
  }
</style>

<script lang="ts">
  import type { LOD } from 'three'
  import { Detailed } from '@threlte/extras'
  import { IcosahedronGeometry } from 'three'
  import { T, useTask } from '@threlte/core'

  type DetailItem = {
    color: number
    distance: number
  }

  const items: DetailItem[] = [
    { color: 0xff_00_00, distance: 0 },
    { color: 0x00_ff_00, distance: 3 },
    { color: 0x00_00_ff, distance: 6 }
  ]

  let detailed = $state.raw<LOD>()

  let time = 0
  useTask((delta) => {
    time += delta
    detailed?.position.setZ(3 * Math.sin(time))
  })
</script>

<Detailed bind:ref={detailed}>
  {#each items as { color, distance }, i}
    {@const detail = items.length - i - 1}
    <T.Mesh
      {distance}
      geometry={new IcosahedronGeometry(1, detail)}
      material.wireframe
      material.color={color}
    />
  {/each}
</Detailed>

Notice that as the mesh’s distance from the camera increases, geometries with fewer vertices are swapped.

The distance between the camera and the <Detailed> component itself is what determines which level-of-detail to use. You can set positions for children but they will not be used in the distance calculation.

Children of <Detailed> accept a distance prop. This prop determines the visibility of each child based on its distance from the camera. If not specified, distance defaults to 0.

<Detailed>
  <T.Mesh>
    <T.BoxGeometry />
  </T.Mesh>
  <T.Mesh distance={10}>
    <T.BoxGeometry />
  </T.Mesh>
</Detailed>

Children of <Detailed> accept a hysteresis prop which can be used to prevent flickering at LOD boundaries. If not specified, hysteresis defaults to 0.

<Detailed>
  <T.Mesh hysteresis={0.5}>
    <T.BoxGeometry />
  </T.Mesh>
</Detailed>

It is fairly common to export a high-detail, medium-detail, and low-detail model from 3D asset creation tools.

Component Signature

<Detailed> extends < T . LOD > and supports all its props, snippets, bindings and events.