Mesh Gradient
Vue

useMeshGradient() (Vue)

Reference for the Vue useMeshGradient composable, reactive instance access, and advanced control.

useMeshGradient()

The useMeshGradient composable creates and manages a MeshGradient instance. It automatically handles the lifecycle of the gradient instance and provides access to the core MeshGradient API for advanced use cases.

Basic Usage

<template>
  <div>My Component</div>
</template>

<script setup lang="ts">
import { useMeshGradient } from '@mesh-gradient/vue'

const { instance } = useMeshGradient()

// instance is available after component mounts
// You can call methods on it when needed
</script>

Return Value

The composable returns an object with the following property:

Prop

Type

When to Use

Use useMeshGradient when you need:

  • Direct access to the MeshGradient instance
  • Custom initialization logic beyond the component's automatic behavior
  • Advanced control over gradient lifecycle
  • Integration with other libraries or custom logic

Lifecycle Management

The composable automatically:

  • Creates a new MeshGradient instance on mount
  • Destroys the instance when the component unmounts
  • Provides the instance through a reactive reference
<template>
  <canvas ref="canvasRef" />
</template>

<script setup lang="ts">
import { useMeshGradient } from '@mesh-gradient/vue'
import { ref, onMounted } from 'vue'

const { instance } = useMeshGradient()
const canvasRef = ref<HTMLCanvasElement>()

onMounted(() => {
  if (!instance.value || !canvasRef.value) return
  
  // Custom initialization logic
  instance.value.init(canvasRef.value, {
    colors: ['#ff0080', '#0080ff', '#ff0080', '#0080ff'],
    seed: 42
  })
})
</script>

Available Methods

When you have access to the instance.value, you can call these methods:

Core Methods

Prop

Type

Properties

<script setup lang="ts">
import { useMeshGradient } from '@mesh-gradient/vue'

const { instance } = useMeshGradient()

// Check if gradient is initialized
if (instance.value?.isInitialized) {
  // Safe to call methods
}
</script>

Advanced Example

<template>
  <div>
    <canvas 
      ref="canvasRef" 
      class="w-full h-64 rounded-lg"
    />
    
    <div class="mt-4 space-x-2">
      <button @click="toggleAnimation">
        {{ isPaused ? 'Play' : 'Pause' }}
      </button>
      <button @click="updateColors">
        Random Colors
      </button>
      <button @click="resetGradient">
        Reset
      </button>
    </div>
  </div>
</template>

<script setup lang="ts">
import { useMeshGradient } from '@mesh-gradient/vue'
import { ref, onMounted, watch } from 'vue'

const { instance } = useMeshGradient()
const canvasRef = ref<HTMLCanvasElement>()
const isPaused = ref(false)

// Initialize gradient on mount
onMounted(() => {
  if (!instance.value || !canvasRef.value) return
  
  instance.value.init(canvasRef.value, {
    colors: ['#ff0080', '#0080ff', '#80ff00', '#ff8000'],
    animationSpeed: 1.2,
    seed: 1
  })
})

// Watch for pause state changes
watch(isPaused, (paused) => {
  if (!instance.value?.isInitialized) return
  
  if (paused) {
    instance.value.pause()
  } else {
    instance.value.play()
  }
})

const toggleAnimation = () => {
  isPaused.value = !isPaused.value
}

const updateColors = () => {
  if (!instance.value?.isInitialized) return
  
  const randomColors = [
    '#' + Math.floor(Math.random()*16777215).toString(16),
    '#' + Math.floor(Math.random()*16777215).toString(16),
    '#' + Math.floor(Math.random()*16777215).toString(16),
    '#' + Math.floor(Math.random()*16777215).toString(16)
  ]
  
  instance.value.update({
    colors: randomColors,
    transition: true,
    transitionDuration: 500
  })
}

const resetGradient = () => {
  if (!instance.value?.isInitialized) return
  
  instance.value.update({
    colors: ['#ff0080', '#0080ff', '#80ff00', '#ff8000'],
    seed: 1,
    transition: true
  })
}
</script>

Reactive Integration

You can integrate the composable with Vue's reactivity system:

<template>
  <div>
    <canvas ref="canvasRef" class="w-full h-64" />
    
    <div class="mt-4 space-y-2">
      <div>
        <label>Animation Speed: {{ animationSpeed.toFixed(1) }}</label>
        <input 
          v-model.number="animationSpeed" 
          type="range" 
          min="0.1" 
          max="3" 
          step="0.1"
        />
      </div>
      
      <div>
        <label>
          <input v-model="isStatic" type="checkbox" />
          Static Mode
        </label>
      </div>
    </div>
  </div>
</template>

<script setup lang="ts">
import { useMeshGradient } from '@mesh-gradient/vue'
import { ref, onMounted, watch } from 'vue'

const { instance } = useMeshGradient()
const canvasRef = ref<HTMLCanvasElement>()
const animationSpeed = ref(1.0)
const isStatic = ref(false)

onMounted(() => {
  if (!instance.value || !canvasRef.value) return
  
  instance.value.init(canvasRef.value)
})

// Watch for changes and update gradient
watch([animationSpeed, isStatic], () => {
  if (!instance.value?.isInitialized) return
  
  instance.value.update({
    animationSpeed: animationSpeed.value,
    isStatic: isStatic.value
  })
})
</script>

Performance Considerations

  • The composable creates a new instance on every component mount
  • For frequently mounting/unmounting components, consider using a shared instance
  • The instance is automatically destroyed on unmount, preventing memory leaks
  • Use instance.value?.isInitialized to check if it's safe to call methods

When NOT to Use

Don't use useMeshGradient if you:

  • Only need basic gradient display (use <MeshGradient /> component instead)
  • Don't need direct control over the gradient instance
  • Want automatic canvas management and lifecycle handling

Comparison with Component

Prop

Type

TypeScript Support

The composable is fully typed and provides proper TypeScript support:

<script setup lang="ts">
import { useMeshGradient } from '@mesh-gradient/vue'
import type { MeshGradient } from '@mesh-gradient/core'

const { instance } = useMeshGradient()

// instance is properly typed as Ref<MeshGradient | null>
if (instance.value) {
  // TypeScript knows instance.value is MeshGradient here
  instance.value.init(/* ... */)
}
</script>

<MeshGradient /> (Vue)

Reference for the Vue <MeshGradient /> component props, events, and usage patterns.

On this page

useMeshGradient()Basic UsageReturn ValueWhen to UseLifecycle ManagementAvailable MethodsCore MethodsPropertiesAdvanced ExampleReactive IntegrationPerformance ConsiderationsWhen NOT to UseComparison with ComponentTypeScript Support