API V2.0.0

options

All the global options available.

Property	Default	Type	Description
element (required)	/	String or HTMLCanvasElement	A CSS selector for the canvas element or the HTMLCanvasElement itself (e.g. '#granim-canvas' or document.querySelector('#granim-canvas')) that will be used for the gradient animation.
name	false	String	This is the prefix used for the dark / light class name added on the options.elToSetClassOn element depending on the average gradient lightness, the class will be updated during the animation. If you don't set a name, the class won't be set.
elToSetClassOn	'body'	String	The element to set the dark / light class on (e.g. '#canvas-wrapper') Only useful if you set a name.
direction	'diagonal'	String	The orientation of the gradient, you can choose between: 'diagonal' 'left-right' 'top-bottom' 'radial' 'custom'
customDirection	/	Object	Let you customize the direction of the gradient with pixels or percentage values with the following format: `{ x0: '10%', y0: '25px', x1: '30%', y1: '322px' }` This property is required when the propertydirection is set tocustom. For more details, checkout the documentation of the createLinearGradient function.
isPausedWhenNotInView	false	Boolean	Does the animation stop when it's not in window view? (Despite this parameter, the animation always pause when changing tab).
scrollDebounceThreshold	300	Int	What is the scroll debounce threshold (in ms)? Only useful if isPausedWhenNotInView is set to true.
stateTransitionSpeed	1000	Int	Duration of the animation when changing state (in ms).
defaultStateName	'default-state'	String	The name of the default state.
states (required)	/	Object	Object containing all the states, see more info below.
image	/	Object	Object containing image options, see more info below.

options.states

All the options available to customize the states and the different gradients.
Create a state with the name you want then add these parameters.
By default, the name of your first state is 'default-state', you can change it with options.defaultStateName.

Property Default Type Description

Property	Default	Type	Description
gradients (required)	/	Array of Arrays	You can set the gradients in two different ways: 1. The simple way, you only set the colors that will be evenly distributed, e.g. `[ ['rgba(255, 153, 102, .33)', '#ff5e62', ...], ['hsla(144, 100%, 47%, .75)', 'hsl(210, 96%, 46%)', ...], ... ]` 2. The complex way, you set the colors and their positions (ranging from 0 to 1), e.g. `[ [ { color: 'rgba(255, 153, 102, .33)', pos: .5 }, { color: '#ff5e62', pos: 1 }, ... ], [ { color: 'hsla(144, 100%, 47%, .75)', pos: .1 }, { color: 'hsl(210, 96%, 46%)', pos: .6 }, ... ], ... ]` The colors type accepted are: hexadecimal, rgb, rgba, hsl and hsla. All the gradients should contain the same number of colors.
transitionSpeed	5000	Int	Transition duration between each gradient (in ms).
loop	true	Boolean	When the animation has arrived to the last gradient, does it repeat?

gradients (required)

Array of Arrays

You can set the gradients in two different ways:
1. The simple way, you only set the colors that will be evenly distributed, e.g.

[
  ['rgba(255, 153, 102, .33)', '#ff5e62', ...],
  ['hsla(144, 100%, 47%, .75)', 'hsl(210, 96%, 46%)', ...],
  ...
]

2. The complex way, you set the colors and their positions (ranging from 0 to 1), e.g.

[
  [
    { color: 'rgba(255, 153, 102, .33)', pos: .5 },
    { color: '#ff5e62', pos: 1 }, ...
  ], [
    { color: 'hsla(144, 100%, 47%, .75)', pos: .1 },
    { color: 'hsl(210, 96%, 46%)', pos: .6 }, ...
  ],
  ...
]

The colors type accepted are: hexadecimal, rgb, rgba, hsl and hsla. All the gradients should contain the same number of colors.

transitionSpeed 5000 Int Transition duration between each gradient (in ms).

loop true Boolean When the animation has arrived to the last gradient, does it repeat?

options.image

All the options available to customize the image.
The blending Mode works only if you set an image and gradients.

Property	Default	Type	Description
source (required)	/	String	The source of your image, e.g. 'img/800x200.jpg'.
position	['center', 'center']	Array	The position of your image in the canvas, represented as an [x, y] array. Possible values for x: 'left' 'center' 'right' Possible values for y: 'top' 'center' 'bottom'
stretchMode	/	Array	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: 'none' 'stretch' 'stretch-if-smaller' 'stretch-if-bigger'
blendingMode	/	String	How the image should blend with the gradient ? You can see all the possible values on MDN.

Callbacks

You can set callbacks.

Property	Default	Type	Description
onStart	false	Function	Triggered when the animation start.
onGradientChange	false	Function	Triggered when a gradient change and loop.
onEnd	false	Function	Triggered when the animation end.

Emitted events

Granim will emit events you can listen to at key moments.

// You can listen to these events:
// - granim:start
// - granim:end
// - granim:loop
// - granim:gradientChange


// js
var canvasElement = document.querySelector('#granim-canvas');
canvasElement.addEventListener('granim:start', function(event) {
    console.log(event);
});


// with jQuery
$('#granim-canvas').on('granim:start', function(event) {
    console.log(event);
})

Methods

Methods to control the gradients.

// Play the animation
granimInstance.play();


// Pause the animation
granimInstance.pause();


// Stop the animation and clear the gradient
granimInstance.clear();


// Change state by putting its name in the argument
granimInstance.changeState('state-name');


// [v1.1.0] Change the direction
granimInstance.changeDirection('direction-name');


// [v1.1.0] Change the blending mode (useful only if you use an image)
granimInstance.changeBlendingMode('blending-mode-name');


// [v1.1.0] Destroy an instance and remove its events listeners
granimInstance.destroy();

Complete configuration

Complete configuration with two states, an image and callbacks set.

var granimInstance = new Granim({
    element: '',
    name: 'granim',
    elToSetClassOn: 'body',
    direction: 'diagonal',
    isPausedWhenNotInView: false,
    scrollDebounceThreshold: 300,
    stateTransitionSpeed: 1000,
    image : {
        source: '../assets/img/bg-forest.jpg',
        position: ['center', 'bottom'],
        stretchMode: ['stretch', 'stretch-if-bigger'],
        blendingMode: 'multiply',
    },
    states : {
        "default-state": {
            gradients: [
                ['#834d9b', '#d04ed6'],
                ['#1CD8D2', '#93EDC7']
            ],
            transitionSpeed: 5000,
            loop: true
        },
        "dark-state": {
            gradients: [
                ['#757F9A', '#D7DDE8'],
                ['#5C258D', '#4389A2']
            ],
            transitionSpeed: 5000,
            loop: true
        }
    },
    onStart: function() {
        console.log('Granim: onStart');
    },
    onGradientChange: function(colorDetails) {
        console.log('Granim: onGradientChange, details: ');
        console.log(colorDetails);
    },
    onEnd: function() {
        console.log('Granim: onEnd');
    }
);

You can use more than 2 colors for the gradients, but cannot have different length of colors in the different states.

var granimInstance = new Granim({
    element: '',
    name: 'granim',
    elToSetClassOn: 'body',
    direction: 'diagonal',
    isPausedWhenNotInView: false,
    scrollDebounceThreshold: 300,
    stateTransitionSpeed: 1000,
    states : {
        "default-state": {
            gradients: [
                ['#834d9b', '#d04ed6', '#1CD8D2', '#93EDC7'],
                ['#1CD8D2', '#93EDC7', '#757F9A', '#4389A2']
            ],
            transitionSpeed: 5000,
            loop: true
        },
        "dark-state": {
            gradients: [
                ['#757F9A', '#D7DDE8', '#1CD8D2', '#93EDC7'],
                ['#5C258D', '#4389A2', '#1CD8D2', '#93EDC7']
            ],
            transitionSpeed: 5000,
            loop: true
        }
    }
);