Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
QrcodeVue
✓ import QrcodeVue from 'qrcode.vue'
✗ const QrcodeVue = require('qrcode.vue')
QrcodeVue is the default export for the primary component. For Vue 3, ensure you are using qrcode.vue v3.x. CommonJS require() syntax is not supported in modern Vue 3 projects.
{ QrcodeCanvas, QrcodeSvg }
✓ import { QrcodeCanvas, QrcodeSvg } from 'qrcode.vue'
✗ import QrcodeCanvas from 'qrcode.vue'
QrcodeCanvas and QrcodeSvg are named exports allowing direct rendering to canvas or SVG elements, respectively. They are not default exports.
Types (Level, RenderAs, ImageSettings)
✓ import type { Level, RenderAs, ImageSettings } from 'qrcode.vue'
✗ import { Level, RenderAs } from 'qrcode.vue'
When importing types in TypeScript, use 'import type' to ensure they are stripped from the compiled JavaScript, preventing runtime errors or unnecessary bundle size increases. These types define valid prop values.
This quickstart demonstrates how to use qrcode.vue with Vue 3's Composition API, configuring common props like value, error correction level, rendering type (SVG), colors, margins, image settings for a logo, and gradient fills.
import { ref } from 'vue'
import QrcodeVue from 'qrcode.vue'
import type { Level, RenderAs, GradientType, ImageSettings } from 'qrcode.vue'
// This code snippet demonstrates how to set up reactive data and import necessary
// components and types for qrcode.vue within a Vue 3 Composition API setup.
// In a real Vue component, these refs would be used in the <template> section.
const value = ref('https://checklist.day/qrcode-example')
const level = ref<Level>('H') // High error correction level
const renderAs = ref<RenderAs>('svg') // Render as SVG for scalability
const constbackground = ref('#ffffff')
const foreground = ref('#000000')
const margin = ref(4)
const imageSettings = ref<ImageSettings>({
src: 'https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6/svgs/solid/qrcode.svg', // Example logo
width: 40,
height: 40,
excavate: true, // Excavate QR code behind the image for clarity
borderRadius: 8 // Apply border radius to the logo
})
const gradient = ref(true)
const gradientType = ref<GradientType>('linear')
const gradientStartColor = ref('#10b981') // Emerald green
const gradientEndColor = ref('#3b82f6') // Blue
// Usage in a Vue template (example):
// <template>
// <qrcode-vue
// :value="value"
// :level="level"
// :render-as="renderAs"
// :background="background"
// :foreground='foreground'
// :margin="margin"
// :gradient="gradient"
// :gradient-type="gradientType"
// :gradient-start-color="gradientStartColor"
// :gradient-end-color="gradientEndColor"
// :image-settings='imageSettings'
// />
// </template>
Debug
Known issues
breakingMajor version incompatibility between Vue 2 and Vue 3. qrcode.vue v1.x is for Vue 2, while v3.x is for Vue 3. Using the wrong version will lead to runtime errors.fixEnsure `qrcode.vue` version matches your Vue.js project's major version. For Vue 3 projects, install `qrcode.vue@^3.0.0`. For Vue 2 projects, stick to `qrcode.vue@^1.0.0`.
affects: >=1.0.0, <3.0.0 (for Vue 2) | >=3.0.0 (for Vue 3)
breakingIn v3.4.0, the underlying QR code generation library was switched from `qr.js` to `nayuki/QR-Code-generator` for performance improvements. While largely compatible, this change might introduce subtle differences in QR code rendering or edge case behavior compared to previous versions.fixTest your QR code outputs thoroughly after upgrading to v3.4.0 or newer to ensure no regressions or unexpected visual changes, especially in complex use cases.
affects: >=3.4.0
gotchaPrior to v3.8.1, when rendering multiple QR codes using `render-as="svg"` on the same page, there was a potential for conflicting SVG element IDs, which could cause accessibility issues or incorrect rendering behavior.fixUpgrade to `qrcode.vue` v3.8.1 or newer to benefit from the fix that ensures unique SVG IDs for multi-instance renderings. If unable to upgrade, consider rendering to `canvas` or manually managing component keys.
affects: >=3.0.0 <3.8.1
gotchaThe `margin` prop, while internally optimized in v3.5.1 to handle string numeric values (e.g., `margin="0"`), is ideally expected as a `number`. Providing non-numeric strings might lead to unexpected behavior.fixAlways bind `margin` as a number using `:margin="0"` (or a variable holding a number) to ensure correct type handling and avoid potential coercion issues.
affects: >=3.0.0
Errors
Common errors & fixes
[Vue warn]: Component provided is not a function or object. Did you forget to import the component from the file?
Attempting to use `qrcode.vue` v1.x (for Vue 2) in a Vue 3 project, or vice-versa, or incorrect import path.
fixVerify that your `qrcode.vue` version matches your Vue.js project's major version. For Vue 3, ensure `qrcode.vue` v3.x is installed. Also, double-check the import statement: `import QrcodeVue from 'qrcode.vue'`.
TypeError: qrcode_vue__WEBPACK_IMPORTED_MODULE_0__.default is not a constructor
Attempting to instantiate `QrcodeVue` using `new QrcodeVue()` with an ES module import, or incorrect default import usage.
fixQrcodeVue is a Vue component, not a class to be instantiated with `new`. Use it directly in your Vue component's `components` option or template: `import QrcodeVue from 'qrcode.vue'; components: { QrcodeVue }`. Property 'ImageSettings' does not exist on type 'typeof import("qrcode.vue")'. Did you mean 'imageSettings'?
Attempting to import `ImageSettings` or other types as a regular named import instead of a type import in TypeScript.
fixWhen importing types, use the `import type` syntax: `import type { Level, RenderAs, ImageSettings } from 'qrcode.vue'`. Audit
Dependencies
vuerequiredPeer dependency required for the Vue component to function. Version 1.x supports Vue 2, while version 3.x supports Vue 3.