React component for scalable canvases backed by SVGs.
Oftentimes one would want to import an SVG into an HTML canvas, in order to do further raster processing with it. In React, this can be easily accomplished with refs and lifecycle methods that run after the DOM is updated. However, the drawback with such an approach is that since canvas operates upon bitmap, the key benefit of using SVG – the ability to scale according to device pixel density – is gone.
This React component solves the scaling problem, first by scaling the canvas
using devicePixelRatio
when the component is mounted initially, and second
by listening for pixel ratio changes using matchMedia
and resolution
CSS media query (with dppx
units), in order to redraw the canvas
automatically when a change is detected (e.g. when the user zooms in, or when
the window is moved to another display).
The following explicitly declared props apply to the underlying canvas. If you pass a prop that is not documented below, it will be passed along to the canvas anyway.
width
,height
Number
: Base dimensions of the canvas. The actual canvas size will be scaled according todevicePixelRatio
. Default:300
×150
.imageSmoothingEnabled
Boolean
: Whether or not image smoothing is to be enabled when rendering SVG image to the canvas. This is directly mapped toCanvasRenderingContext2D
'simageSmoothingEnabled
parameter. Default:true
.imageSmoothingQuality
String
: Quality of image smoothing when rendering SVG image to the canvas. This is directly mapped toCanvasRenderingContext2D
'simageSmoothingQuality
parameter. Default:'high'
.
These props control behaviors of this React component.
autoScale
Boolean
: Listen for device pixel ratio changes and automatically rescale the canvas to accomodate. Default:true
.drawDimensions
Array<Number>
: Unscaled dimensions passed todrawImage
, as an array of numbers. This component will automatically scale the actual dimensions used based on the current pixel ratio. The two-argument signature fordrawImage
is not supported as it does not support scaling. Default:[0, 0, width, height]
, wherewidth
andheight
correspond to the props which fills the entire canvas.predraw
Function
: This function is called every time a redraw is requested, before the SVG has already been drawn. It has the signature(ctx, scaleFactor)
wherectx
is aCanvasRenderingContext2D
associated with the canvas, andscaleFactor
is aNumber
representing the requested scale.draw
Function
: This function is called every time a redraw is requested, after the SVG has already been drawn. It has the signature(ctx, scaleFactor)
wherectx
is aCanvasRenderingContext2D
associated with the canvas, andscaleFactor
is aNumber
representing the requested scale. Here is where you can do extra processing on the SVG canvas.onRatioChange
Function
: This function is called when the scale factor for the canvas changes due to changing device pixel ratio. It has the signature(scaleFactor)
, wherescaleFactor
is equal to the current value ofdevicePixelRatio
.
The SVG used in rendering can be supplied in two ways. If both are specified,
svgString
takes precedence. If neither is specified, an empty SVG is used as
the default.
svgString
String
: SVG to be rendered on the canvas as a string. This is the preferred method when the SVG is entirely static.svgElement
ReactElement
: SVG to be rendered on the canvas as a React element.
If you get a ref of the HybridCanvas
element, you will be able to access the
following properties and methods.
canvas
HTMLCanvasElement
: The underlying canvas DOM object.ctx
CanvasRenderingContext2D
: The 2D rendering context associated withcanvas
.
toBlob
(scaleFactor: Number) → Promise<Blob>
: Convert the canvas to an image Blob, scaled at the providedscaleFactor
. This uses thetoBlob
method of anHTMLCanvasElement
, but since the requestedscaleFactor
may be different from the actual one of thecanvas
property, a temporary canvas may be used.