SVG string renderer
When to use
Section titled “When to use”Use QRCodeSVGRenderer for scalable output in web pages, print, generated assets, or HTTP
responses. It is the recommended default whenever the destination accepts SVG.
- Output stays sharp at every size.
- It needs no browser or Node.js APIs.
For email, render a PNG with the PNG Buffer renderer instead. SVG support varies between email clients.
Minimal example
Section titled “Minimal example”import {QRCodeSVGRenderer, qrcode} from '@qrcodesdk/core';
const svg = qrcode('https://qrcodesdk.dev').render(QRCodeSVGRenderer());To insert the SVG into a page, see Render QR codes in the browser.
Styled example
Section titled “Styled example”import {QRCodeSVGRenderer, qrcode} from '@qrcodesdk/core';import {circle, finder, rounded} from '@qrcodesdk/core/style';
const svg = qrcode('https://qrcodesdk.dev').render( QRCodeSVGRenderer({ style: { moduleSize: 8, foreground: '#0f172a', modules: rounded(), finder: finder({ring: rounded({radius: 1}), center: circle(), color: '#e11d48'}), }, }),);See Customize appearance for every color, shape, and finder option.
Return value
Section titled “Return value”The renderer returns a complete SVG string:
- It has an explicit
width,height, andviewBox. - It draws the background and one even-odd
<path>per color. RGBA colors setfill-opacity. - With only square modules and patterns, it sets
shape-rendering="crispEdges". Shaped styles, including custom shapes, omit that hint. - A center image is an
<image>element drawn after the modules. Cleared modules are left out of the paths.
Accessibility depends on the labels you pass:
- A non-blank
ariaLabelortitleaddsrole="img". - Without either, the SVG is decorative. It gets
aria-hidden="true", so assistive technology skips it.
Label every QR code unless nearby content already explains it.
Options
Section titled “Options”| Option | Type | Default | Effect |
|---|---|---|---|
style |
QRCodeVisualStyle |
shared defaults | Applies graphical dimensions, colors, and shapes |
accessibility.ariaLabel |
string |
undefined |
Sets aria-label and role="img" |
accessibility.title |
string |
undefined |
Adds a child <title> and role="img" |
centerImage |
QRCodeSVGCenterImage |
undefined |
Embeds a center image from svgCenterImage() |
QRCodeSVGRendererOptions accepts only these keys.
Center image
Section titled “Center image”Create the centerImage value with svgCenterImage(source, layout?) from @qrcodesdk/core:
import {QRCodeSVGRenderer, qrcode, svgCenterImage} from '@qrcodesdk/core';
// A red circle with a viewBox, so it scales to the image box.const logo = 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMCAxMCI+PGNpcmNsZSBjeD0iNSIgY3k9IjUiIHI9IjUiIGZpbGw9IiNlMTFkNDgiLz48L3N2Zz4=';const svg = qrcode('https://qrcodesdk.dev') .errorCorrection('H') .render(QRCodeSVGRenderer({centerImage: svgCenterImage(logo, {size: 0.3})}));| Parameter | Type | Default | Effect |
|---|---|---|---|
source |
QRCodeDataImageURL |
required | Embeds a prepared data:image/... URL |
layout.size |
number |
0.3 |
Square image box as a fraction of the shorter matrix side |
layout.aspectRatio |
number |
1 |
Source width divided by height, used to fit the cutout |
layout.padding |
number |
1 |
Cleared border around the image, in modules |
layout.clearBackground |
boolean |
true |
Removes every module the image or its padding touches |
Constraints
Section titled “Constraints”- Escaping. The renderer escapes label text and image URL attributes. The payload becomes QR modules, never HTML. Still, never concatenate unescaped user input into the returned SVG.
- Center image source.
svgCenterImage()requires a non-empty embedded image data URL. It throwsINVALID_IMAGE_SOURCEotherwise, and never reads paths or fetches remote URLs. - Uploaded images.
svgCenterImage()checks the URL format, not the embedded image. Validate uploads before you create the data URL. - Center image layout.
sizemust be finite, greater than0, and at most1.paddingmust be finite and non-negative.aspectRatiomust be finite and positive.svgCenterImage()validates these values when it is called. - Labels.
ariaLabelandtitlemust contain only characters that XML allows. Control characters other than tab, line feed, and carriage return throwQRCodeErrorwith codeINVALID_OPTIONSwhenQRCodeSVGRenderer()is called.details.fieldisaccessibility.ariaLabeloraccessibility.title. - No
alt. SVG does not acceptaccessibility.alt. UseariaLabeland, optionally,title. - Option checks. TypeScript rejects unknown keys and checks that
centerImagecomes fromsvgCenterImage(). The renderer does not repeat these checks at runtime. - Option copies.
QRCodeSVGRenderer()copies option values when it is called. - Runtimes. The renderer supports the same runtimes as Core.
Related guides
Section titled “Related guides”- Customize appearance for colors, module shapes, quiet zones, labels, and scan reliability.
- Add a center image for preparing an SVG center image source.
- Render QR codes in the browser for DOM insertion and layout.
- Download or save for files and browser downloads.
- Serve a QR code for HTTP responses.
- Errors for every
QRCodeErrorcode.
Related pages
Section titled “Related pages”Support QRCodeSDK
If you find QRCodeSDK useful, please consider sponsoring the project!