API V1.1.1

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'
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 v1.1.0	300	Int	What is the scroll debounce threshold (in ms)? Only useful if isPausedWhenNotInView is set to true.
opacity (required)	/	Array of Int	You can adapt the opacity of each color of the gradient. if you have two colors [1, .5], or three [1, .5, 1]...
stateTransitionSpeed	1000	Int	Duration of the animation when changing state.
defaultStateName	'default-state'	String	The name of the default state.
states (required)	/	Object	Object containing all the states, see more info below.
image v1.1.0	/	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
gradients (required)	/	Array of Arrays	The different gradients with the different colors e.g. [ ['#FFF', '#000'], ['#000', '#FFF'] ]. The array can contain only one gradient.
transitionSpeed	5000	Int	Transition duration between each gradient.
loop	true	Boolean	When the animation has arrived to the last gradient, does it repeat?

options.image v1.1.0

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: '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,
    opacity: [1, 1],
    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. you will also have to adapt the opacity.

var granimInstance = new Granim({
    element: '',
    name: 'granim',
    elToSetClassOn: 'body',
    direction: 'diagonal',
    isPausedWhenNotInView: false,
    scrollDebounceThreshold: 300,
    opacity: [1, 1, .5, 1],
    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
        }
    }
);