# Two.js

A two-dimensional drawing api geared towards modern web browsers. It is renderer agnostic enabling the same api to draw in multiple contexts: svg, canvas, and webgl.

Github

# Download

Download

Development 93KB Production 40KB

TIP

Prior to v0.7.0-alpha.1 Two.js requires Underscore.js and Backbone.js Events. If you're already loading these files elsewhere then you can build the project yourself and get the file size even smaller. For more information on custom builds check out the source on github.

Node.js Version with npm:

npm install --save two.js@latest

# Overview

Overview

  • # Focus on Vector Shapes

    Two.js is deeply inspired by flat motion graphics (opens new window). As a result, two.js aims to make the creation and animation of flat shapes easier and more concise.

  • # Scenegraph

    At its core two.js relies on a scenegraph (opens new window). This means that when you draw or create an object (a Two.Path or Two.Group), two actually stores and remembers that. After you make the object you can apply any number of operations to it — e.g: rotation, position, scale, etc..

  • # Animation Loop

    Two.js has a built in animation loop. It is simple in nature and can be automated or paired with another animation library. For more information check out the examples.

  • # SVG Interpreter

    Two.js features a Scalable Vector Graphics (opens new window) Interpreter. This means developers and designers alike can create SVG elements in commercial applications like Adobe Illustrator (opens new window) and bring them into your two.js scene. For more information check out the examples.

# Basic Usage

Basic Usage

In order to start any of these demos you'll want to download two.js and add it to your HTML document. Once downloaded add this tag to the <head> of your document: <script src="./path-to-two/two.js"></script>. When you visit the page, you should be able to open up the console and type Two. If this returns a function (and not an error) then you're ready to begin!

# Drawing Your First Shapes

Drawing Your First Shapes

Before we get into all the fancy animating it's good to get a feel for how to make shapes in two.js. In order to do this we need to have an instance of two. This sets up a dom element that contains either an svg or canvas element to add to the webpage. The two object has a scene which holds all shapes as well as methods for creating shapes.

TIP

For a list of all properties and construction parameters check out the documentation.

 
 

# Shapes and Groups

Shapes and Groups

Adding shapes to groups makes managing multiple shapes easier and more sane. Group's provide an easy way to move your content through position, rotation, and scale. These operations emit from the coordinate space (0, 0). In the example below we can see that the initial orientation of the circle and rectangle changed from the first example. These shapes are oriented around (0, 0), which allows us to transform the group around the centeroid of the shapes. In addition Group's styling operations trickle down and apply to each shape.

 
 

# Adding Motion

Adding Motion

Finally, let's add some motion to our shapes. So far the examples use two.update(); to draw content to the screen. The instance of two.js has two particular methods for animation. The first is two.play(); which calls two.update(); at 60 frames-per-second. This rate, however, will slowdown if there's too much content to render per frame.

The second method is two.bind(); This method takes a string as its first parameter indicating what event to listen to and a function as its second argument delineating what to do when the event described in the first parameter happens. To sync a function with the animation loop simply invoke two.bind('update', referenceToFunction); as outlined below:

 
 

# Next Steps

Now that you got a quick glimpse into some of the functionality two.js offers, check out the official and community examples to see what else you can do. These examples range from showing off specific features of the library to using the library in other environments, like React and Angular.

Looking for more information on a specific property? Then head over to the documentation which outlines all of the library's public features.

Haven't found what you're looking for? Then ask a question on our GitHub (opens new window) page.



# Project Credits

Two.js is dependency free, but its creation would not have been possible without these great contributions to the JavaScript ecosystem:

Site design by Yuin (opens new window) • Site development in collaboration with Tonia (opens new window)

Two.js is a project by Jono (opens new window) and numerous contributors (opens new window)

published under the MIT License (opens new window) © 2012 – 2021