THE VIETQR FIELD GUIDE
Documentation
1. Installation
Choose your framework and package manager to get the right install command.
pnpm add @viet-qr/core @viet-qr/react2. Basic Usage (Core)
Use `generateVietQR` to build an EMVCo-compliant payload string, and `parseVietQR` to decode and validate one (yours or a third-party QR).
import { generateVietQR, parseVietQR } from '@viet-qr/core';
const payload = generateVietQR({
bankId: 'VCB',
accountNo: '1122334455',
accountName: 'NGUYEN NGOC A',
amount: 50000,
content: 'Thanh toan don hang',
});
console.log(payload);
// Decode & validate any VietQR string (yours or a third-party one)
const result = parseVietQR(payload);
console.log(result.isValid, result.isDynamic, result.beneficiary);Both functions throw/return a descriptive error on invalid input — e.g. accountNo must be alphanumeric (≤ 50 chars) and amount must be a non-negative integer with at most 13 digits. Omit the amount or use zero for a static QR.
3. Components
The example below follows your selection. The core API is shared across frameworks.
React
If you are using React, we provide a dedicated wrapper component that handles everything from generating the payload to rendering the QR code.
import { VietQR, VietQRButton } from '@viet-qr/react';
import { CompactCard, PayStandee } from '@viet-qr/templates/react';
function PaymentModal() {
return (
<>
{/* Basic QR */}
<VietQR
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
content="Thanh toan don hang"
renderAs="svg"
size={300}
/>
{/* Payment Button with built-in Modal */}
<VietQRButton
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
label="Thanh toán"
/>
{/* Pre-built Templates */}
<CompactCard
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
/>
<PayStandee
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
/>
</>
);
}Need full control over the UI instead? @viet-qr/react also exports a useVietQR hook/composable that returns a reactive { payload, isValid, error } object, so you can render the QR however you like.
Vue
If you are using Vue, we provide a dedicated wrapper component that handles everything from generating the payload to rendering the QR code.
<script setup>
import { VietQR, VietQRButton } from '@viet-qr/vue';
import { CompactCard, PayStandee } from '@viet-qr/templates/vue';
import '@viet-qr/vue/style.css'; // For VietQRButton Modal
</script>
<template>
<!-- Basic QR -->
<VietQR
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
:amount="50000"
content="Thanh toan don hang"
renderAs="svg"
:size="300"
/>
<!-- Payment Button with built-in Modal -->
<VietQRButton
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
:amount="50000"
label="Thanh toán"
/>
<!-- Pre-built Templates -->
<CompactCard
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
:amount="50000"
/>
<PayStandee
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
:amount="50000"
/>
</template>Need full control over the UI instead? @viet-qr/vue also exports a useVietQR hook/composable that returns a reactive { payload, isValid, error } object, so you can render the QR however you like.
Svelte
If you are using Svelte, we provide a dedicated wrapper component that handles everything from generating the payload to rendering the QR code.
<script>
import { VietQR, VietQRButton } from '@viet-qr/svelte';
import { CompactCard, PayStandee } from '@viet-qr/templates/svelte';
</script>
<!-- Basic QR -->
<VietQR
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
content="Thanh toan don hang"
renderAs="svg"
size={300}
/>
<!-- Payment Button with built-in Modal -->
<VietQRButton
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
label="Thanh toán"
/>
<!-- Pre-built Templates -->
<CompactCard
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
/>
<PayStandee
bankId="VCB"
accountNo="1122334455"
accountName="NGUYEN NGOC A"
amount={50000}
/>Need full control over the UI instead? @viet-qr/svelte also exports a useVietQR hook/composable that returns a reactive { payload, isValid, error } object, so you can render the QR however you like.
Note for Svelte 4 users
Since we distribute raw TS code for maximum IDE support, please configure Vite to preprocess it. You can copy the exact configuration files below:
import { defineConfig } from 'vite';
import { svelte } from '@sveltejs/vite-plugin-svelte';
export default defineConfig({
plugins: [svelte()],
optimizeDeps: {
exclude: ['@viet-qr/svelte', '@viet-qr/templates']
}
});import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
export default {
preprocess: vitePreprocess()
};Vanilla JS
If you are using Vanilla JS, we provide a dedicated wrapper component that handles everything from generating the payload to rendering the QR code.
<!-- Include the library via CDN -->
<script src="https://unpkg.com/@viet-qr/templates/dist/elements/index.global.js"></script>
<link rel="stylesheet" href="https://unpkg.com/@viet-qr/templates/dist/styles.css" />
<!-- Basic QR, no card wrapper -->
<viet-qr-basic
bank-id="VCB"
account-no="1122334455"
account-name="NGUYEN NGOC A"
amount="50000"
></viet-qr-basic>
<!-- Pre-built Templates -->
<viet-qr-compact
bank-id="VCB"
account-no="1122334455"
account-name="NGUYEN NGOC A"
amount="50000"
></viet-qr-compact>
<viet-qr-standee
bank-id="VCB"
account-no="1122334455"
account-name="NGUYEN NGOC A"
amount="50000"
></viet-qr-standee>
<!-- Payment Button with built-in Modal -->
<viet-qr-button
bank-id="VCB"
account-no="1122334455"
account-name="NGUYEN NGOC A"
amount="50000"
label="Thanh toán"
></viet-qr-button>4. API Reference
Looking for detailed functions, props, and types? Check out the complete VietQR API Reference.
API Reference