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

Name	Type	Default	Description
canvas	String or Element	null	A canvas element (or CSS selector) to draw the items.
items	Array or Object	[]	Item objects to draw and animate. Each item should be in the format: {type, value, options}, where type could be image, text or path.
image	Array or Image	[]	Image elements to draw and animate.
text	Array or String	[]	String elements (text) to draw and animate.
path	Array or String	[]	String values corresponding to d attributes of SVG path elements.
x	Integer or String	0	Start position for the x axis, or one of the possible String values: 'center' (center the items, positioned sequentially) or 'centerAll' (center all items individually).
y	Integer or String	0	Start position for the y axis, or one of the possible String values: 'center' (center the items, positioned sequentially) or 'centerAll' (center all items individually).
itemSeparation	Integer	1	Separation among items.
animation	Object	{duration: 1000, delay: 0, easing: 'easeInOutCubic'}	Default values to perform animations using anime.js. The duration and delay properties could be functions.
debug	Boolean	false	If true, enable a debug mode, where you can see how the pieces and items are being drawn in the canvas.

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.

Name	Type	Default	Description
piecesWidth	Integer or Function	5	Pieces width.
piecesSpacing	Integer or Function	5	Separation among pieces.
extraSpacing	Integer or Object	0	Extra space that should be covered by the pieces. You can set a different value for each axis using an Object like: {extraX: 0, extraY: 0}. This is useful if angle != 0.
angle	Integer	0	Rotation angle for pieces. All pieces in the same item will have the same rotation angle.
rotate	Integer	0	Rotation angle for items. This will rotate the entire item, including pieces.
translate	Integer or Object	0	Translation for items. You can set a different value for each axis using an Object like: {translateX: 0, translateY: 0}.
padding	String	0	Padding for items. It must be set like a CSS shortcut format: 'top right bottom left'.
opacity	Integer or Function	1	Opacity for items.
fontFamily	String	"sans-serif"	Font family for text items.
fontSize	Integer	100	Font size for text items.
fontWeight	Integer	900	Font weight for text items.
color	String	'#000'	Color to draw text and path items.
backgroundColor	String or Boolean	false	Background color for items, if it's not false.
backgroundRadius	Integer	0	Useful to draw rounded corners for the item background.

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.

Name	Type	Description
x	Integer	Pieces x position.
y	Integer	Pieces y position.
w	Integer	Pieces width.
h	Integer	Pieces height.
tx	Integer	Pieces translation in x axis.
ty	Integer	Pieces translation in y axis.

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.