useMeshGradient()

The useMeshGradient hook 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

import { useMeshGradient } from '@mesh-gradient/react'
 
function MyComponent() {
  const { instance } = useMeshGradient()
  
  // instance is available after component mounts
  // You can call methods on it when needed
  
  return <div>My Component</div>
}

Return Value

The hook returns an object with the following property:

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 hook automatically:

• Creates a new MeshGradient instance on mount
• Destroys the instance when the component unmounts
• Provides the instance through the instance property

import { useMeshGradient } from '@mesh-gradient/react'
import { useEffect } from 'react'
 
function AdvancedGradient() {
  const { instance } = useMeshGradient()
 
  const canvasRef = useRef<HTMLCanvasElement>(null)
  
  useEffect(() => {
    if (!instance || !canvasRef.current) return
    
    // Custom initialization logic
    instance.init(canvasRef.current, {
      colors: ['#ff0080', '#0080ff', '#ff0080', '#0080ff'],
      seed: 42
    })
 
  }, [instance, canvasRef])
  
  return <canvas ref={canvasRef} />
}

Available Methods

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

Core Methods

// Initialize the gradient
instance.init(canvas, options)
 
// Update gradient options
instance.update(options)
 
// Play animation
instance.play()
 
// Pause animation
instance.pause()
 
// Destroy the gradient
instance.destroy()

Properties

// Check if gradient is initialized
if (instance.isInitialized) {
  // Safe to call methods
}

Performance Considerations

• The hook 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.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

TypeScript Support

The hook is fully typed and provides proper TypeScript support:

import { useMeshGradient } from '@mesh-gradient/react'
import type { MeshGradient } from '@mesh-gradient/core'
 
function TypedGradient() {
  const { instance } = useMeshGradient()
  
  // instance is properly typed as MeshGradient | null
  if (instance) {
    // TypeScript knows instance is MeshGradient here
    instance.init(/* ... */)
  }
}