Getting started with Cardistry

Cardistry is an expressive and versatile card animation engine, for animating cards or card-like visuals in your website.

It provides an easy and intuitive API for developers to animate a group of cards, and allows them to specify a sequence of animations to play for a group of cards.

Some examples made possible with this library are moving, spreading, fanning, flipping, distributing, shuffling, and twisting a deck of cards.

Installation

There are several ways to install this library into your project.

Using NPM:

Using Yarn:

Using a CDN (Add this to the head of your HTML document)

 <script defer src="unpkg.com/cardistry@1.0.1"></script> 

Download Source files

Your can download the source files from the Github Repository

Basic Usage

Setup a simple hello world example to get you up and running.

Import the library as an ES6 module.

import Cardistry from 'cardistry';

Setup your HTML with cards to be animated.

<section class="example-cards">
  <div class="card"> <div class="content"> </div> </div>
  <div class="card"> <div class="content"> </div> </div>
  <div class="card"> <div class="content"> </div> </div>
  <div class="card"> <div class="content"> </div> </div>
</section>

Use the Cardistry state machine to animate the group of cards.

new Cardistry({
  target: ".example-cards",
  loop: true,
  states: [
    { moveX: 250, moveY: -100 }, 
    { moveY: 100 }, 
    { moveX: -250, moveY: -100 }, 
    { moveY: 100 } 
  ]
});

Core Concepts

Setting up the Cards

To be able to use Cardistry correctly, the card's HTML have to be in a certain structure. Here is an example of a single card element:

<div class="card"> 
  <div class="content"> 
    <div class="front"> ... </div> 
    <div class="back"> ... </div> 
  </div> 
</div>

Each card must be assigned a class "card" and have a direct child with class "content", the "front" and "back" is only needed if you intend to flip the card at some point.

Hence, each card element will be direct child of a wrapping parent element, which will be referred to by the state machine.

The State Machine

The state machine class, called Cardistry, takes in a target, which is a query of an element in the DOM, specifically the parent of the list of cards you want to animate. It also takes in an array of states, which are the states the target cards will animate over. Each state has properties which position the cards, like translateX, translateY, rotateZ to name a few, and also animation properties like delay, duration and timing.

Here is an example of a simple call to the state machine, it animates the cards to move to the right, then move to the left, and it continues doing so because loop is set to true.

new Cardistry({
  target: ".example-cards",
  loop: true, // whether this state machine loops indefinately
  states: [
    {
      moveX: 250, // in px
      duration: 400,   // in milliseconds
    },
    {
      moveX: -250,
      duration: 400,
    },
  ]
});

Functional state properties

All state properties can be assigned a value, like 100, but some can also be assigned a function, with given parameters (i, n), where i is the current index of the card being animated, and n being the total number of cards to be animated. With this option to assign functions instead of plain values, staggering animations for individual cards becomes possible, and opens up a wide range of possibilities.

Here is an example of a call to the state machine, with some properties as functions for more complex behaviours. This one spreads the cards horizontally to the right, stacks then back together, then spreads them again but this time centered from the origin. Notice the use of the function stack() which is a preset state supplied by the library, all it does is resets all the properties which stacks the deck of cards. The difference between the first and the last state is due to the n parameter (number of cards), which allows us to calculate the negative offset required to center the spreaded out cards. The delay property as a function allows us to stagger the animation of each card, instead of having all of the cards animate in sync.

new Cardistry({
  target: ".cards",
  states: [
    {
      moveX: i => i * 25, // spread right
      delay: i => i * 100,
      duration: 400,
    },
    stack(),
    {
      moveX: (i, n) => (i + 0.5 - n / 2) * 25, // spread right but centered
      delay: i => i * 100,
      duration: 400,
    },
  ]
})

State Presets

To use presets like the one used above called stack(), we have to import them from the presets directory.

import { stack } from 'cardistry/presets';

Presets are essentially pre-built states that are used often. Using the ES6 spread operator, they can be mix and matched with custom states.

new Cardistry({
  target: ".example",
  states: [
    { ...stack(), delay: 500 },
    { ...spreadCenter(50), duration: 700 },
  ],
})

Depending on the preset, there are different arguments used to create them. Some preset states available are stack, spread, fan, and disperse. Refer to the API Summary for the full list.

The State Machine

State Machine Instance

When instantiating a Cardistry state machine using the new operator, the instance itself can be stored for later use.

const instance = new Cardistry({
  target: ".cards",
  states: [ ... ]
});

Playback Controls

With instance. Functions like play(), pause(), stop(), and speed allows us to control the animation like a video.

instance.pause(); // pauses the animation
instance.speed = 2; // sets the speed to 2x
instance.play(); // resumes animation
instance.speed = 0.01; // sets the speed to slo-mo
instance.stop(); // stops the animation

By default, the animation starts playing when the state machine is instantiated, unless autoplay is set to false.

The loop property can also be assigned a number to allow the animation to loop a certain amount of times.

const instance = new Cardistry({
  target: ".cards",
  loop: 3, // loops animation 3 times before stopping
  autoplay: false, // do not auto play animation, .play() has to be called manually.
  states: [ ... ]
});

Relative States

Another property of the state machine is relative, which defaults to false. This determines whether the next state inherits properties from the previous state, or that each state is independant of each other.

Here is an example with relative states. The result is the cards moving to the right, then down to the bottom right, since the previous state is inherited.

new Cardistry({
  target: ".cards",
  relative: true,
  states: [
    {
      moveX: 200, // moves X by 200
      duration: 500,
    },
    {
      moveY: 200, // moves Y by 200, on top of already moving X by 200
      duration: 500,
    },
  ]
})

Timing Function

A global timing function (to the state machine) can also be specified, which determines the interpolation behaviour between each state transition.

The property takes in a string for predefined timing functions, for eg linear, ease, and elastic. But a function can also be supplied for any custom timing behaviours.

new Cardistry({
  target: ".cards",
  timing: "linear", // predefined timing function, OR
  timing: t => Math.sqrt(1 - Math.pow(t - 1, 2)), // custom, where t is the normalized time that goes from 0 to 1
  states: [ ... ]
})

API Summary

Type Definitions

State Machine Options

For the arguments passed into the options object when contructing a new Cardistry instance.

State Options

Properties for each state, for the states array and initialState properties for the state machine.

Presets

Pre-built states to be used within the states array of the state machine.