@threlte/extras

transitions

The plugin transitions enables Svelte-like transitions on Threlte components.

Usage

To use Threlte transitions, you need to inject the plugin first via invoking transitions(). All child <T> components will then accept transition properties.

createTransition

Threlte Transitions use Svelte transitions under the hood and therefore use a similar API. The function createTransition is used to conveniently create a transition.

import type { Material } from 'three'
import { createTransition } from '@threlte/extras'
import { cubicOut } from 'svelte/easing'

const fade = createTransition<Material>((ref) => {
  ref.transparent = true
  return {
    tick(t) {
      // t is [0,1]
      ref.opacity = t
    },
    easing: cubicOut,
    duration: 400,
    delay: 100
  }
})

The transition fade can now be applied to all <T> components that instantiate classes extending THREE.Material like THREE.MeshBasicMaterial or THREE.MeshStandardMaterial:

<T.MeshStandardMaterial transition={fade} />

Transition Directions

Run a transition only when the component mounts:

<T.MeshStandardMaterial in={fade} />

Run a transition only when the component unmounts:

<T.MeshStandardMaterial out={fade} />

Run a transition when the component mounts or unmounts:

<T.MeshStandardMaterial transition={fade} />

To react on different transition directions in the same transition, you can use the direction parameter:

import { createTransition } from '@threlte/extras'

// direction is 'in', 'out' or 'both'
const fly = createTransition((ref, { direction }) => {
  // …
})

Transition Parameters

To make reusing transitions throughout your application easier, make createTransition the return value of a function that accepts parameters:

import { createTransition } from '@threlte/extras'

const scale = (duration: number) => {
  return createTransition((ref) => {
    return {
      tick(t) {
        ref.scale.setScalar(t)
      },
      duration
    }
  })
}

The transition can now be used like this:

<T.Mesh transition={scale(400)} />

Transition Events

Similar to Svelte transitions, Threlte transitions also emit events:

{#if visible}
  <T.Mesh
    {geometry}
    {material}
    transition={fade}
    onintrostart={() => console.log('intro started')}
    onoutrostart={() => console.log('outro started')}
    onintroend={() => console.log('intro ended')}
    onoutroend={() => console.log('outro ended')}
  />
{/if}

Limitations

Transitions are always global

Threlte transitions cannot be declared as local and therefore transitions will run when any upstream component mounts or unmounts.

Threlte transitions always “intro”

As opposed to Svelte transitions, in and transition transitions will also run on the first render of a component.