@canvas3/nuxt

Canvas3 Nuxt Module

A Nuxt module that integrates ThreeJS into your Nuxt app, providing a smooth-scroll engine, WebGL image effects, scroll-triggered animations, and a shader/animation API — all wired together through Vue directives and a global Canvas3 composable-like utility.

✨ Example use cases

Features

• 🎬 Smooth scroll engine – Custom lerp-based scroll with speed tracking, fixed-to-parent elements, and mobile breakpoint handling.
• 🖼 WebGL image replacement – Turn any <img> into a shader-driven ThreeJS mesh via the v-canvas3-image directive.
• 👀 Scroll-triggered activation – Activate/deactivate elements (and their linked meshes) as they enter/leave the viewport with v-canvas3-scroll-action.
• 🎨 Custom shader support – Bring your own vertex/fragment shaders per mesh, plus a global post-processing scroll shader pass.
• ⏱ Animation scheduler – Register callbacks that run conditionally on scroll, resize, mouse move, or custom render triggers, avoiding unnecessary renders.
• 🖱 Mouse-reactive uniforms – Automatic uMouse / uMouseMovement uniforms updated on mouse movement for interactive shaders.
• 📱 Responsive & reduced-motion aware – Built-in isMobile / prefersReducedMotion / disabled options to gracefully degrade.
• 🧩 Global utility API – Canvas3 import exposes scene, camera, renderer, mesh, and scroll controls anywhere in your app.
• 🏗 Layout-based setup – Ships a ready-to-use canvas3 Nuxt layout that wraps your page content with the scroll/canvas containers.

Quick Setup

Install the module to your Nuxt application with one command:

npx nuxi module add canvas3-nuxt

That's it! You can now use the Canvas3 module in your Nuxt app ✨

1. Use the canvas3 layout

<!-- pages/index.vue -->
<script setup>
definePageMeta({ layout: 'canvas3' })
</script>

2. Enable Canvas3 in the layout

The layout exposes canvas3enabled and canvas3options props. Enable it once your options (shaders, fonts, etc.) are ready:

<!-- app.vue or a wrapping component -->
<template>
  <NuxtLayout
    :canvas3enabled="ready"
    :canvas3options="canvas3Options"
    @canvas3-ready="onReady"
  >
    <NuxtPage />
  </NuxtLayout>
</template>

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

const ready = ref(false)
const canvas3Options = {
  shaders: {
    default: { vertexShader: defaultVert, fragmentShader: defaultFrag },
    scroll: { vertexShader: scrollVert, fragmentShader: scrollFrag },
  },
  activateMeshOptions: {
    image: { uAniInImage: { value: 1, duration: 1, ease: 'power2.out' } },
  },
  canvasElement: { zIndex: -1 },
  prefersReducedMotion: false,
  isMobile: false,
  disabled: false,
}

function onReady() {
  ready.value = true
}

ready.value = true
</script>

Directives

v-canvas3-image

Converts an <img> element into a ThreeJS mesh rendered in sync with the DOM element's position, size, and scroll offset. The original image is hidden (opacity set to 0) and replaced visually by the WebGL mesh.

Requirements: must be applied to an <img> tag.

Binding value (Canvas3ImageBinding):

<template>
  <img
    src="https://raw.githubusercontent.com/kmettom/Canvas3Nuxt/HEAD/images/hero.jpg"
    alt="Hero"
    v-canvas3-image="{
      shaderName: 'wave',
      uniforms: {
        vectorVNoise: { value: [2, 2], duration: 0 },
      },
      activateMeshUniforms: {
        uAniInImage: { value: 1, duration: 1.2, ease: 'power2.out' },
      },
    }"
  >
</template>

Behavior notes:

• Waits for the image to load (complete/load event) and for the canvas to be initiated before creating the mesh.
• Automatically re-creates the mesh if src changes.
• Cleans up (disposes geometry/material/texture, removes from scene) on unmount.
• Respects canvas3options.disabled, adding a .reduced-motion class instead of creating a mesh.

v-canvas3-scroll-action

Marks an element to be tracked by the scroll engine. When the element enters/exits the configured viewport range, it toggles an active class, fires callbacks, and (optionally) activates any WebGL image meshes nested inside it (matched via data-mesh-id, set automatically by v-canvas3-image).

Binding value (ScrollActionBindOptionType):

<template>
  <section
    v-canvas3-scroll-action="{
      activeRange: 0.8,
      activateCallback: onSectionActive,
      deactivateCallback: onSectionInactive,
    }"
  >
    <img src="https://raw.githubusercontent.com/kmettom/Canvas3Nuxt/HEAD/images/panel.jpg" alt="Panel" v-canvas3-image="{}">
  </section>
</template>

<script setup>
function onSectionActive(item) {
  console.log('Section entered view', item.elNode)
}
function onSectionInactive(item) {
  console.log('Section left view', item.elNode)
}
</script>

Parallax example:

<div v-canvas3-scroll-action="{ scrollSpeed: { value: 0.3 } }">
  <div>Moves at 0.3x scroll speed</div>
</div>

Pin-to-parent example:

<div id="stickyContainer" style="height: 200vh;">
  <div
    v-canvas3-scroll-action="{
      fixToParent: { containerId: 'stickyContainer', fixPosition: 0.5, margin: 0 },
    }"
  >
    <div>Pinned child, centered at 50% viewport while parent is in view</div>
  </div>
</div>

Global Canvas3 Utility

The module auto-imports a Canvas3 utility (via Nuxt's addImports) that exposes scene/camera/renderer access and imperative controls, independent of the directives.

Animation callback example:

import { Canvas3 } from '#imports'

Canvas3.addAnimationToRender('rotateLogo', {
  onScroll: false,
  onResize: false,
  onMouseMove: true,
  onAnimationsRender: false,
  render: false,
  animationCallback: () => {
    const mesh = Canvas3.getMeshFromSceneByName('logoMesh')
    if (mesh) mesh.rotation.y += 0.01
  },
})

// later, to stop it:
Canvas3.removeAnimationFromRender('rotateLogo')

Manual scroll control example:

import { Canvas3 } from '#imports'

function goToSection() {
  Canvas3.scrollToElBySelector('#contact', 0, -80)
}

Options Reference (Canvas3OptionsType)

Contribution

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release