Skip to content
Shaw edited this page Nov 13, 2015 · 16 revisions

Canvallax.js

Easy parallax effects on <canvas>

Canvallax is a small (5.5kb minified, 2kb gzipped) dependency-free Javascript library for managing elements on <canvas>. Support is built-in for:

  • Parallax Scrolling, with optional damping to smooth motions
  • Distance/scaling
  • Images on Canvas, from URLs or nodes (<img />, <canvas />, etc) with Canvallax.Image
  • Common shapes (Canvallax.Circle, Canvallax.Polygon and Canvallax.Rectangle)
  • Element stacking with zIndex
  • Fixed position Elements
  • Element cloning

The Canvallax library is primarily meant to help with managing individual elements on canvas with unified positioning, scale and scroll effects. Some canvas knowledge will be needed for more advanced implementations like custom elements and animation, though most effects can be achieved with the built-in functionality.

Examples

Starfield Header Image Slice Pointer Tracking Parallax Sky Background Falling Hexagon Mask transformOrigin

View the CodePen collection of Canvallax demos

Basic Usage

Create a new Canvallax instance either by calling new Canvallax() or Canvallax(), either will work. First variable is an optional object containing options, the default values are shown below.

  var myCanvallax = Canvallax(),
      img = Canvallax.Image('image.jpg'),
      circle = Canvallax.Circle(),
      triangle = Canvallax.Polygon({
        sides: 3
      }),
      square = Canvallax.Rectangle({
        width: 100,
        height: 100
      });
  
  myCanvallax.add(img,circle,triangle,square);
  

Options

Options are set from an object provided when the Canvallax instance is created. These options are applied as properties to the Canvallax instance and can be changed later on directly, e.g. myCanvallax.x = 200;.

All options are shown below with the default values.

  Canvallax({

    tracking: 'scroll',
    // (false||'scroll'||'pointer')
    // If 'scroll', the `x` and `y` of the scene are tied to document's scroll for a typical parallax experience.
    // If 'pointer', the `x` and `y` of the scene will be tied to the pointer (mouse or touch)
    // Set to false if you want to control the scene's X and Y manually, perfect for animating with GSAP.

    trackingInvert: false,
    // (true||'invertx'||'inverty')
    // Inversion of the tracking values.
    // If true, 'invertx' or 'inverty', the appropriate axes will be reversed on scroll.

    x: 0,
    // (Number)
    // Starting x position.
    // If `tracking` is enabled, this will be overridden on render.

    y: 0,
    // (Number)
    // Starting y position.
    // If `tracking` is enabled, this will be overridden on render.

    damping: 1,
    // (Number)
    // The 'easing' of the x & y position when updated. 1 = none, higher is longer.
    // If you're syncing parallax items to regular items in the scroll, then you'll probably want a low damping.

    canvas: undefined,
    // (Node)
    // Use Canvallax on an existing canvas node, otherwise one is created.

    className: '',
    // (String)
    // Classes to add to the canvas, in addition to the 'canvallax' class automatically added.

    parent: document.body,
    // (Node)
    // Canvas is prepended to document.body by default. Override with your own node if you want it within a certain container.

    elements: undefined,
    // (Array)
    // Collection of elements to render on the Canvallax instance

    animating: true,
    // (Boolean)
    // Update canvas every requestAnimationFrame call.

    fullscreen: true,
    // (Boolean)
    // Set the canvas width and height to the size of the window, and update on window resize. Otherwise, the provided with and height will be used.

    preRender: noop,
    // (Function)
    // Callback before elements are rendered.

    postRender: noop
    // (Function)
    // Callback after elements are rendered.
    
  });

Methods

Each Canvallax instance has the following methods:

  • add(element,...): Add an element or array of elements to the Canvallax instance
  • remove(element): Remove an element from the Canvallax instance
  • render(): Clears canvas and renders all elements. This is called every requestAnimationFrame when the Canvallax instance is animating.
  • resize(width,height): Set canvas width and height
  • resizeFullscreen(): Set canvas to full window width & height, perfect for backgrounds.
  • play(): Render Canvallax elements every requestAnimationFrame
  • pause(): Stop Canvallax rendering

Utilities

  • Canvallax.extend(object,object,...): Merge properties of objects onto the first object. If only one object provided, the properties will be applied to Canvallax, much like jQuery.extend.
  • [Canvallax.createElement(properties)](https://github.com/shshaw/Canvallax.js/wiki/Canvallax.createElement()): Create an element type that can be added to Canvallax. The object provided will be added to that element's prototype and inherited by each element of that type. Each element type created should have a render property with a function that will actually draw that element on the canvas.