Advanced

Custom Abstractions

A lot of the components you will find in the package @threlte/extras are abstractions on top of the <T> component. These abstractions provide extra functionality like automatically invalidating the frame or providing default values or extra props.

A common use case for custom abstractions is to create a component that is a fixed entity in your Threlte app which you want to reuse in multiple places. As an example, let’s create a component that is made up from multiple <T> components resembling a floor and a cube on top:

Tile.svelte

<script>
  import { T } from '@threlte/threlte'
  import { MathUtils } from 'three'
  
  let { children } = $props()
</script>

<T.Group>
  <!-- 1x1x1 Cube -->
  <T.Mesh position.y={0.5}>
    <T.BoxGeometry />
    <T.MeshStandardMaterial />
  </T.Mesh>

  <!-- 2x2 Floor -->
  <T.Mesh rotation.x={-90 * MathUtils.DEG2RAD}>
    <T.PlaneGeometry args={[2, 2]} />
    <T.MeshStandardMaterial />
  </T.Mesh>

  {@render children()}
</T.Group>

Let’s see what implementing that component looks like:

Scene.svelte

<script>
  import Tile from './Tile.svelte'
</script>

<Tile />

Props

The <Tile> component is now available in the scene and can be reused as many times as you want. Now we’d like to assign a different position to the <Tile> component in order to move it around. We can do that by passing a position prop to the <Tile> component:

Scene.svelte

<script>
  import Tile from './Tile.svelte'
</script>

<Tile position={[0, 0, 0]} />
<Tile position={[2, 0, 0]} />
<Tile position={[4, 0, 0]} />

The component <Tile> internally needs to use the position prop in order to set the position of the <T> components. We can do that by spreading props on the <T.Group> component at the root hierarchy of <Tile>:

Tile.svelte

<script>
  import { T } from '@threlte/threlte'
  import { MathUtils } from 'three'

  let { children, ...props } = $props()
</script>

<T.Group {...props}>
  <!-- 1x1x1 Cube -->
  <T.Mesh position.y={0.5}>
    <T.BoxGeometry />
    <T.MeshStandardMaterial />
  </T.Mesh>

  <!-- 2x2 Floor -->
  <T.Mesh rotation.x={-90 * MathUtils.DEG2RAD}>
    <T.PlaneGeometry args={[2, 2]} />
    <T.MeshStandardMaterial />
  </T.Mesh>

  {@render children()}
</T.Group>

Types

The following section assumes you use TypeScript.

The last thing we need to do is to add types to our custom abstraction so that editors like VSCode can provide us with autocompletion and type checking. We will create a Tile.d.ts file next to the Tile.svelte file and add the following content:

Tile.d.ts

import type { Props } from '@threlte/core'
import { SvelteComponent } from 'svelte'
import type { Group } from 'three'

export type TileProps = Props<Group> & {
  // Define extra props here.
}

export default class Tile extends SvelteComponent<TileProps> {}

Now we can use the <Tile> component in our scene and get autocompletion and type checking:

Scene.svelte

<script>
  import Tile from './Tile.svelte'
</script>

<!-- Autocompletion and type checking works here. -->
<Tile position={[0, 0, 0]} />

Let’s cross check the types inside our Tile.svelte file by typing the $props rune.

Addtionally, let’s create a bindable ref and pass it to any child components:

Tile.svelte

<script lang="ts">
  import { T } from '@threlte/threlte'
  import { MathUtils } from 'three'
  import type { TileProps } from './Tile.svelte'

  let {
    children,
    ref = $bindable(),
    ...props,
  }: TileProps = $props()
</script>

<T.Group {...props} bind:ref>
  <!-- 1x1x1 Cube -->
  <T.Mesh position.y={0.5}>
    <T.BoxGeometry />
    <T.MeshStandardMaterial />
  </T.Mesh>

  <!-- 2x2 Floor -->
  <T.Mesh rotation.x={-90 * MathUtils.DEG2RAD}>
    <T.PlaneGeometry args={[2, 2]} />
    <T.MeshStandardMaterial />
  </T.Mesh>

  {@render children(ref)}
</T.Group>

Previous Page Plugins

Next Page Migration Guides