Canvas element

Usage

A canvas consists of a drawable region defined in HTML code with height and width attributes. JavaScript code may access the area through a full set of drawing functions similar to those of other common 2D APIs, thus allowing for dynamically generated graphics. Some anticipated uses of canvas include building graphs, animations, games, and image composition.

Interacting with the canvas involves obtaining the canvas' rendering context, which determines whether to use the canvas API, WebGL, or WebGL2 rendering context.

Example

The following code creates a <canvas> element in an HTML page:

<span id="mwRA"></span><span class="p" id="mwRQ"><</span><span class="nt" id="mwRg">canvas</span> <span class="na" id="mwRw">id</span><span class="o" id="mwSA">=</span><span class="s" id="mwSQ">"example"</span> <span class="na" id="mwSg">width</span><span class="o" id="mwSw">=</span><span class="s" id="mwTA">"200"</span> <span class="na" id="mwTQ">height</span><span class="o" id="mwTg">=</span><span class="s" id="mwTw">"200"</span><span class="p" id="mwUA">></span> This text is displayed if your browser does not support HTML canvas element. <span class="p" id="mwUQ"></</span><span class="nt" id="mwUg">canvas</span><span class="p" id="mwUw">></span>

Using JavaScript, you can draw on the canvas:

<span id="mwWA"></span><span class="kd" id="mwWQ">var</span><span class="w" id="mwWg"> </span><span class="nx" id="mwWw">example</span><span class="w" id="mwXA"> </span><span class="o" id="mwXQ">=</span><span class="w" id="mwXg"> </span><span class="nb" id="mwXw">document</span><span class="p" id="mwYA">.</span><span class="nx" id="mwYQ">getElementById</span><span class="p" id="mwYg">(</span><span class="s1" id="mwYw">'example'</span><span class="p" id="mwZA">);</span> <span class="kd" id="mwZQ">var</span><span class="w" id="mwZg"> </span><span class="nx" id="mwZw">context</span><span class="w" id="mwaA"> </span><span class="o" id="mwaQ">=</span><span class="w" id="mwag"> </span><span class="nx" id="mwaw">example</span><span class="p" id="mwbA">.</span><span class="nx" id="mwbQ">getContext</span><span class="p" id="mwbg">(</span><span class="s1" id="mwbw">'2d'</span><span class="p" id="mwcA">);</span> <span class="nx" id="mwcQ">context</span><span class="p" id="mwcg">.</span><span class="nx" id="mwcw">fillStyle</span><span class="w" id="mwdA"> </span><span class="o" id="mwdQ">=</span><span class="w" id="mwdg"> </span><span class="s1" id="mwdw">'red'</span><span class="p" id="mweA">;</span> <span class="nx" id="mweQ">context</span><span class="p" id="mweg">.</span><span class="nx" id="mwew">fillRect</span><span class="p" id="mwfA">(</span><span class="mf" id="mwfQ">30</span><span class="p" id="mwfg">,</span><span class="w" id="mwfw"> </span><span class="mf" id="mwgA">30</span><span class="p" id="mwgQ">,</span><span class="w" id="mwgg"> </span><span class="mf" id="mwgw">50</span><span class="p" id="mwhA">,</span><span class="w" id="mwhQ"> </span><span class="mf" id="mwhg">50</span><span class="p" id="mwhw">);</span>

This code draws a red rectangle on the screen.

The Canvas API also provides save() and restore(), for saving and restoring all the canvas context's attributes.

Canvas element size versus drawing surface size

A canvas actually has two sizes: the size of the element itself and the size of the element's drawing surface. Setting the element's width and height attributes sets both of these sizes; CSS attributes affect only the element's size and not the drawing surface.

By default, both the canvas element's size and the size of its drawing surface is 300 screen pixels wide and 150 screen pixels high. In the listing shown in the example, which uses CSS to set the canvas element's size, the size of the element is 600 pixels wide and 300 pixels high, but the size of the drawing surface remains unchanged at the default value of 300 pixels × 150 pixels. When a canvas element's size does not match the size of its drawing surface, the browser scales the drawing surface to fit the element (which may result in surprising and unwanted effects).

Example setting element size and drawing surface size to different values:

<span id="mwlA"></span><span class="cp" id="mwlQ"><!DOCTYPE html></span> <span class="p" id="mwlg"><</span><span class="nt" id="mwlw">html</span><span class="p" id="mwmA">></span> <span class="p" id="mwmQ"><</span><span class="nt" id="mwmg">head</span><span class="p" id="mwmw">></span> <span class="p" id="mwnA"><</span><span class="nt" id="mwnQ">title</span><span class="p" id="mwng">></span>Canvas element size: 600 x 300, Canvas drawing surface size: 300 x 150<span class="p" id="mwnw"></</span><span class="nt" id="mwoA">title</span><span class="p" id="mwoQ">></span> <span class="p" id="mwog"><</span><span class="nt" id="mwow">style</span><span class="p" id="mwpA">></span> <span class="w" id="mwpQ"> </span><span class="nt" id="mwpg">body</span><span class="w" id="mwpw"> </span><span class="p" id="mwqA">{</span> <span class="w" id="mwqQ"> </span><span class="k" id="mwqg">background</span><span class="p" id="mwqw">:</span><span class="w" id="mwrA"> </span><span class="mh" id="mwrQ">#dddddd</span><span class="p" id="mwrg">;</span> <span class="w" id="mwrw"> </span><span class="p" id="mwsA">}</span> <span class="w" id="mwsQ"> </span><span class="p" id="mwsg">#</span><span class="nn" id="mwsw">canvas</span><span class="w" id="mwtA"> </span><span class="p" id="mwtQ">{</span> <span class="w" id="mwtg"> </span><span class="k" id="mwtw">margin</span><span class="p" id="mwuA">:</span><span class="w" id="mwuQ"> </span><span class="mi" id="mwug">20</span><span class="kt" id="mwuw">px</span><span class="p" id="mwvA">;</span> <span class="w" id="mwvQ"> </span><span class="k" id="mwvg">padding</span><span class="p" id="mwvw">:</span><span class="w" id="mwwA"> </span><span class="mi" id="mwwQ">20</span><span class="kt" id="mwwg">px</span><span class="p" id="mwww">;</span> <span class="w" id="mwxA"> </span><span class="k" id="mwxQ">background</span><span class="p" id="mwxg">:</span><span class="w" id="mwxw"> </span><span class="mh" id="mwyA">#ffffff</span><span class="p" id="mwyQ">;</span> <span class="w" id="mwyg"> </span><span class="k" id="mwyw">border</span><span class="p" id="mwzA">:</span><span class="w" id="mwzQ"> </span><span class="kc" id="mwzg">thin</span><span class="w" id="mwzw"> </span><span class="kc" id="mw0A">inset</span><span class="w" id="mw0Q"> </span><span class="mh" id="mw0g">#aaaaaa</span><span class="p" id="mw0w">;</span> <span class="w" id="mw1A"> </span><span class="k" id="mw1Q">width</span><span class="p" id="mw1g">:</span><span class="w" id="mw1w"> </span><span class="mi" id="mw2A">600</span><span class="kt" id="mw2Q">px</span><span class="p" id="mw2g">;</span> <span class="w" id="mw2w"> </span><span class="k" id="mw3A">height</span><span class="p" id="mw3Q">:</span><span class="w" id="mw3g"> </span><span class="mi" id="mw3w">300</span><span class="kt" id="mw4A">px</span><span class="p" id="mw4Q">;</span> <span class="w" id="mw4g"> </span><span class="p" id="mw4w">}</span> <span class="w" id="mw5A"> </span><span class="p" id="mw5Q"></</span><span class="nt" id="mw5g">style</span><span class="p" id="mw5w">></span> <span class="p" id="mw6A"></</span><span class="nt" id="mw6Q">head</span><span class="p" id="mw6g">></span> <span class="p" id="mw6w"><</span><span class="nt" id="mw7A">body</span><span class="p" id="mw7Q">></span> <span class="p" id="mw7g"><</span><span class="nt" id="mw7w">canvas</span> <span class="na" id="mw8A">id</span><span class="o" id="mw8Q">=</span><span class="s" id="mw8g">"canvas"</span><span class="p" id="mw8w">></span> Canvas not supported <span class="p" id="mw9A"></</span><span class="nt" id="mw9Q">canvas</span><span class="p" id="mw9g">></span> <span class="p" id="mw9w"></</span><span class="nt" id="mw-A">body</span><span class="p" id="mw-Q">></span> <span class="p" id="mw-g"></</span><span class="nt" id="mw-w">html</span><span class="p" id="mw_A">></span>

Canvas versus Scalable Vector Graphics (SVG)

SVG is an alternative approach to drawing shapes in browsers. Unlike canvas, which is raster-based, SVG is vector-based, so that each drawn shape is remembered as an object in a scene graph or Document Object Model, which is subsequently rendered to a bitmap. This means that if attributes of an SVG object are changed, the browser can automatically re-render the scene.

Canvas objects, on the other hand, are drawn in immediate mode. In the canvas example above, the rectangle draw operation modifies the canvas, and its representation as a rectangle is forgotten by the system. If the rectangle's position were to be changed, the canvas would need to be redrawn, including any objects that might have been covered by the rectangle. In the equivalent SVG case, one could simply change the position attributes of the rectangle and the browser would determine how to repaint it. There are additional JavaScript libraries that abstract the canvas model to have svg-like scene capabilities within the canvas element. Multiple canvas layers can also be used, meaning that only specific layers need to be recreated when changes are required.

SVG images are represented in XML, and complex scenes can be created and maintained with XML editing tools.

The SVG scene graph enables event handlers to be associated with objects, so a rectangle may respond to an onClick event. To get the same functionality with canvas, one must manually match the coordinates of the mouse click with the coordinates of the drawn rectangle to determine whether it was clicked.

Conceptually, canvas is a lower-level API upon which higher-level interfaces might be built (for example, SVG support). There are JavaScript libraries that provide partial SVG implementations using canvas for browsers that do not provide SVG but support canvas, such as the browsers in Android 2.x. However, this is not normally the case—they are independent standards. The situation is complicated because there are scene graph libraries for canvas, and SVG has some bitmap manipulation functionality.

Reactions

At the time of its introduction, the canvas element was met with mixed reactions from the web standards community. There have been arguments against Apple's decision to create a new proprietary element instead of supporting the SVG standard. There are other concerns about syntax, such as the absence of a namespace.

Intellectual property over canvas

On March 14, 2007, WebKit developer Dave Hyatt forwarded an email from Apple's Senior Patent Counsel, Helene Plotka Workman, which stated that Apple reserved all intellectual property rights relative to WHATWG's Web Applications 1.0 Working Draft, dated March 24, 2005, Section 10.1, entitled "Graphics: The bitmap canvas", but left the door open to licensing the patents should the specification be transferred to a standards body with a formal patent policy. This caused considerable discussion among web developers and raised questions concerning the WHATWG's lack of a policy on patents in comparison to the World Wide Web Consortium (W3C)'s explicit favoring of royalty-free licenses. Apple later disclosed the patents under the W3C's royalty-free patent licensing terms. The disclosure means that Apple is required to provide royalty-free licensing for the patent whenever the Canvas element becomes part of a future W3C recommendation created by the HTML working group.

Privacy concerns

Canvas fingerprinting is one of a number of browser fingerprinting techniques for tracking online users that allow websites to identify and track visitors using the HTML <canvas> element. The technique received wide media coverage in 2014, after researchers from Princeton University and KU Leuven University described it in their paper The Web never forgets. The privacy concerns regarding canvas fingerprinting center around the fact that even deleting cookies and clearing the cache will not be sufficient for users to avoid online tracking.

Browser support

The element is supported by the current versions of Mozilla Firefox, Google Chrome, Internet Explorer, Safari, Konqueror, Opera and Microsoft Edge.