# Stagger

References:

Contents:

# Basic Usage:

stagger is a function not cunstructor! that wraps ANY module to create staggered animations. You can treat stagger function as a prism is mounted on top of modules and splits input properties evenly between them:

// wrap shape in stagger
const Shapes = mojs.stagger( mojs.Shape );
// now you can have staggered syntax on the shape and create multiple shapes at once. the next code will produce 5 shapes
const shapes = new Shapes({
  // quantifier defines number of modules to create
  quantifier:   5,
  // each module will have the same scale transition
  scale:        { 1: 0 }
});

CodePen Example (opens new window)

You can use array to specify property value for each shape:

// wrap shape in stagger
const StaggeredShape = mojs.stagger( mojs.Shape );
// now you can have staggered syntax on the shape and create multiple shapes at once. the next code will produce 5 shapes
const shapes = new StaggeredShape({
  // quantifier defines number of modules to create
  quantifier:   5,
  // each module will receive value from this array. if array is smaller than amount of modules (4 vs 5), the stagger prism will loop on the array, thus `5th` item will receive value by `index = 0`, `6th` item will receive value by `index = 1` and so on. This is called `property map` because it maps properties array to modules inside stagger.
  scale: [{ 0: 1 }, {0: 1.25}, { 0: 1.5 }, { 0: 2 }],
});

CodePen Example (opens new window)

You can use stagger string incremental properties:

// wrap shape in stagger
const StaggeredShape = mojs.stagger( mojs.Shape );
// now you can have staggered syntax on the shape and create multiple shapes at once. the next code will produce 5 shapes
const shapes = new StaggeredShape({
  // quantifier defines number of modules to create
  quantifier:   5,
  // the value of the property will be increased for each module with specified `step`(.25), starting from the `initial value`(1). Step could be `positive` or `negative`.
  scale: 'stagger(1, .25)'
});

CodePen Example (opens new window)

The initial value could be omitted - it will fallback to 0:

// wrap shape in stagger
const Shapes = mojs.stagger( mojs.Shape );
// now you can have staggered syntax on the shape and create multiple shapes at once. the next code will produce 5 shapes
const shapes = new Shapes({
  // quantifier defines number of modules to create
  quantifier:   5,
  // this means stagger with step of `50` starting from `0`
  x:            'stagger(50)'
});

CodePen Example (opens new window)

stagger strings can be used inside deltas and can contain rand expressions:

// wrap shape in stagger
const StaggeredShape = mojs.stagger( mojs.Shape );
// now you can have staggered syntax on the shape and create multiple shapes at once. the next code will produce 5 shapes
const shapes = new StaggeredShape({
  // quantifier defines number of modules to create
  quantifier:   5,
  // animate scale from `0` to staggered value (`1` for 1st module, `1.25` for 2nd, `1.5` for 3rd etc.)
  scale: { 0: 'stagger(1, .25)' },
  // random value in range from `0` to staggered value (`200` for 1st module, `400` for 2nd, `600` for 3rd etc.)
  x: 'stagger(-300, rand(100, 200))'
});

CodePen Example (opens new window)

# Full API Reference

const shape = new mojs.Shape({
  // how many modules to create. {Number, String} [amount of modules, property name]
  // if `string` is set instead of `number` it is treated as `property name` pointer - the number of modules will be inferred on value of that property, for instance if `quantifier` is set to `el` and `el` property has `array like` as it's value - quantifier will be set to length of that array.
  quantifier: 'el',
  // options for timeline that controls all modules
  timeline: {},
  /*
    Module's properties and callbacks, depends on what module has been wrapped into stagger, please see wrapped module API reference.
  */
})
/*
  Creates next state transition chain.
  @param options {Object} Next shape state.
*/
.then({ /* next state options */ })

/*
  Tunes start state with new options.
  @param options {Object} New start properties.
*/
.tune({ /* new start properties */ })

/*
  Regenerates all randoms in initial properties.
*/
.generate()
/*
  Starts playback.
  @param shift {Number} Start progress shift in milliseconds.
*/
.play( shift = 0 )
/*
  Starts playback in backward direction.
  @param shift {Number} Start progress shift in milliseconds.
*/
.playBackward( shift = 0 )
/*
  Pauses playback.
*/
.pause()
/*
  Restarts playback.
  @param shift {Number} Start progress shift in milliseconds.
*/
.replay( shift = 0 )
/*
  Restarts playback in backward direction.
  @param shift {Number} Start progress shift in milliseconds.
*/
.replayBackward( shift = 0 )
/*
  Resumes playback in direction it was prior to `pause`.
  @param shift {Number} Start progress shift in milliseconds.
*/
.resume( shift = 0 )
/*
  Sets progress of the tween.
  @param progress {Number} Progress to set [ 0..1 ].
*/
.setProgress( progress )
/*
  Sets speed of the tween.
  @param speed {Number} Progress to set [ 0..∞ ].
*/
setSpeed ( speed )
/* Stops and resets the tween. */
reset ( speed );