Skip to content

@qrcodesdk/svelte

Svelte components that render QR codes as inline SVG, as PNG, WebP, GIF, or JPEG Image elements, or as Canvas elements.

Terminal window
npm install @qrcodesdk/svelte

Import a component in a Svelte component:

<script lang="ts">
import {QRCodeSVG, type QRCodeSVGOptions} from '@qrcodesdk/svelte';
const options: QRCodeSVGOptions = {
accessibility: {ariaLabel: 'Scan to open qrcodesdk.dev'},
};
</script>
<figure>
<QRCodeSVG payload="https://qrcodesdk.dev" {options} />
<figcaption>
Scan the code or open <a href="https://qrcodesdk.dev">qrcodesdk.dev</a>
</figcaption>
</figure>
  • ariaLabel names the QR code for screen readers. The link gives everyone another way to reach the destination.
  • Without accessibility options, the QR code is decorative and hidden from assistive technology. Leave it unlabeled only when nearby content, such as this link, already explains it.
  • QRCodePNG, QRCodeWebP, QRCodeGIF, QRCodeJPEG, and QRCodeCanvas take the same payload and options props. Image components also accept accessibility.alt.
@qrcodesdk/svelte Svelte
0.x.x ^5.0.0

Each output format has its own component. Your bundle only includes the encoders of the components you import.

ComponentOutputDownload support
QRCodeSVGInline SVG elementSVG
QRCodePNGPNG-backed <img>PNG
QRCodeWebPWebP-backed <img>WebP
QRCodeGIFGIF-backed <img>GIF
QRCodeJPEGJPEG-backed <img>JPEG
QRCodeCanvas<canvas> elementNone

Component props

PropTypeDescription
payloadstring | numberRequired QR code payload.
optionsComponent-specific optionsOptional matrix options and renderer options, such as QRCodeSVGOptions for QRCodeSVG.
class, style, other <div> attributesHTMLAttributes<HTMLDivElement>Spread onto the wrapper <div> that contains the output element. children is not accepted.
bind:thisQRCodeDownloadHandleExposes download(filename?) on every component except QRCodeCanvas, which exports nothing.
  • QRCodePNG uses the browser’s native PNG encoder.
  • QRCodeWebP uses a lossless encoder bundled in the SDK. It also works in Safari and usually produces the smallest file.
  • QRCodeGIF is limited to 256 colors and on-or-off transparency. Prefer PNG or WebP for transparent backgrounds and photographic center images.
  • QRCodeJPEG is lossy and has no transparency. It blends transparent pixels onto a white matte by default. Its quality option ranges from 1 to 100 and defaults to 92. Use it only when a destination requires JPEG.

See Image element renderers for details.

<script lang="ts">
import {QRCodeSVG, type QRCodeSVGOptions} from '@qrcodesdk/svelte';
const options: QRCodeSVGOptions = {
style: {moduleSize: 8, quietZone: 4},
accessibility: {ariaLabel: 'Scan to open qrcodesdk.dev'},
};
</script>
<QRCodeSVG payload="https://qrcodesdk.dev" {options} />
<script lang="ts">
import {QRCodePNG, type QRCodePNGImageOptions} from '@qrcodesdk/svelte';
const options: QRCodePNGImageOptions = {
style: {moduleSize: 8, quietZone: 4},
accessibility: {alt: 'QR code: scan to open qrcodesdk.dev'},
};
</script>
<QRCodePNG payload="https://qrcodesdk.dev" {options} />
<script lang="ts">
import {QRCodeWebP, type QRCodeWebPImageOptions} from '@qrcodesdk/svelte';
const options: QRCodeWebPImageOptions = {
style: {moduleSize: 8, quietZone: 4},
accessibility: {alt: 'QR code: scan to open qrcodesdk.dev'},
};
</script>
<QRCodeWebP payload="https://qrcodesdk.dev" {options} />
<script lang="ts">
import {QRCodeGIF, type QRCodeGIFImageOptions} from '@qrcodesdk/svelte';
const options: QRCodeGIFImageOptions = {
style: {moduleSize: 8, quietZone: 4},
accessibility: {alt: 'QR code: scan to open qrcodesdk.dev'},
};
</script>
<QRCodeGIF payload="https://qrcodesdk.dev" {options} />
<script lang="ts">
import {QRCodeJPEG, type QRCodeJPEGImageOptions} from '@qrcodesdk/svelte';
const options: QRCodeJPEGImageOptions = {
style: {moduleSize: 8, quietZone: 4},
quality: 90,
accessibility: {alt: 'QR code: scan to open qrcodesdk.dev'},
};
</script>
<QRCodeJPEG payload="https://qrcodesdk.dev" {options} />
<script lang="ts">
import {QRCodeCanvas, type QRCodeCanvasOptions} from '@qrcodesdk/svelte';
const options: QRCodeCanvasOptions = {
style: {moduleSize: 8, quietZone: 4},
accessibility: {ariaLabel: 'Scan to open qrcodesdk.dev'},
};
</script>
<QRCodeCanvas payload="https://qrcodesdk.dev" {options} />
<script lang="ts">
import {
QRCodePNG,
type QRCodeDownloadHandle,
type QRCodePNGImageOptions,
} from '@qrcodesdk/svelte';
let qrcode: QRCodeDownloadHandle | undefined;
const options: QRCodePNGImageOptions = {
accessibility: {alt: 'QR code: scan to open qrcodesdk.dev'},
};
</script>
<QRCodePNG bind:this={qrcode} payload="https://qrcodesdk.dev" {options} />
<button type="button" onclick={() => qrcode?.download('qrcodesdk')}>Download PNG</button>

For PNG, WebP, GIF, JPEG, and Canvas components:

  1. Load and decode a browser image.
  2. Store it in $state.
  3. Pass canvasCenterImage(image) as options.centerImage.
  4. Render the component only after the image is ready.

QRCodeSVG takes svgCenterImage() with an embedded data URL instead. See Add a center image for the complete Svelte example.

Every component except QRCodeCanvas exposes download(filename?). Get it through bind:this. The method appends the file extension when needed.

See Download or save for a complete Svelte example. For manual downloads, see Export a canvas manually.

  • QRCodeSVG produces runtime-neutral SVG and renders on the server.
  • QRCodePNG, QRCodeWebP, QRCodeGIF, QRCodeJPEG, and QRCodeCanvas need browser DOM and Canvas APIs. On the server, they render an empty wrapper and skip downloads. They fill the wrapper after mounting in the browser.

The options prop groups encoding settings under matrix. Renderer settings, such as style, accessibility, and centerImage, sit next to it:

import {type QRCodeSVGOptions, circle, finder, rounded} from '@qrcodesdk/svelte';
const options: QRCodeSVGOptions = {
matrix: {errorCorrectionLevel: 'H'},
style: {moduleSize: 8, quietZone: 4, modules: rounded(), finder: finder({center: circle()})},
accessibility: {ariaLabel: 'Scan to open qrcodesdk.dev'},
};

Each component has its own options type:

Component Options type Extra options
QRCodeSVG QRCodeSVGOptions None
QRCodePNG QRCodePNGImageOptions None
QRCodeWebP QRCodeWebPImageOptions None
QRCodeGIF QRCodeGIFImageOptions transparency.threshold
QRCodeJPEG QRCodeJPEGImageOptions quality, transparency.matte
QRCodeCanvas QRCodeCanvasOptions None

Learn more about each group:

Import payload helpers, such as wifiPayload(), from @qrcodesdk/svelte. QRCodeError comes from @qrcodesdk/core. To use it, add Core to the project.

Mixed-mode segmentation is opt-in. Import automaticSegmenter from @qrcodesdk/svelte and pass it as matrix.segmenter:

import {type QRCodeSVGOptions, automaticSegmenter} from '@qrcodesdk/svelte';
const options: QRCodeSVGOptions = {matrix: {mode: 'auto', segmenter: automaticSegmenter}};

Components derive their renderer from options. They render the QR code again when:

  • options is reassigned;
  • state read by the options changes, such as a property of a $state object or a value used in an inline options={{...}} expression.

Unrelated parent updates do not render it again. Changing a property of a plain object that is not $state has no effect.

Components throw QRCodeError for invalid payloads and options.

Component Where it throws
QRCodeSVG During rendering
Image and Canvas components In an $effect

To handle them:

  • With Svelte 5.3 or newer, wrap the component in a <svelte:boundary> to catch errors in the browser. Give it a failed snippet or an onerror handler. Without one, Svelte rethrows the error. Svelte 5.0 to 5.2 have no <svelte:boundary>.
  • Boundaries have no effect during server-side rendering by default. A throwing QRCodeSVG fails the whole server render.
  • Without a boundary, and for server-side rendering, validate user-controlled payloads before rendering.
  • Wrap downloads called from an event handler in your own try/catch.
<svelte:boundary onerror={(error) => console.error(error)}>
<QRCodeSVG payload="https://qrcodesdk.dev" />
{#snippet failed()}
<p>This QR code could not be rendered.</p>
{/snippet}
</svelte:boundary>

See Check errors from framework packages.

import {
type QRCodeAlignmentCenterShape,
type QRCodeAlignmentOptions,
type QRCodeAlignmentRingShape,
type QRCodeAlignmentStyle,
type QRCodeBaseProps,
QRCodeCanvas,
type QRCodeCanvasAccessibilityOptions,
type QRCodeCanvasCenterImage,
type QRCodeCanvasOptions,
type QRCodeCanvasProps,
type QRCodeCenterImageLayout,
type QRCodeCircleShapeOptions,
type QRCodeColor,
type QRCodeDataImageURL,
type QRCodeDownloadHandle,
type QRCodeEncodingMode,
type QRCodeErrorCorrectionLevel,
type QRCodeFinderCenterShape,
type QRCodeFinderOptions,
type QRCodeFinderRingShape,
type QRCodeFinderStyle,
QRCodeGIF,
type QRCodeGIFImageOptions,
type QRCodeGIFProps,
type QRCodeImageAccessibilityOptions,
QRCodeJPEG,
type QRCodeJPEGImageOptions,
type QRCodeJPEGProps,
type QRCodeKanji,
type QRCodeMask,
type QRCodeMatrixOptions,
type QRCodeMode,
type QRCodeModulePattern,
type QRCodeModuleShape,
QRCodePNG,
type QRCodePNGImageOptions,
type QRCodePNGProps,
type QRCodePayload,
type QRCodeRoundedShapeOptions,
QRCodeSVG,
type QRCodeSVGAccessibilityOptions,
type QRCodeSVGCenterImage,
type QRCodeSVGOptions,
type QRCodeSVGProps,
type QRCodeSegment,
type QRCodeSegmenter,
type QRCodeSegmenterOptions,
type QRCodeShape,
type QRCodeShapePath,
type QRCodeShapePiece,
type QRCodeVersion,
type QRCodeVisualStyle,
QRCodeWebP,
type QRCodeWebPImageOptions,
type QRCodeWebPProps,
alignment,
automaticSegmenter,
canvasCenterImage,
circle,
customShape,
diagonal,
finder,
kanji,
rounded,
svgCenterImage,
} from '@qrcodesdk/svelte';

@qrcodesdk/svelte

Version
v0.0.6
Downloads
846/mo
Install size
795.2 kB
Bundled size
25.9 kB
Works with
Works with Google ChromeWorks with FirefoxWorks with Safari

Support QRCodeSDK

If you find QRCodeSDK useful, please consider sponsoring the project!