API

What methods and properties are available in Mesh Gradient and how to use them.

MeshGradient

The main instance API.


import { MeshGradient } from '@mesh-gradient/core';
 
const gradient = new MeshGradient();

Name	Type	Default
`init`	`(selector: string \| HTMLCanvasElement, options?: (MeshGradientOptions & MeshGradientInitOptions) \| undefined) => MeshGradient` Initialize the gradient
`update`	`(config?: (MeshGradientOptions & MeshGradientUpdateOptions) \| undefined) => void` Updates the gradient with new configuration. Supports fade transition if enabled.
`destroy`	`() => void` Completely destroys the gradient and cleans up all resources. This method should be called when the gradient is no longer needed
`play`	`() => void` Manually start gradient animation
`pause`	`() => void` Manually pause gradient animation
`toggleAutoPause`	`(enabled: boolean) => void` Enable or disable auto-pause when gradient goes out of viewport
`isInitialized`	`boolean` Whether the gradient is been initialized by calling `init` method.	`false`

MeshGradientOptions

Options for .init() and .update() methods.


import { MeshGradientOptions } from '@mesh-gradient/core';
 
const options: MeshGradientOptions = {
  colors: ['#000000', '#ffffff', '#000000', '#ffffff'],
};

Name	Type	Default
`seed`	`number` Seed for the gradient. It needs to generate the same gradient pattern on every page load.	`random value`
`animationSpeed`	`number` Animation speed multiplier. Higher values make animation faster, lower values make it slower. Performance remains constant regardless of speed value.	`1.0`
`frequency`	`number \| MeshGradientFrequencyConfig` Frequency for the gradient. Can be a single number or an object with x, y, and delta properties.	`{ x: 0.00014, y: 0.00029, delta: 0.0001 }`
`activeColors`	`MeshGradientToggleColorsConfig` Active colors for the gradient.	`{ 1: true, 2: true, 3: true, 4: true }`
`isStatic`	`boolean` Static mode. If true, the gradient will not animate. Optimized for performance.	`false`
`pauseOnOutsideViewport`	`boolean` Auto pause when gradient goes out of viewport. Powered by `Intersection Observer` API.	`true`
`pauseObserverOptions`	`IntersectionObserverInit` Intersection observer options for pause on outside viewport option.	`{ root: document.body, rootMargin: '0px', threshold: 0.05 }`
`resizeDelay`	`number` Resize delay after canvas is resized. Helps to optimize performance.	`300 ms`
`colors`	`MeshGradientColorsConfig` Colors in hex format. Should be an array of 4 colors in hex format.
`cssVariablesFallback`	`boolean` Fallback to CSS variables instead of random colors if colors are not provided.	`false`

Init Options

Type MeshGradientInitOptions contains additional options for .init() method. Not used in .update() method.

Name	Type	Default
`appearance`	`"smooth" \| "default"` Appearance mode. `smooth` enables smooth appearance transition when gradient is initialized.	`'smooth'`
`appearanceDuration`	`number` Duration of appearance transition in milliseconds.	`300`

Update Options

Type MeshGradientUpdateOptions contains additional options for .update() method.

Name	Type	Default
`transition`	`boolean` Enable fade transition when updating gradient.	`true`
`transitionDuration`	`number` Duration of fade transition in milliseconds.	`300`