Hooks & Events

Shaders provides lifecycle hooks that let you respond to key moments in the rendering pipeline. This is useful for orchestrating UI transitions, hiding loading states, or triggering animations once the shader is ready.

onReady

The onReady hook fires once after the GPU has compiled the shader and the first frame is ready to render. This is the ideal moment to fade in the shader, remove a loading skeleton, or start a dependent animation.

<template>
  <Shader @ready="onShaderReady" :style="{ opacity: visible ? 1 : 0, transition: 'opacity 0.5s' }">
    <Circle color="#ff0088" />
  </Shader>
</template>

<script setup>
import { ref } from 'vue'

const visible = ref(false)

function onShaderReady() {
  visible.value = true
}
</script>

import { useState } from 'react'

function App() {
  const [visible, setVisible] = useState(false)

  return (
    <Shader
      onReady={() => setVisible(true)}
      style={{ opacity: visible ? 1 : 0, transition: 'opacity 0.5s' }}
    >
      <Circle color="#ff0088" />
    </Shader>
  )
}

<script>
  let visible = $state(false)
</script>

<Shader onready={() => visible = true} style:opacity={visible ? 1 : 0} style:transition="opacity 0.5s">
  <Circle color="#ff0088" />
</Shader>

import { createSignal } from 'solid-js'

function App() {
  const [visible, setVisible] = createSignal(false)

  return (
    <Shader
      onReady={() => setVisible(true)}
      style={{ opacity: visible() ? 1 : 0, transition: 'opacity 0.5s' }}
    >
      <Circle color="#ff0088" />
    </Shader>
  )
}

const canvas = document.getElementById('my-canvas')

// Start hidden
canvas.style.opacity = '0'
canvas.style.transition = 'opacity 0.5s'

const shader = await createShader(canvas, {
  components: [
    { type: 'Circle', id: 'c1', props: { color: '#ff0088' } }
  ]
}, {
  onReady: () => {
    canvas.style.opacity = '1'
  }
})

Timing

onReady fires after the shader's node tree has been compiled into a GPU pipeline and is actively rendering. This means:

The WebGPU renderer is initialized
All child shader components have registered
The composed shader pipeline has been compiled
The first frame is ready to display

The callback fires once per shader lifecycle. If the component is unmounted and remounted, it will fire again after recompilation.

Notes

onReady is called asynchronously (via microtask) so the rendered frame is available by the time your callback executes
If the <Shader> component starts off-screen and initializes lazily when scrolled into view, onReady fires after that deferred initialization completes

Unsupported browsers

Shaders is WebGPU-only. On a browser or driver that can't provide a working GPU device — an older Safari, Firefox with WebGPU still behind a flag, a blocklisted or exhausted driver — the canvas simply stays transparent. onReady never fires, nothing is written to the console, and the rest of your page is completely unaffected.

If you want to render your own fallback instead of empty space, you have two options.

Check before you mount

isWebGPUSupported() is a synchronous check for whether the browser exposes WebGPU at all. getWebGPUSupport() goes further and actually asks for an adapter, so it also catches blocklisted drivers — its result is cached for the page.

<template>
  <Shader v-if="supported">
    <Circle color="#ff0088" />
  </Shader>
  <div v-else class="fallback" />
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { Shader, Circle, getWebGPUSupport } from 'shaders/vue'

const supported = ref(false)
onMounted(async () => {
  supported.value = (await getWebGPUSupport()).supported
})
</script>

import { useState, useEffect } from 'react'
import { Shader, Circle, getWebGPUSupport } from 'shaders/react'

function App() {
  const [supported, setSupported] = useState(false)
  useEffect(() => {
    getWebGPUSupport().then(({ supported }) => setSupported(supported))
  }, [])

  return supported
    ? <Shader><Circle color="#ff0088" /></Shader>
    : <div className="fallback" />
}

<script>
  import { Shader, Circle, getWebGPUSupport } from 'shaders/svelte'

  let supported = $state(false)
  getWebGPUSupport().then((info) => { supported = info.supported })
</script>

{#if supported}
  <Shader><Circle color="#ff0088" /></Shader>
{:else}
  <div class="fallback"></div>
{/if}

import { createSignal, onMount, Show } from 'solid-js'
import { Shader, Circle, getWebGPUSupport } from 'shaders/solid'

function App() {
  const [supported, setSupported] = createSignal(false)
  onMount(async () => setSupported((await getWebGPUSupport()).supported))

  return (
    <Show when={supported()} fallback={<div class="fallback" />}>
      <Shader><Circle color="#ff0088" /></Shader>
    </Show>
  )
}

import { createShader, getWebGPUSupport } from 'shaders/js'

const { supported } = await getWebGPUSupport()
if (supported) {
  await createShader(canvas, preset)
} else {
  canvas.replaceWith(fallbackElement)
}

React to it after the fact

The unavailable event fires at most once if the GPU can't be used — either because it was never available, or because it became unusable later (device loss with no recovery, an out-of-memory refusal, a driver that can't run the compiled pipeline). By the time it fires the canvas has already been cleared and every GPU resource released.

<template>
  <Shader @unavailable="showFallback = true">
    <Circle color="#ff0088" />
  </Shader>
</template>

<Shader onUnavailable={(reason) => setShowFallback(true)}>
  <Circle color="#ff0088" />
</Shader>

<Shader onunavailable={() => (showFallback = true)}>
  <Circle color="#ff0088" />
</Shader>

<Shader onUnavailable={() => setShowFallback(true)}>
  <Circle color="#ff0088" />
</Shader>

await createShader(canvas, preset, {
  onError: (reason) => {
    // 'unsupported' | 'no-adapter' | 'no-device' | 'init-failed'
    // | 'device-lost' | 'out-of-memory' | 'gpu-error' | 'render-failed'
    // | 'limit-exceeded' | 'unrecoverable'
    showFallback(reason)
  }
})

Debugging

Shaders keeps quiet in production on purpose — an embedded background effect must never fill a host page's console with errors the visitor can do nothing about. When you need to see what the renderer is actually doing, switch diagnostics on:

localStorage.setItem('shaders:debug', '1')  // persists for the origin
// or, in code:
import { setShadersDebug } from 'shaders/vue'
setShadersDebug(true)

Telemetry

Anonymous usage data collection and how to disable it

Shaders MCP (Pro)

Connect your AI coding agent to Shaders and build stunning effects without leaving your workflow