Scrawl-canvas Tour

Welcome to the Scrawl-canvas Library

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

• Defines a set of factory functions for creating a wide range of graphic artefacts and effects, which can be drawn on a canvas.
• Includes an adaptable - yet easy to use - protocol for positioning, displaying and animating artefacts and effects across the canvas.
• Adds functionality to make <canvas> elements responsive, adapting their size to their surrounding environment while remaining fully interactive.
• Helps make <canvas> elements more accessible for both keyboard and AT users.

→ See the code on Github. → View the CodePen collection. → Discuss Scrawl-canvas on Discord.

Why use Scrawl-canvas?

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):

Resize this grid by dragging its bottom right corner.

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.

Hover over pins to reveal labels; click to visit relevant wikipedia page. Can also use the tab and enter keys to navigate links

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.

Scrawl-canvas version 8.9.9 - released 16 February 2023. Please raise issues in the Discord channel, or Github.

©2022 Rik Roots. Site built and maintained by RikWorks.
Tech: Svelte scaffold, Page.js routing, Tailwind css