/pieces

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

Primary LanguageJavaScriptMIT LicenseMIT

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.