Neat gradients

Create awesome 3D gradients with this WebGL-based library.

⚠️ Breaking change (v0.7): Neat no longer depends on three.js. The rendering engine has been rewritten to use raw WebGL. You can safely npm uninstall three @types/three. The mouse interaction properties (mouseDistortionStrength, mouseDistortionRadius, mouseDecayRate, mouseDarken) have also been removed. All other config properties remain unchanged.

Check the demo and gradients editor to find your perfect config here: https://neat.firecms.co/

Neat is released under the CC license, so you can use it for free in your projects, commercial or not. You can also modify it and redistribute it, but you must keep the license and the credits.

Installation

yarn add @firecms/neat

or

npm install @firecms/neat

Usage

You can use the library to create a gradient in your website or application. You need to define a config and then create a new NeatGradient instance. You are encouraged to use the gradients editor to find your perfect config.

Simple example

import { NeatConfig, NeatGradient } from "@firecms/neat";

// Define your config
export const config: NeatConfig = {
    colors: [
        {
            color: "#FF5373",
            enabled: true
        },
        {
            color: "#FFC858",
            enabled: true
        },
        {
            color: "#17E7FF",
            enabled: true
        },
        {
            color: "#6D3BFF",
            enabled: true
        },
        {
            color: "#f5e1e5",
            enabled: false
        }
    ],
    speed: 4,
    horizontalPressure: 4,
    verticalPressure: 5,
    waveFrequencyX: 2,
    waveFrequencyY: 3,
    waveAmplitude: 5,
    shadows: 0,
    highlights: 2,
    colorSaturation: 7,
    colorBrightness: 1,
    wireframe: false,
    colorBlending: 6,
    backgroundColor: "#003FFF",
    backgroundAlpha: 1
};


// define an element with id="gradient" in your html
const neat = new NeatGradient({
    ref: document.getElementById("gradient"),
    ...config
});

// you can change the config at any time
neat.speed = 6;

// you can also destroy the gradient for cleanup
// e.g. returning from a useEffect hook in React
neat.destroy();

React example

import React, { useEffect, useRef } from "react";
import { NeatGradient } from "@firecms/neat";

export const MyComponent: React.FC = () => {
    const canvasRef = useRef<HTMLCanvasElement | null>(null);

    useEffect(() => {
        if (!canvasRef.current) return;

        const gradient = new NeatGradient({
            ref: canvasRef.current,
            colors: [
                { color: "#FF5373", enabled: true },
                { color: "#FFC858", enabled: true },
                { color: "#05d5ef", enabled: true },
                { color: "#6D3BFF", enabled: true },
                { color: "#f5e1e5", enabled: false }
            ],
            speed: 4,
            horizontalPressure: 4,
            verticalPressure: 5,
            waveFrequencyX: 2,
            waveFrequencyY: 3,
            waveAmplitude: 5,
            shadows: 0,
            highlights: 1,
            colorSaturation: 0,
            colorBrightness: 1,
            wireframe: false,
            colorBlending: 6,
            backgroundColor: "#003FFF",
            backgroundAlpha: 1,
            resolution: 0.5
        });

        return gradient.destroy;
    }, []);

    return (
        <canvas
            style={{
                isolation: "isolate",
                height: "100%",
                width: "100%",
            }}
            ref={canvasRef}
        />
    );
};

Configuration Parameters

Required Parameters

ref

• Type: HTMLCanvasElement
• Description: The canvas element where the gradient will be rendered
• Required: Yes

colors

• Type: NeatColor[]
• Description: Array of color objects that define the gradient palette
• Required: Yes
• Color Object Properties:
  • color (string): Hex color value (e.g., "#FF5373")
  • enabled (boolean): Whether the color is active in the gradient
  • influence (number, optional): Value from 0 to 1 controlling color strength

Animation Parameters

speed

• Type: number
• Range: 0 to 10
• Default: 4
• Description: Animation speed. Set to 0 to pause all animations (waves and flow).

Color Pressure Parameters

Note: These are disabled when enableProceduralTexture is true

horizontalPressure

• Type: number
• Range: 0 to 10
• Default: 3
• Description: Horizontal color distribution intensity

verticalPressure

• Type: number
• Range: 0 to 10
• Default: 3
• Description: Vertical color distribution intensity

colorBlending

• Type: number
• Range: 0 to 10
• Default: 5
• Description: How smoothly colors blend together

Wave Parameters

Note: Requires speed > 0 to be visible

waveFrequencyX

• Type: number
• Range: 0 to 10
• Default: 5
• Description: Horizontal wave frequency

waveFrequencyY

• Type: number
• Range: 0 to 10
• Default: 5
• Description: Vertical wave frequency

waveAmplitude

• Type: number
• Range: 0 to 10
• Default: 3
• Description: Wave height/intensity

Visual Effects Parameters

shadows

• Type: number
• Range: 0 to 10
• Default: 4
• Description: Intensity of shadow effects

highlights

• Type: number
• Range: 0 to 10
• Default: 4
• Description: Intensity of highlight effects

colorSaturation

• Type: number
• Range: -10 to 10
• Default: 0
• Description: Color saturation adjustment (negative values desaturate)

colorBrightness

• Type: number
• Range: 0 to 10
• Default: 1
• Description: Overall brightness multiplier

Grain Parameters

grainIntensity

• Type: number
• Range: 0 to 1
• Default: 0.55
• Description: Strength of film grain effect. Set to 0 to disable grain.

grainScale

• Type: number
• Range: 0 to 100
• Default: 2
• Description: Size of grain particles

grainSparsity

• Type: number
• Range: 0 to 1
• Default: 0.0
• Description: How sparse/scattered the grain appears

grainSpeed

• Type: number
• Range: 0 to 10
• Default: 0.1
• Description: Animation speed of grain particles

Shape Parameters

resolution

• Type: number
• Range: 0.05 to 2
• Default: 1
• Description: Mesh density/quality. Lower values improve performance but reduce visual quality.

wireframe

• Type: boolean
• Default: false
• Description: Show the 3D mesh structure. When enabled, colors, grain, and texture effects are less visible.

yOffset

• Type: number
• Range: 0 to 100000
• Default: 0
• Description: Vertical offset for scroll-based effects

yOffsetWaveMultiplier

• Type: number
• Range: 0 to 20
• Default: 4
• Description: How much vertical offset affects wave animation

yOffsetColorMultiplier

• Type: number
• Range: 0 to 20
• Default: 4
• Description: How much vertical offset affects color distribution

yOffsetFlowMultiplier

• Type: number
• Range: 0 to 20
• Default: 4
• Description: How much vertical offset affects flow field

Background Parameters

backgroundColor

• Type: string
• Default: "#FFFFFF"
• Description: Hex color for the background

backgroundAlpha

• Type: number
• Range: 0 to 1
• Default: 1.0
• Description: Background opacity (0 = transparent, 1 = opaque)

Flow Field Parameters

Note: Requires speed > 0 and flowEnabled: true

flowEnabled

• Type: boolean
• Default: true
• Description: Enable/disable flow field distortion

flowDistortionA

• Type: number
• Range: 0 to 5
• Default: 0
• Description: Wave amplitude for flow distortion

flowDistortionB

• Type: number
• Range: 0 to 10
• Default: 0
• Description: Wave frequency for flow distortion

flowScale

• Type: number
• Range: 0 to 5
• Default: 1.0
• Description: Scale of the flow field waves

flowEase

• Type: number
• Range: 0 to 1
• Default: 0.0
• Description: Blend between original and flow-distorted state

Procedural Texture Parameters

Note: When enabled, replaces color pressure controls

enableProceduralTexture

• Type: boolean
• Default: false
• Description: Enable procedurally generated texture overlay

textureVoidLikelihood

• Type: number
• Range: 0 to 1
• Default: 0.45
• Description: Frequency of gaps/voids in texture bands

textureVoidWidthMin

• Type: number
• Range: 10 to 200
• Default: 200
• Description: Minimum width of texture gaps in pixels

textureVoidWidthMax

• Type: number
• Range: 50 to 600
• Default: 486
• Description: Maximum width of texture gaps in pixels

textureBandDensity

• Type: number
• Range: 0.1 to 3
• Default: 2.15
• Description: Density of texture bands

textureColorBlending

• Type: number
• Range: 0 to 1
• Default: 0.01
• Description: Color blending within texture

textureSeed

• Type: number
• Range: 0 to 1000
• Default: 333
• Description: Random seed for texture generation (change for different patterns)

textureEase

• Type: number
• Range: 0 to 1
• Default: 0.5
• Description: Blend between flow field and procedural texture (0 = flow, 1 = texture)

proceduralBackgroundColor

• Type: string
• Default: "#000000"
• Description: Hex color for texture void/gap areas

textureShapeTriangles

• Type: number
• Range: 0 to 100
• Default: 20
• Description: Number of triangle shapes in texture

textureShapeCircles

• Type: number
• Range: 0 to 100
• Default: 15
• Description: Number of circle shapes in texture

textureShapeBars

• Type: number
• Range: 0 to 100
• Default: 15
• Description: Number of bar shapes in texture

textureShapeSquiggles

• Type: number
• Range: 0 to 100
• Default: 10
• Description: Number of squiggle/wavy shapes in texture

Tips

• Use the online editor to visually design your gradient and export the configuration
• Start with lower resolution values (0.5-1.0) for better performance, especially on mobile devices
• Set speed: 0 to create static gradients without animation
• Combine yOffset with scroll position for scroll-based gradient effects
• Enable wireframe: true during development to understand the 3D mesh structure
• Procedural textures work best with textureEase values between 0.3 and 0.7

NEAT Link

If you want to remove the NEAT link, you can reach us at [email protected]