CanvasRenderingContext2D

The CanvasRenderingContext2D interface provides the 2D rendering context for the drawing surface of a <canvas> element.

To get an object of this interface, call getContext() (en-US) on a <canvas>, supplying "2d" as the argument:

var canvas = document.getElementById('mycanvas');
var ctx = canvas.getContext('2d');

Once you have the 2D rendering context for a canvas, you can draw within it. For example:

ctx.fillStyle = "rgb(200,0,0)";
ctx.fillRect(10, 10, 55, 50);

See the properties and methods in the sidebar and below. The canvas tutorial has more information, examples, and resources as well.

Drawing rectangles

There are three methods that immediately draw rectangles to the bitmap.

CanvasRenderingContext2D.clearRect() (en-US)
Sets all pixels in the rectangle defined by starting point (x, y) and size (width, height) to transparent black, erasing any previously drawn content.
CanvasRenderingContext2D.fillRect() (en-US)
Draws a filled rectangle at (x, y) position whose size is determined by width and height.
CanvasRenderingContext2D.strokeRect() (en-US)
Paints a rectangle which has a starting point at (x, y) and has a w width and an h height onto the canvas, using the current stroke style.

Drawing text

The following methods are provided for drawing text. See also the TextMetrics (en-US) object for text properties.

CanvasRenderingContext2D.fillText() (en-US)
Draws (fills) a given text at the given (x,y) position.
CanvasRenderingContext2D.strokeText() (en-US)
Draws (strokes) a given text at the given (x, y) position.
CanvasRenderingContext2D.measureText() (en-US)
Returns a TextMetrics (en-US) object.

Line styles

The following methods and properties control how lines are drawn.

CanvasRenderingContext2D.lineWidth (en-US)
Width of lines. Default 1.0
CanvasRenderingContext2D.lineCap (en-US)
Type of endings on the end of lines. Possible values: butt (default), round, square.
CanvasRenderingContext2D.lineJoin (en-US)
Defines the type of corners where two lines meet. Possible values: round, bevel, miter (default).
CanvasRenderingContext2D.miterLimit (en-US)
Miter limit ratio. Default 10.
CanvasRenderingContext2D.getLineDash() (en-US)
Returns the current line dash pattern array containing an even number of non-negative numbers.
CanvasRenderingContext2D.setLineDash() (en-US)
Sets the current line dash pattern.
CanvasRenderingContext2D.lineDashOffset (en-US)
Specifies where to start a dash array on a line.

Text styles

The following properties control how text is laid out.

CanvasRenderingContext2D.font (en-US)
Font setting. Default value 10px sans-serif.
CanvasRenderingContext2D.textAlign (en-US)
Text alignment setting. Possible values: start (default), end, left, right or center.
CanvasRenderingContext2D.textBaseline (en-US)
Baseline alignment setting. Possible values: top, hanging, middle, alphabetic (default), ideographic, bottom.
CanvasRenderingContext2D.direction (en-US)
Directionality. Possible values: ltr, rtl, inherit (default).

Fill and stroke styles

Fill styling is used for colors and styles inside shapes and stroke styling is used for the lines around shapes.

CanvasRenderingContext2D.fillStyle
Color or style to use inside shapes. Default #000 (black).
CanvasRenderingContext2D.strokeStyle (en-US)
Color or style to use for the lines around shapes. Default #000 (black).

Gradients and patterns

CanvasRenderingContext2D.createLinearGradient() (en-US)
Creates a linear gradient along the line given by the coordinates represented by the parameters.
CanvasRenderingContext2D.createRadialGradient() (en-US)
Creates a radial gradient along the line given by the coordinates represented by the parameters.
CanvasRenderingContext2D.createPattern() (en-US)
Creates a pattern using the specified image (a CanvasImageSource (en-US)). It repeats the source in the directions specified by the repetition argument. This method returns a CanvasPattern (en-US).

Shadows

CanvasRenderingContext2D.shadowBlur (en-US)
Specifies the blurring effect. Default 0
CanvasRenderingContext2D.shadowColor (en-US)
Color of the shadow. Default fully-transparent black.
CanvasRenderingContext2D.shadowOffsetX (en-US)
Horizontal distance the shadow will be offset. Default 0.
CanvasRenderingContext2D.shadowOffsetY (en-US)
Vertical distance the shadow will be offset. Default 0.

Paths

The following methods can be used to manipulate paths of objects.

CanvasRenderingContext2D.beginPath() (en-US)
Starts a new path by emptying the list of sub-paths. Call this method when you want to create a new path.
CanvasRenderingContext2D.closePath() (en-US)
Causes the point of the pen to move back to the start of the current sub-path. It tries to draw a straight line from the current point to the start. If the shape has already been closed or has only one point, this function does nothing.
CanvasRenderingContext2D.moveTo() (en-US)
Moves the starting point of a new sub-path to the (x, y) coordinates.
CanvasRenderingContext2D.lineTo() (en-US)
Connects the last point in the subpath to the x, y coordinates with a straight line.
CanvasRenderingContext2D.bezierCurveTo() (en-US)
Adds a cubic Bézier curve to the path. It requires three points. The first two points are control points and the third one is the end point. The starting point is the last point in the current path, which can be changed using moveTo() before creating the Bézier curve.
CanvasRenderingContext2D.quadraticCurveTo() (en-US)
Adds a quadratic Bézier curve to the current path.
CanvasRenderingContext2D.arc() (en-US)
Adds an arc to the path which is centered at (x, y) position with radius r starting at startAngle and ending at endAngle going in the given direction by anticlockwise (defaulting to clockwise).
CanvasRenderingContext2D.arcTo() (en-US)
Adds an arc to the path with the given control points and radius, connected to the previous point by a straight line.
CanvasRenderingContext2D.ellipse() (en-US) This is an experimental API that should not be used in production code.
Adds an ellipse to the path which is centered at (x, y) position with the radii radiusX and radiusY starting at startAngle and ending at endAngle going in the given direction by anticlockwise (defaulting to clockwise).
CanvasRenderingContext2D.rect() (en-US)
Creates a path for a rectangle at position (x, y) with a size that is determined by width and height.

Drawing paths

CanvasRenderingContext2D.fill() (en-US)
Fills the subpaths with the current fill style.
CanvasRenderingContext2D.stroke() (en-US)
Strokes the subpaths with the current stroke style.
CanvasRenderingContext2D.drawFocusIfNeeded() (en-US)
If a given element is focused, this method draws a focus ring around the current path.
CanvasRenderingContext2D.scrollPathIntoView() (en-US)
Scrolls the current path or a given path into the view.
CanvasRenderingContext2D.clip() (en-US)
Creates a clipping path from the current sub-paths. Everything drawn after clip() is called appears inside the clipping path only. For an example, see Clipping paths in the Canvas tutorial.
CanvasRenderingContext2D.isPointInPath()
Reports whether or not the specified point is contained in the current path.
CanvasRenderingContext2D.isPointInStroke() (en-US)
Reports whether or not the specified point is inside the area contained by the stroking of a path.

Transformations

Objects in the CanvasRenderingContext2D rendering context have a current transformation matrix and methods to manipulate it. The transformation matrix is applied when creating the current default path, painting text, shapes and Path2D (en-US) objects. The methods listed below remain for historical and compatibility reasons as SVGMatrix (en-US) objects are used in most parts of the API nowadays and will be used in the future instead.

CanvasRenderingContext2D.currentTransform (en-US)
Current transformation matrix (SVGMatrix (en-US) object).
CanvasRenderingContext2D.rotate() (en-US)
Adds a rotation to the transformation matrix. The angle argument represents a clockwise rotation angle and is expressed in radians.
CanvasRenderingContext2D.scale() (en-US)
Adds a scaling transformation to the canvas units by x horizontally and by y vertically.
CanvasRenderingContext2D.translate() (en-US)
Adds a translation transformation by moving the canvas and its origin x horzontally and y vertically on the grid.
CanvasRenderingContext2D.transform() (en-US)
Multiplies the current transformation matrix with the matrix described by its arguments.
CanvasRenderingContext2D.setTransform() (en-US)
Resets the current transform to the identity matrix, and then invokes the transform() method with the same arguments.
CanvasRenderingContext2D.resetTransform() (en-US) This is an experimental API that should not be used in production code.
Resets the current transform by the identity matrix.

Compositing

CanvasRenderingContext2D.globalAlpha (en-US)
Alpha value that is applied to shapes and images before they are composited onto the canvas. Default 1.0 (opaque).
CanvasRenderingContext2D.globalCompositeOperation (en-US)
With globalAlpha applied this sets how shapes and images are drawn onto the existing bitmap.

Drawing images

CanvasRenderingContext2D.drawImage() (en-US)
Draws the specified image. This method is available in multiple formats, providing a great deal of flexibility in its use.

Pixel manipulation

See also the ImageData (en-US) object.

CanvasRenderingContext2D.createImageData() (en-US)
Creates a new, blank ImageData (en-US) object with the specified dimensions. All of the pixels in the new object are transparent black.
CanvasRenderingContext2D.getImageData() (en-US)
Returns an ImageData (en-US) object representing the underlying pixel data for the area of the canvas denoted by the rectangle which starts at (sx, sy) and has an sw width and sh height.
CanvasRenderingContext2D.putImageData() (en-US)
Paints data from the given ImageData (en-US) object onto the bitmap. If a dirty rectangle is provided, only the pixels from that rectangle are painted.

Image smoothing

CanvasRenderingContext2D.imageSmoothingEnabled (en-US) This is an experimental API that should not be used in production code.
Image smoothing mode; if disabled, images will not be smoothed if scaled.

The canvas state

The CanvasRenderingContext2D rendering context contains a variety of drawing style states (attributes for line styles, fill styles, shadow styles, text styles). The following methods help you to work with that state:

CanvasRenderingContext2D.save() (en-US)
Saves the current drawing style state using a stack so you can revert any change you make to it using restore().
CanvasRenderingContext2D.restore() (en-US)
Restores the drawing style state to the last element on the 'state stack' saved by save().
CanvasRenderingContext2D.canvas
A read-only back-reference to the HTMLCanvasElement. Might be null if it is not associated with a <canvas> element.

Hit regions

CanvasRenderingContext2D.addHitRegion() (en-US) This is an experimental API that should not be used in production code.
Adds a hit region to the canvas.
CanvasRenderingContext2D.removeHitRegion() (en-US) This is an experimental API that should not be used in production code.
Removes the hit region with the specified id from the canvas.
CanvasRenderingContext2D.clearHitRegions() (en-US) This is an experimental API that should not be used in production code.
Removes all hit regions from the canvas.

Non-standard APIs

Most of these APIs are deprecated and will be removed in the future.

This API has not been standardized. CanvasRenderingContext2D.clearShadow()
Removes all shadow settings like CanvasRenderingContext2D.shadowColor (en-US) and CanvasRenderingContext2D.shadowBlur (en-US).
This API has not been standardized. CanvasRenderingContext2D.drawImageFromRect()
This is redundant with an equivalent overload of drawImage.
This API has not been standardized. CanvasRenderingContext2D.setAlpha()
Use CanvasRenderingContext2D.globalAlpha (en-US) instead.
This API has not been standardized. CanvasRenderingContext2D.setCompositeOperation()
Use CanvasRenderingContext2D.globalCompositeOperation (en-US) instead.
This API has not been standardized. CanvasRenderingContext2D.setLineWidth()
Use CanvasRenderingContext2D.lineWidth (en-US) instead.
This API has not been standardized. CanvasRenderingContext2D.setLineJoin()
Use CanvasRenderingContext2D.lineJoin (en-US) instead.
This API has not been standardized. CanvasRenderingContext2D.setLineCap()
Use CanvasRenderingContext2D.lineCap (en-US) instead.
This API has not been standardized. CanvasRenderingContext2D.setMiterLimit()
Use CanvasRenderingContext2D.miterLimit (en-US) instead.
This API has not been standardized. CanvasRenderingContext2D.setStrokeColor()
Use CanvasRenderingContext2D.strokeStyle (en-US) instead.
This API has not been standardized. CanvasRenderingContext2D.setFillColor()
Use CanvasRenderingContext2D.fillStyle instead.
This API has not been standardized. CanvasRenderingContext2D.setShadow()
Use CanvasRenderingContext2D.shadowColor (en-US) and CanvasRenderingContext2D.shadowBlur (en-US) instead.
This API has not been standardized. CanvasRenderingContext2D.webkitLineDash
Use CanvasRenderingContext2D.getLineDash() (en-US) and CanvasRenderingContext2D.setLineDash() (en-US) instead.
This API has not been standardized. CanvasRenderingContext2D.webkitLineDashOffset
Use CanvasRenderingContext2D.lineDashOffset (en-US) instead.
This API has not been standardized. CanvasRenderingContext2D.webkitImageSmoothingEnabled
Use CanvasRenderingContext2D.imageSmoothingEnabled (en-US) instead.
This API has not been standardized. CanvasRenderingContext2D.getContextAttributes()
Inspired by the same WebGLRenderingContext method it returns an Canvas2DContextAttributes object that contains the attributes "storage" to indicate which storage is used ("persistent" by default) and the attribute "alpha" (true by default) to indicate that transparency is used in the canvas.
This API has not been standardized. CanvasRenderingContext2D.isContextLost()
Inspired by the same WebGLRenderingContext method it returns true if the Canvas context has been lost, or false if not.

WebKit only

This API has not been standardized. CanvasRenderingContext2D.webkitBackingStorePixelRatio
The backing store size in relation to the canvas element. See High DPI Canvas.
This API has not been standardized. CanvasRenderingContext2D.webkitGetImageDataHD
Intended for HD backing stores, but removed from canvas specifications.
This API has not been standardized. CanvasRenderingContext2D.webkitPutImageDataHD
Intended for HD backing stores, but removed from canvas specifications.

Gecko only

This API has not been standardized. CanvasRenderingContext2D.filter (en-US)
CSS and SVG filters as Canvas APIs. Likely to be standardized in a new version of the specification.

Prefixed APIs

This API has not been standardized. CanvasRenderingContext2D.mozCurrentTransform
Sets or gets the current transformation matrix, see CanvasRenderingContext2D.currentTransform (en-US)
This API has not been standardized. CanvasRenderingContext2D.mozCurrentTransformInverse
Sets or gets the current inversed transformation matrix. 
This API has not been standardized. CanvasRenderingContext2D.mozFillRule
The fill rule to use. This must be one of evenodd or nonzero (default).
This API has not been standardized. CanvasRenderingContext2D.mozImageSmoothingEnabled
See CanvasRenderingContext2D.imageSmoothingEnabled (en-US).
This API has not been standardized. This deprecated API should no longer be used, but will probably still work. CanvasRenderingContext2D.mozDash
An array which specifies the lengths of alternating dashes and gaps . Use CanvasRenderingContext2D.getLineDash() (en-US) and CanvasRenderingContext2D.setLineDash() (en-US) instead.
This API has not been standardized. This deprecated API should no longer be used, but will probably still work. CanvasRenderingContext2D.mozDashOffset
Specifies where to start a dash array on a line. . Use CanvasRenderingContext2D.lineDashOffset (en-US) instead.
This API has not been standardized. This deprecated API should no longer be used, but will probably still work. CanvasRenderingContext2D.mozTextStyle
Introduced in in Gecko 1.9, deprecated in favor of the CanvasRenderingContext2D.font (en-US) property.
This API has not been standardized. This is an obsolete API and is no longer guaranteed to work. CanvasRenderingContext2D.mozDrawText()
This method was introduced in Gecko 1.9 and is removed starting with Gecko 7.0. Use CanvasRenderingContext2D.strokeText() (en-US) or CanvasRenderingContext2D.fillText() (en-US) instead.
This API has not been standardized. This is an obsolete API and is no longer guaranteed to work. CanvasRenderingContext2D.mozMeasureText()
This method was introduced in Gecko 1.9 and is unimplemented starting with Gecko 7.0. Use CanvasRenderingContext2D.measureText() (en-US) instead.
This API has not been standardized. This is an obsolete API and is no longer guaranteed to work. CanvasRenderingContext2D.mozPathText()
This method was introduced in Gecko 1.9 and is removed starting with Gecko 7.0.
This API has not been standardized. This is an obsolete API and is no longer guaranteed to work. CanvasRenderingContext2D.mozTextAlongPath()
This method was introduced in Gecko 1.9 and is removed starting with Gecko 7.0.

Internal APIs (chrome-context only)

This API has not been standardized. CanvasRenderingContext2D.asyncDrawXULElement()
Renders a region of a XUL element into the canvas.
This API has not been standardized. CanvasRenderingContext2D.drawWindow() (en-US)
Renders a region of a window into the canvas. The contents of the window's viewport are rendered, ignoring viewport clipping and scrolling.
This API has not been standardized. CanvasRenderingContext2D.demote()
This causes a context that is currently using a hardware-accelerated backend to fallback to a software one. All state should be preserved.

Internet Explorer

This API has not been standardized. CanvasRenderingContext2D.msFillRule
The fill rule to use. This must be one of evenodd or nonzero (default).

Specifications

Specification Status Comment
HTML Living Standard
The definition of 'CanvasRenderingContext2D' in that specification.
Living Standard  

Browser compatibility

We're converting our compatibility data into a machine-readable JSON format. This compatibility table still uses the old format, because we haven't yet converted the data it contains. Find out how you can help! (en-US)
Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 1 1.5 (1.8) 9 9 2
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support ? ? ? ? ? ?

Compatibility notes

  • Starting with Gecko 5.0 (Firefox 5.0 / Thunderbird 5.0 / SeaMonkey 2.2), specifying invalid values are now silently ignored for the following methods and properties: translate(), transform(), rotate(), scale(), rect(), clearRect(), fillRect(), strokeRect(), lineTo(), moveTo(), quadraticCurveTo(), arc(), shadowOffsetX, shadowOffsetYshadowBlur.

See also