Pieces

Javascript library to draw and animate images, texts or SVG paths as multiple rectangular pieces.

DEMO

TUTORIAL

Visit lmgonzalves.com to see it in action!

Basic usage

The Pieces library depends on anime.js to perform animations, so you need to include it before Pieces. Then you only need a canvas element in HTML to start animating things with a piece of code like this:

<!-- Canvas to draw the pieces -->
<canvas class="my-canvas"></canvas>

<script src="anime.min.js"></script>
<script src="dist/pieces.min.js"></script>
<script>
    // Options for customization, see full list below
    var options = {
        canvas: '.my-canvas',
        text: 'Some Text'
    };

    // Initialize a new instance, by default the pieces will be 'hidden'
    var myPieces = new Pieces(options);

    // Show pieces using default options. See the full list of available operations below.
    myPieces.showPieces();
</script>

Operations

These are all the possible operations that can be performed with a Pieces instance. To specify the item you want to animate, you can use the corresponding index or an Array of indexes, like:

var options1 = {items: 0};      // Animate the first item
var options2 = {items: [0, 2]}; // Animate the first and the third items

Operations to animate item values

• animateItems(options): Animate the items properties passed in options. So far, you will only need this to animate the angle property for items.

To animate pieces values

• animatePieces(options): Animate the pieces properties passed in options.
• showPieces(options): Show pieces (animate to the "show" values).
• hidePieces(options): Hide pieces (animate to the "hide" values).

Options

For customization, you can pass options (in object notation) to Pieces constructor. These options overrides default values, and will be used for any future operation. You can also override the options for an specific operation. Here is the complete list, for reference.

Options for Pieces constructor

The following options can be passed as an Array too, each value for the corresponding item. In case there are more items than Array elements, the last value will be used.

Options to use in operations for updating pieces

After the pieces are built (new Pieces instance created), they can be animated through operations, and you can use all of these possible properties to do it. Just provide the properties that you want to update inside the options argument.

As the animations are handled by anime.js, each property could be a function instead a static value (read more here). And every piece object also has s_property (property value when the piece is shown) and h_property (property value when the piece is hidden) values, so you could do something like this (ES6 code):

// Animate everything to the "show" (`s_property`) values
const options = {
    x: p => p.s_x,
    y: p => p.s_y,
    w: p => p.s_w,
    h: p => p.s_h,
    tx: p => p.s_tx,
    ty: p => p.s_ty
};
myPiecesInstance.animatePieces(options);

// It's the same to call `myPiecesInstance.showPieces()` instead, just posting that here as an example

Useful functions

The Pieces library also offers some useful functions that you can use:

• Pieces.random(min, max): Return a random number between min and max values.
• Pieces.extend(target, source): Extend a target object with properties from one or multiple source objects.