Help language development. Donate to The Perl Foundation

HTML::Canvas cpan:WARRINGD last updated on 2022-02-10


Actions Status


This is a Raku module for composing and rendering HTML-5 canvases.

It supports the majority of the HTML Canvas 2D Context API.

A canvas may be constructed via the API, then rendered to JavaScript via the toDataURL(), .js() or .to-html() methods, or saved to a Cairo-supported format such as PNG, SVG or PDF.

The module includes classes:


This package depends on Cairo, Font::FreeType, Text::FriBidi and HarfBuzz. Additional fonts may also be required on your system on your system:


use v6;
# Create a simple Canvas. Save as PNG and HTML

use HTML::Canvas;
my HTML::Canvas $canvas .= new: :width(150), :height(100);

$canvas.context: -> \ctx {
    ctx.strokeRect(0, 0, 150, 100);; {
        ctx.fillStyle = "orange";
        ctx.fillRect(10, 10, 50, 50);

        ctx.fillStyle = "rgba(0, 0, 200, 0.3)";
        ctx.fillRect(35, 35, 50, 50);
    }; ctx.restore;

    ctx.font = "18px Arial";
    ctx.fillText("Hello World", 40, 75);

# save canvas as PNG
use Cairo;
my Cairo::Image $img = $canvas.image;
$img.write_png: "examples/canvas-demo.png";

# also save canvas as HTML, source and data URL:
#  1. Save source Javascript
my $html = "<html><body>{ $ }</body></html>";
"examples/canvas-demo-js.html".IO.spurt: $html;
#  2. Save data URL Image
my $data-uri = $canvas.toDataURL();
$html = "<html><body><img src='$data-uri'/></body></html>";
"examples/canvas-demo-url.html".IO.spurt: $html;


Saving as PDF

use v6;
use Cairo;
use HTML::Canvas;
use HTML::Canvas::To::Cairo;
# create a 128 X 128 point PDF
my Cairo::Surface::PDF $surface .= create("examples/read-me-example.pdf", 128, 128);

# create a PDF with two pages
# use a common cache for objects shared between pages such as
# fonts and images. This reduces both processing times and PDF file sizes.
my HTML::Canvas::To::Cairo::Cache $cache .= new;

for 1..2 -> $page {
    my HTML::Canvas $canvas .= new: :$surface, :$cache;
    $canvas.context: {
        .font = "10pt times-roman bold";
        .fillStyle = "blue";
        .strokeStyle = "red";
        .save; {
            .fillStyle = "rgba(1.0, 0.2, 0.2, 0.25)";
            .rect(15, 20, 50, 50);
        }; .restore;
        .fillText("Page $page/2", 12, 12);



The HTML::Canvas::Image class is used to upload images for inclusion in HTML documents, and/or rendering by back-ends.

use HTML::Canvas;
use HTML::Canvas::Image;

my HTML::Canvas $canvas .= new;
my @html-body;
# add the image, as a hidden DOM item
my HTML::Canvas::Image \image .= open("t/images/camelia-logo.png");
@html-body.push: image, :style("visibility:hidden");
# draw it
$canvas.context: -> \ctx {
    ctx.drawImage(image, 10, 10  );  

@html-body.push: $;

my $html = "<html><body>" ~ @html-body.join ~ "</body></html>";

HTML::Canvas::Image can load a variety of image formats. The built-in HTML::Canvas::To::Cairo renderer only supports PNG images, as below:

Currently supported image formats are:

HTML::Canvas (HTML) X X X X
HTML::Canvas::To::Cairo X
HTML::Canvas::To::PDF X X X


HTML::Canvas::Path2D can be used to create a re-usable path that can be passed to calls to the fill() or stroke() methods:

use HTML::Canvas;
use HTML::Canvas::Path2D;

my HTML::Canvas $canvas .= new;

$canvas.context: -> \ctx {
    # Create path
    my HTML::Canvas::Path2D \region .= new;
    region.moveTo(30, 90);
    region.lineTo(110, 20);
    region.lineTo(240, 130);
    region.lineTo(60, 130);
    region.lineTo(190, 20);
    region.lineTo(270, 90);

    ctx.fillStyle = 'green';
    ctx.fill(region, 'evenodd');

    ctx.translate(100, 100);
    ctx.fillStyle = 'blue';

The following methods can be used in path construction:

Font Loading

Font Resources

This module integrates with the CSS::Font::Resources module.

A list of @font-face CSS font descriptors can be passed to the canvas object to specify font sources. Fonts are resolved the same way as @font-face rules in a stylesheet.

For example:

use HTML::Canvas;
use HTML::Canvas::To::Cairo;
use CSS::Font::Descriptor;
use Cairo;

my CSS::Font::Descriptor $ugly .= new: :font-family<arial>, :src<url(resources/font/FreeMono.ttf)>;
my HTML::Canvas $canvas .= new: :font-face[$ugly], :width(650), :height(400);
$canvas<scale>(2.0, 3.0);
$canvas<font> = "30px Arial";
$canvas.fillText("Hello World",10,50);
# save canvas as PNG
my Cairo::Surface $surface = $canvas.image;
$surface.write_png: "tmp/ariel-ugly.png";

Note that supported fonts may be backend dependant.

Font System Loading

Local fonts and fonts without matching @font-face font descriptors are resolved using fontconfig's fc-match utility. For example:

% fc-match 'arial;weight=bold'
DejaVuSans.ttf: "DejaVu Sans" "Book"

If fc-match is unable to find a font. HTML::Canvas currently falls back to using a mono-spaced font (FreeMono).

The font may need to be installed on your system and/or fontconfig may need additional configuration to ensure it finds the correct font.


The methods below implement the majority of the W3C HTML Canvas 2D Context API.



has Numeric $.lineWidth = 1.0;


has Numeric $.globalAlpha = 1.0;


subset LineCap of Str where 'butt'|'round'|'square';
has LineCap $.lineCap = 'butt';


subset LineJoin of Str where 'bevel'|'round'|'miter';
has LineJoin $.lineJoin = 'bevel';


has Str $.font = '10pt times-roman';


subset Baseline of Str where 'alphabetic'|'top'|'hanging'|'middle'|'ideographic'|'bottom';
has Baseline $.textBaseline = 'alphabetic';


subset TextAlignment of Str where 'start'|'end'|'left'|'right'|'center';
has TextAlignment $.textAlign = 'start';


subset TextDirection of Str where 'ltr'|'rtl';
has TextDirection $.direction = 'ltr';


subset ColorSpec where Str|HTML::Canvas::Gradient|HTML::Canvas::Pattern;
has ColorSpec $.fillStyle is rw = 'black';


has ColorSpec $.strokeStyle is rw = 'black';


 has Numeric @.lineDash;


  has Numeric $.lineDashOffset = 0.0;

Graphics State



scale(Numeric $x, Numeric $y)

rotate(Numeric $rad)

translate(Numeric $x, Numeric $y)

transform(Numeric \a, Numeric \b, Numeric \c, Numeric \d, Numeric \e, Numeric \f)

setTransform(Numeric \a, Numeric \b, Numeric \c, Numeric \d, Numeric \e, Numeric \f)

Painting Methods

clearRect(Numeric $x, Numeric $y, Numeric $w, Numeric $h)

fillRect(Numeric $x, Numeric $y, Numeric $w, Numeric $h)

strokeRect(Numeric $x, Numeric $y, Numeric $w, Numeric $h)


fill(FillRule $rule?) or fill(HTML::Canvas::Path2D $path, FillRule $rule?)

stroke(HTML::Canvas::Path2D $path?)


fillText(Str $text, Numeric $x, Numeric $y, Numeric $max-width?)

strokeText(Str $text, Numeric $x, Numeric $y, Numeric $max-width?)

measureText(Str $text)

Path Methods


moveTo(Numeric \x, Numeric \y)

lineTo(Numeric \x, Numeric \y)

quadraticCurveTo(Numeric \cp1x, Numeric \cp1y, Numeric \x, Numeric \y)

bezierCurveTo(Numeric \cp1x, Numeric \cp1y, Numeric \cp2x, Numeric \cp2y, Numeric \x, Numeric \y)

rect(Numeric $x, Numeric $y, Numeric $w, Numeric $h)

arc(Numeric $x, Numeric $y, Numeric $radius, Numeric $startAngle, Numeric $endAngle, Bool $counterClockwise?)

Images Patterns and Gradients


multi method drawImage( $image, Numeric \sx, Numeric \sy, Numeric \sw, Numeric \sh, Numeric \dx, Numeric \dy, Numeric \dw, Numeric \dh);
multi method drawImage(CanvasOrXObject $image, Numeric $dx, Numeric $dy, Numeric $dw?, Numeric $dh?)

createLinearGradient(Numeric $x0, Numeric $y0, Numeric $x1, Numeric $y1)

createRadialGradient(Numeric $x0, Numeric $y0, Numeric $r0, Numeric $x1, Numeric $y1, Numeric:D $r1)

createPattern($image, HTML::Canvas::Pattern::Repetition $repetition = 'repeat')


use HTML::Canvas;
use HTML::Canvas::Image;

my HTML::Canvas \ctx .= new;
my @html-body;

## Images ##

my HTML::Canvas::Image \image .= open("t/images/crosshair-100x100.jpg");

# save to HTML
@html-body.push: image, :style("visibility:hidden");
# draw on the canvas
ctx.drawImage(image,  20, 10,  50, 50);

## Patterns ##

my \pat = ctx.createPattern(image,'repeat');
ctx.fillStyle = pat;

## Gradients

with ctx.createRadialGradient(75,50,5,90,60,100) -> $grd {
    ctx.fillStyle = $grd;
    ctx.fillRect(10, 10, 150, 100);

say ctx.js;

Image Data

Currently support for getImageData and putImageData (3 argument format) only.

getImageData(Numeric sx, Numeric sy, Numeric sw, Numeric sh)

putImageData(image-data, Numeric dx, Numeric dy)

Additional Rendering Backends