tesserae

v0.10.3

Published

3 years ago

Animated mosaic backgrounds with HTML5 Canvas

Downloads

0High
0Medium
0Low

hrvarakl

mosaic background canvas

Tesserae

Animated mosaic backgrounds with HTML5 Canvas (demo)

Tesserae is a small library that creates customizable and optionally animated mosaic patterns that can be used to replace dull/static/image backgrounds.

Tesserae uses HTML5 Canvas instead of (hundreds of) DOM elements to create its backgrounds and requestAnimationFrame to handle its animations. The reasoning behind this lies in the performance gains of Immediate Mode (canvas) vs Retained Mode (DOM). You can read here for more details.

Despite being faster and less memory taxing on modern desktop browsers, using canvas comes with its downsides:

not all browsers support it
canvas performance on some mobile browsers is poor

Both the above issues can be countered by gracefully degrading to a static/image background on mobile browsers or on browsers that do not support canvas.

Installation

Option 1: Browser

Include the /bundle/tesserae.js or /bundle/tesserae.min.js preferably at the end of your <body>, i.e:

<body>

  <!-- your code  -->

  <!-- include tesserae  -->
  <script src="tesserae.min.js"></script>
  <script>
    // use it
	new Tesserae({
		container: '#some-container'
	});
  </script>
</body>

Option 2: CommonJS environment (i.e. webpack or browserify)

Install via npm:

$ npm install tesserae

require it and use it like so:

var Tesserae = require('tesserae');

new Tesserae({
  container: '#some-container'
});

Usage

You can create a new Tesserae mosaic background inside a predefined html container by calling the constructor.

var t = new Tesserae({
  container: '#some-container'
});

Keeping a reference to the returned instance is advised, so you may later invoke some of its methods, for instance in case you wish to destroy or re-draw the background.

Options

You invoke the Tesserae constructor passing an options object. While the only required option is the container selector, you should really play around with different values for the other options to get the result you desire.

Here is the list of all the available options:

container

string: The selector of the element inside which you wish Tesserae to draw the background.

var t = new Tesserae({
  container: '#some-container'
});

NOTE: Tesserae respects the container size. In fact, it expects container to be visible and of non-zero width/height. So for example, trying to initialize Tesserae on an empty <div> whose dimensions are not explicitly set would yield no result.

tesseraWidth

number: The width of each mosaic tile in pixels. default: 30

tesseraHeight

number: The height of each mosaic tile in pixels. default: 30

var t = new Tesserae({
  container: '#some-container',
  tesseraWidth: 40,
  tesseraHeight: 40
});

randomcolor

object: Options to be forwarded to the random color generator. default:

randomcolor = {
  hue: 'monochrome',
  luminosity: 'light'
}

Tesserae uses the Random Color generator by David Merfield to generate random colors for each mosaic tile. For more info on all the available options you can check the project's github page.

// example 1: bright variations of purple-based colors
var t1 = new Tesserae({
  container: '#some-container',
  randomcolor = {
	hue: 'purple',
	luminosity: 'bright'
  }
});

Omitting the randomcolor.hue option will generate a truly random color:

// example 2: dark variations of truly random colors
var t2 = new Tesserae({
  container: '#some-other-container',
  randomcolor = {
	luminosity: 'dark'
  }
});

filter

object or false: Controls the appearance of a filter (overlay) above the mosaic. When false disables the filter entirely. default:

filter = {
  color: '#000',
  opacity: 0.6
}

Filter is best used when bright colors are chosen and/or when text is to be displayed on top of the generated background.

// example: turquise filter with 80% opacity
var t = new Tesserae({
  container: '#some-container',
  filter = {
	color: '#16a085',
	opacity: 0.8
  }
});

gradual

object or false: Controls the draw behavior of the mosaic. When set to false all tiles will be drawn at once. When set to object, tiles will be gradually drawn in batches. Batch size is controlled by the step property. Each batch is drawn in a new animation frame. default:

gradual = {
  enable: true,
  step: 10
}

// example: gradually draw mosaic in batches of 4
var t = new Tesserae({
  container: '#some-container',
  gradual = {
    enable: true,
    step: 4
  }
});

animate

object or false: Controls the draw behavior of individual tiles. When set to false each tile will draw itself immediately, without animation. When set to object, each tile will animate-show itself. The speed of the animation is controlled by the step property. default:

animate = {
  enable: true,
  step: 2
}

// example: animate tiles a little faster on show
var t = new Tesserae({
  container: '#some-container',
  animate = {
    enable: true,
    step: 4
  }
});

live

object or false: Enables "live mode" which forces random tiles to periodically change color. It creates a subtle effect which is barely visible in same-hue backgrounds with filter.

The change interval is random within the range of live.minInterval and live.maxInterval. default:

live = {
  enable: true,
  minInterval: 50,
  maxInterval: 500
}

// example: live backround with random hue and shorter change intervals
var t = new Tesserae({
  container: '#some-container',
  live: {
    // shorter intervals make effect more prominent
    minInterval: 10,
    maxInterval: 100
  }
});

Methods

By keeping a reference to the created Tesserae instance you may invoke the following methods:

destroy()

Destroys the canvas and unregisters all listeners.

// create a Tesserae instance
var t = new Tesserae({
  container: '#some-container'
});
// destroy it
t.destroy();

draw()

Draws the mosaic. It is automatically called upon the creation of a new instance. Manually calling it again will re-draw the mosaic. It is a good idea to manually call draw anytime the container size changes.

NOTE: Tesserae listens for window resize events and re-draws automatically, so you need only worry about programatical size changes of the container (i.e. when you manually update its size)

// create a Tesserae instance
var t = new Tesserae({
  container: '#some-container'
});
// re-draw
t.draw();

License

MIT

Author

Christopher Varakliotis