API

options

All the global options available.

PropertyDefaultTypeDescription
element (required)/String or HTMLCanvasElementA 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.
namefalseStringThis 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'StringThe element to set the dark / light class on (e.g. '#canvas-wrapper')
Only useful if you set a name.
direction'diagonal'StringThe orientation of the gradient, you can choose between:
  • 'diagonal'
  • 'left-right'
  • 'top-bottom'
  • 'radial'
isPausedWhenNotInViewfalseBooleanDoes the animation stop when it's not in window view?
(Despite this parameter, the animation always pause when changing tab).
scrollDebounceThreshold v1.1.0300IntWhat is the scroll debounce threshold (in ms)?
Only useful if isPausedWhenNotInView is set to true.
opacity (required)/Array of IntYou can adapt the opacity of each color of the gradient.
if you have two colors [1, .5], or three [1, .5, 1]...
stateTransitionSpeed1000IntDuration of the animation when changing state.
defaultStateName'default-state'StringThe name of the default state.
states (required)/ObjectObject containing all the states, see more info below.
image v1.1.0/ObjectObject 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.

PropertyDefaultTypeDescription
gradients (required)/Array of ArraysThe different gradients with the different colors e.g. [ ['#FFF', '#000'], ['#000', '#FFF'] ].
The array can contain only one gradient.
transitionSpeed5000IntTransition duration between each gradient.
looptrueBooleanWhen 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.

PropertyDefaultTypeDescription
source (required)/StringThe source of your image, e.g. 'img/800x200.jpg'.
position['center', 'center']ArrayThe 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/ArrayDoes 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/StringHow the image should blend with the gradient ? You can see all the possible values on MDN.

Callbacks

You can set callbacks.

PropertyDefaultTypeDescription
onStartfalseFunctionTriggered when the animation start.
onGradientChangefalseFunctionTriggered when a gradient change and loop.
onEndfalseFunctionTriggered 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
        }
    }
);