@import 'nojs.css';

Please note: this site uses the Scrawl-canvas Javascript library to demonstrate responsive and interactive HTML5 <canvas> elements. As you are viewing the site with Javascript disabled, much of the page's functionality - including internal links - has also been disabled.

Tour Learn How Do I? Docs Demos GitHub

hello world canvas - snapshot of the canvas displaying the banner animation

Scrawl-canvas - make the canvas work for you

Scrawl-canvas is a Javascript library for working with the HTML5 <canvas> element. The library:

Adds functionality to make <canvas> elements responsive, adapting their size according to their surrounding environment.
Makes the canvas both accessible, and interactive - including the ability to easily track user interactions with different parts of the canvas.
Defines a set of factory functions to create a wide range of graphic artefacts and effects which can be drawn on a canvas.
Includes an adaptable - yet easy to use - protocol to position, display and animate artefacts and effects across the canvas.
Builds, controls and animates many canvases - it automatically discovers existing <canvas> elements in a web page, and can add and remove <canvas> elements dynamically, in real time.

Why does the world need Scrawl-canvas?

Working with the native Canvas API is hard work

Particularly when the desired result is more complex than a couple of coloured boxes in a static display.

Working directly with the canvas-related APIs leads to writing significant amounts of JS boilerplate code.
<canvas> elements can be resized and styled using CSS, but changing the CSS size does not affect the element's drawing dimensions - leading to sub-optimal graphic displays.
Events work on the canvas, not on the artefacts within the canvas - we cannot use artefacts as links or hot-spots (click/tap events), we cannot give them the equivalent of a CSS hover state (focus/blur events), we cannot drag-and-drop them around the display (move events).
Tracking a user's interaction with the various parts of a canvas display is particularly difficult.
We cannot save and share artefacts and effects; each canvas display is tightly coupled to the code that defines the display.
Of most concern, canvases are entirely graphical - visual - by nature; they come with significant accessibility issues. Given the ever-stricter requirements for websites to be accessible to all users, this makes using a canvas to present important information a dangerous proposition.

But the benefits of using canvases for graphical displays and animations are also great

Canvases are part of the DOM (unlike Flash); they are natively wired for events and user interactions; they use immediate mode redering (which makes them very quick); and the canvas-related APIs are designed to be used with Javascript.

There are a number of other Javascript canvas libraries available, each with their strengths and weaknesses. Some have been designed to make the production of charts and other data visualisations easier. Some focus on game development, others on making videos interactive.

Libraries which attempt to emulate Flash-Actionscript animations have been developed, as have libraries whose aim is to combine 2D, 3D and even SVG graphics into a usable whole. Speed is a key goal for some of the best libraries, while ease-of-use is an objective for many others.

Scrawl-canvas overcomes the big barriers

Scrawl-canvas aims to be fast, and developer-friendly. It also aims to be broadly focussed, suitable for building infographics, games, interactive videos - whatever we can imagine for a 2D graphical presentation.

But the main purpose of Scrawl-canvas is to make the <canvas> element - and the parts that make up its displays and animations - Responsive, Interactive, Linkable, Trackable, and Accessible!

Responsive canvas elements

The HTML5 <canvas> element was not designed to be responsive. When we add a canvas to a web page, we give it fixed width and height values, which define its drawing (bitmap) dimensions.

To make the web page responsive, so that it can look good across a range of browser sizes and device screens, we need to define a range of sizes using relative proportions - such as CSS percentage values.

This approach fails for the <canvas> element because browsers will stretch its drawing area to match the CSS-defined dimensions, which often leads to an ugly, distorted result.

Scrawl-canvas allows us to define the canvas dimensions in CSS, then displays the canvas output in that area in a variety of ways using a fit attribute (which parodies the CSS object-fit property):

responsive canvases - snapshot of four canvases, each showing the effects of a different 'fit' attribute

Fitting the canvas into a space in the web page is one thing. Positioning the artefacts and effects that make up the canvas's display is another. The HTML5 Canvas API includes many functions for creating graphical elements; all of them use absolute pixel values to define, size and position them on the canvas.

Scrawl-canvas simplifies the Canvas API, supplying a range of factory functions to create 'artefacts', 'styles' and other objects - including animations and tweens - which can be used together to create a canvas display.

Once created, we can position these objects on the canvas in a number of ways:

Absolute positioning - using the canvas like a coordinates grid (which is how the Canvas API positions objects).
Relative positioning - place objects on the canvas using relative percentage values; if the canvas size changes, the objects stay in the same place relative to the canvas.
Reference positioning - use an artefact as a reference against which other artefacts can position themselves; when we update the reference artefact's position, the other artefacts update their position values automatically.

The canvas below uses all these techniques to create its display. The result is entirely responsive - try resizing the browser window to see how the scene looks at smaller and larger viewport sizes!

Accessible and interactive canvas elements

The <canvas> element really comes into its own when we add user-interaction features to it:

Hotspots - defined areas within the display which users can hover over or click/tap to reveal additional information, trigger a tween animation, cause changes in other parts of the web page ... or even navigate to a different web page.
Mouse/touch cursor tracking - attach a graphical artefact to the mouse cursor, or drag-and-drop artefacts around the canvas (or even between different canvases).

Building this functionality for a normal, static canvas display is difficult enough. To build it for a responsive canvas display may seem impossible, given modern time and resource constraints.

Accessible canvas - snapshot of a kitchen scene with accessible links to related Wikipedia articles

Scrawl-canvas makes building such features easier!

More importantly, Scrawl-canvas does a lot of heavy lifting to make those features accessible to users who cannot - for whatever reason - view the canvas display. Links can be made accessible via the keyboard; graphical text is (by default) copied into the DOM so it can be accessed by screen readers. Every Scrawl-canvas canvas comes with ARIA attributes.

Tracking user journeys

Once we've built the canvas, we can add third-party tracker functionality to help record user journeys through its display, record click convertions - whatever the client needs to monitor the effectiveness of their site or campaign.

Go wild with your web pages: do amazing stuff!

Scrawl-canvas is not the solution to all graphical representation problems: for many website designs other canvas and/or SVG libraries may provide a better route to meeting the client's requirements.

But if a site design calls for a responsive, accessible and interactive <canvas> display, Scrawl-canvas should be able to deliver the goods.

Resources

Documentation is supplied as inline comments in the code base, and can be viewed as web pages from the Docs link. Most module files include links to test examples which demonstrate the code functionality.

Code examples can be found in the Demos section of this site. All the demos have links to view the code.

The Learning and "How do I?" cookbook articles on this site are currently under development. If people have suggestions for articles please let me know via GitHub.

The code repository can be found and downloaded from GitHub. It has been released under an MIT Licence and is free-to-use in both personal and commercial projects. Use at your own risk!

Scrawl-canvas version 8.3.0 - released 2 Dec 2020. Please raise issues in Github