Canvas Based Interactive Gradients Animation Library – Granim.js

Category: Animation , Color , Javascript , Recommended | November 12, 2018
Author: sarcadass
Views Total: 565 views
Official Page: Go to website
Last Update: November 12, 2018
License: MIT


Canvas Based Interactive Gradients Animation Library – Granim.js


Granim.js is a lightweight, dependency-free JavaScript library which helps create configurable, interactive gradients animations on an HTML5 canvas element.

How to use it:

Create an HTML5 canvas element where you want to create the gradients animation.

<canvas id="canvas-demo"></canvas>

Insert the minified version of Granim.js script into your html page.

<script src="dist/granim.min.js"></script>

The JavaScript to create a basic gradients animation on the canvas element.

var granimInstance = new Granim({
    element: '#canvas-demo',
    states : {
      "default-state": {
          gradients: [
              ['#485563', '#29323c', '#29323c'],
              ['#00c6ff', '#0072ff', '#0072ff']
          transitionSpeed: 10000

All default configuration options.

var granimInstance = new Granim({

    // CSS selector of canvas element
    element: '',

    // whether to add a dark / light class on the body depending on the gradient lightness, the class will be updated during the animation. 
    // If you don't set a name, the class won't be set.
    name: false,

    // The element to set the dark / light class on
    elToSetClassOn: 'body',

    // 'diagonal', 'left-right', 'radial', 'top-bottom', or 'custom'
    direction: 'diagonal',

    // custom direction
    customDirection: {
      x0: '10%',
      y0: '25px',
      x1: '30%',
      y1: '322px'

    //  scroll debounce threshold (in ms)?
    scrollDebounceThreshold: 300

    // pause animation when out of view
    isPausedWhenNotInView: false,

    // opacity of each color of the gradient
    opacity: '',

    // Object containing all the states
    // gradients (required): The different gradients with the different colors e.g. [ ['#FFF', '#000'], ['#000', '#FFF'] ].
    // transitionSpeed: 500: Transition duration between each gradient.
    // loop: true: Boolean When the animation has arrived to the last gradient, does it repeat?
    states : {
      "default-state": {
          gradients: [
              ['#834d9b', '#d04ed6'],
              ['#1CD8D2', '#93EDC7']
          transitionSpeed: 5000,
          loop: true
      "dark-state": {
          gradients: [
              ['#757F9A', '#D7DDE8'],
              ['#5C258D', '#4389A2']
          transitionSpeed: 5000,
          loop: true

    // name of the default state
    defaultStateName: 'default-state'

    // transition speed
    stateTransitionSpeed: 1000,

    // source (required): The source of your image, e.g. 'img/800x200.jpg'.
    // position: ['center', 'center']: The position of your image in the canvas, represented as an [x, y] array.
    // stretchMode: Does the image have to stretch ? This option is useful for liquid/responsive design. Represented as an [x, y] array.
    // Possible values for x and y:
    // 'stretch'
    // 'stretch-if-smaller'
    // 'stretch-if-bigger'
    // blendingMode: How the image should blend with the gradient ?
    image: {
      source: '../assets/img/bg-forest.jpg',
      position: ['center', 'bottom'],
      stretchMode: ['stretch', 'stretch-if-bigger'],
      blendingMode: 'multiply',

    // callback functions
    onStart: function(){},
    onGradientChange: function(colorDetails){},
    onEnd: function(){},


API methods:

// Change state by putting its name in the argument

// Play the animation;

// Pause the animation

// Stop the animation and clear the gradient

// Change the direction

// Change the blending mode (useful only if you use an image)

// Destroy an instance and remove its events listeners

Callback functions.

var granimInstance = new Granim({

    // Triggered when the animation start.
    onStart: false, 

    // Triggered when a gradient change and loop.
    onGradientChange: false,

    // Triggered when the animation end.
    onEnd: false


Events available

  • granim:start
  • granim:end
  • granim:loop
  • granim:gradientChange
var canvasElement = document.querySelector('#canvas-demo');
canvasElement.addEventListener('granim:start', function(event) {


v2.0.0 (11/12/2018)

  • Add custom direction
  • Add support for other color types: rgb, rgba, hsl, hsla
  • Add custom color positions
  • Code improvement

v1.1.1 (09/12/2018)

  • Bugfixes
  • New features
  • Improvement

You Might Be Interested In:

One thought on “Canvas Based Interactive Gradients Animation Library – Granim.js

Leave a Reply