# 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
--- | --- | --- | ---

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
            }
        }
    );