📱 A simple and powerful library for generating QR code business cards with vCard support, custom design options, and multiple export formats.
Perfect for networking events, digital business cards, and contact sharing. When someone scans your QR code, their phone automatically recognizes it as a contact card and prompts them to save your information.
- vCard 3.0 Support - Standard format that works with all smartphones (iPhone, Android, etc.)
- Custom Design - Add your logo, choose custom colors, and adjust QR code appearance
- Multiple Export Formats - Download as PNG, SVG, or PDF
- TypeScript Support - Full type definitions for better development experience
- Works Everywhere - Use in Node.js or browser environments
- Easy to Use - Simple API that gets you started in minutes
Installation via package managers (npm, pip, or others) may be added in the future. For now, please clone this repository and use it directly from the source code.
Here's a simple example to get you started:
import { QRBusinessCard } from 'qr-business-card-generator';
// Create a generator instance
const generator = new QRBusinessCard();
// Prepare your business card data
const myCard = {
firstName: 'John',
lastName: 'Doe',
email: 'john@example.com',
phone: '+1234567890',
organization: 'Acme Inc',
jobTitle: 'Software Developer',
website: 'https://johndoe.com',
social: {
linkedin: 'linkedin.com/in/johndoe',
github: 'github.com/johndoe'
}
};
// Generate the QR code
const qrCode = await generator.generate(myCard, {
size: 400
});
// The QR code is now a data URI (data:image/png;base64,...)
// You can use it directly in an <img> tag or export itThat's it! You now have a QR code that contains all your contact information in vCard format.
The most basic usage requires just a first name:
const generator = new QRBusinessCard();
const simpleCard = {
firstName: 'Jane',
email: 'jane@example.com'
};
const qrCode = await generator.generate(simpleCard);
// Use qrCode in your applicationYou can include as much or as little information as you want:
const completeCard = {
// Required
firstName: 'John',
// Optional personal info
lastName: 'Doe',
jobTitle: 'Senior Developer',
organization: 'Tech Corp',
// Contact information
email: 'john@example.com',
phone: '+1234567890', // Work phone
mobile: '+0987654321', // Mobile phone
website: 'https://johndoe.com',
// Address (optional)
address: '123 Main Street',
city: 'New York',
state: 'NY',
zipCode: '10001',
country: 'USA',
// Social media links
social: {
linkedin: 'linkedin.com/in/johndoe',
github: 'github.com/johndoe',
twitter: 'twitter.com/johndoe',
instagram: 'instagram.com/johndoe',
facebook: 'facebook.com/johndoe',
youtube: 'youtube.com/@johndoe'
},
// Additional notes
notes: 'Available for freelance projects'
};
const qrCode = await generator.generate(completeCard);Make your QR code match your brand:
const qrCode = await generator.generate(myCard, {
size: 400,
customColors: {
foreground: '#FF5733', // QR code color (orange)
background: '#FFFFFF' // Background color (white)
}
});Add your company logo or profile picture to the center of the QR code:
const qrCode = await generator.generate(myCard, {
size: 400,
logo: {
url: 'https://example.com/logo.png', // URL or data URI
size: 80, // Size in pixels
margin: 10 // Margin around logo
},
errorCorrectionLevel: 'H' // High error correction (recommended with logo)
});Important: When using a logo, always use errorCorrectionLevel: 'H' to ensure the QR code remains scannable even with the logo covering part of it.
const qrCode = await generator.generate(myCard, {
size: 500, // Larger QR code (default: 400)
margin: 2, // Smaller margin (default: 4)
errorCorrectionLevel: 'M' // Lower error correction (faster scanning, less data capacity)
});// Generate the QR code
const qrCode = await generator.generate(myCard);
// Download as PNG file
generator.exportAsPNG(qrCode, 'my-business-card.png');const qrCode = await generator.generate(myCard);
// Download as PDF file
await generator.exportAsPDF(qrCode, 'my-business-card.pdf');// Generate SVG directly
const svgString = await generator.generateSVG(myCard, {
size: 400,
customColors: {
foreground: '#000000',
background: '#FFFFFF'
}
});
// Export SVG file (browser only)
generator.exportAsSVG(svgString, 'my-business-card.svg');Note: Export functions only work in browser environments. In Node.js, you'll get the data URI or SVG string, which you can then save using Node.js file system operations.
If you just need the vCard string without generating a QR code:
const vCardString = generator.generateVCard(myCard);
console.log(vCardString);
// Output:
// BEGIN:VCARD
// VERSION:3.0
// N:Doe;John;;;
// FN:John Doe
// ...const { QRBusinessCard } = require('qr-business-card-generator');
const generator = new QRBusinessCard();
const data = {
firstName: 'John',
email: 'john@example.com',
phone: '+1234567890'
};
const qrCode = await generator.generate(data);
// qrCode is a data URI string
// You can save it using fs.writeFile or use it in other waysimport React, { useState } from 'react';
import { QRBusinessCard, BusinessCardData } from 'qr-business-card-generator';
function BusinessCardQR() {
const [qrCode, setQrCode] = useState<string | null>(null);
const generator = new QRBusinessCard();
const cardData: BusinessCardData = {
firstName: 'Jane',
lastName: 'Smith',
email: 'jane@example.com',
phone: '+1234567890',
organization: 'Tech Startup',
jobTitle: 'Frontend Developer'
};
const handleGenerate = async () => {
const qr = await generator.generate(cardData, {
size: 400,
logo: {
url: '/logo.png',
size: 80
}
});
setQrCode(qr);
};
const handleDownload = () => {
if (qrCode) {
generator.exportAsPNG(qrCode, 'my-card.png');
}
};
return (
<div>
<button onClick={handleGenerate}>Generate QR Code</button>
{qrCode && (
<>
<img src={qrCode} alt="Business Card QR Code" />
<button onClick={handleDownload}>Download PNG</button>
</>
)}
</div>
);
}<!DOCTYPE html>
<html>
<head>
<title>QR Business Card</title>
</head>
<body>
<div id="qr-container"></div>
<script type="module">
import { QRBusinessCard } from './node_modules/qr-business-card-generator/dist/esm/index.js';
const generator = new QRBusinessCard();
const data = {
firstName: 'John',
email: 'john@example.com',
phone: '+1234567890'
};
generator.generate(data, { size: 400 })
.then(qrCode => {
const img = document.createElement('img');
img.src = qrCode;
document.getElementById('qr-container').appendChild(img);
});
</script>
</body>
</html>Note: For browser usage, you may need to bundle the library with a bundler like webpack, rollup, or esbuild since the library uses Node.js dependencies.
QR codes have different error correction levels that determine how much of the code can be damaged while still remaining scannable:
- L (Low) - ~7% error correction, smallest QR code
- M (Medium) - ~15% error correction (default)
- Q (Quartile) - ~25% error correction
- H (High) - ~30% error correction, largest QR code (recommended when using logos)
const qrCode = await generator.generate(data, {
errorCorrectionLevel: 'H' // Use high error correction with logos
});- Size: Keep logo size between 15-25% of QR code size
- Error Correction: Always use
'H'(high) when adding logos - Format: Use PNG or JPG images with transparent or white backgrounds
- Accessibility: Ensure logo URL is accessible (CORS enabled for external URLs)
const qrCode = await generator.generate(data, {
size: 400,
logo: {
url: 'https://example.com/logo.png', // Must be accessible
size: 80, // 20% of 400px
margin: 10
},
errorCorrectionLevel: 'H' // Essential for logo
});When someone scans your QR code:
- Recognition: Their phone recognizes the vCard format
- Prompt: They get a prompt asking if they want to save the contact
- Save: All your information is automatically added to their contacts
The vCard format is a standard that works with:
- ✅ iPhone Contacts
- ✅ Android Contacts
- ✅ Google Contacts
- ✅ Outlook
- ✅ Most contact management systems
const generator = new QRBusinessCard();Generates a QR code from business card data.
Parameters:
data: BusinessCardData- Your business card informationoptions?: QRCodeOptions- Optional customization options
Returns: Promise<string> - QR code as data URI (PNG) or SVG string
Example:
const qrCode = await generator.generate(data, {
size: 400,
customColors: { foreground: '#000000', background: '#FFFFFF' }
});Generates vCard format string without creating a QR code.
Parameters:
data: BusinessCardData- Business card information
Returns: string - vCard 3.0 format string
Convenience method to generate QR code as PNG format.
Returns: Promise<string> - PNG data URI
Generates QR code as SVG format.
Returns: Promise<string> - SVG string
Downloads QR code as PNG file (browser only).
Parameters:
dataUri: string- QR code data URIfilename?: string- Optional filename (default: 'qr-business-card.png')
Downloads QR code as SVG file (browser only).
Downloads QR code as PDF file (browser only).
Returns: Promise<void>
interface BusinessCardData {
firstName: string; // Required
lastName?: string;
organization?: string;
jobTitle?: string;
email?: string;
phone?: string;
mobile?: string;
website?: string;
address?: string;
city?: string;
state?: string;
zipCode?: string;
country?: string;
social?: {
linkedin?: string;
twitter?: string;
instagram?: string;
github?: string;
facebook?: string;
youtube?: string;
};
notes?: string;
}interface QRCodeOptions {
size?: number; // QR code size in pixels (default: 400)
margin?: number; // Margin in modules (default: 4)
errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H'; // Error correction (default: 'H')
customColors?: {
foreground?: string; // QR code color (default: '#000000')
background?: string; // Background color (default: '#FFFFFF')
};
logo?: {
url: string; // Logo image URL or data URI
size?: number; // Logo size in pixels (default: 20% of QR size)
margin?: number; // Logo margin (default: 10)
};
type?: 'image/png' | 'image/svg+xml'; // Output format (default: 'image/png')
}- Size too small: Use at least 200px, preferably 400px or larger
- Low error correction: Use
'H'(high) error correction level - Logo too large: Keep logo under 25% of QR code size
- Poor contrast: Ensure good contrast between foreground and background colors
- CORS issues: Make sure the logo URL is accessible and CORS-enabled
- Invalid URL: Check that the logo URL is correct and the image exists
- Format issues: Use PNG or JPG formats
- Browser only: Export functions only work in browser environments, not Node.js
- Generate first: Make sure you've generated a QR code before trying to export
If you see errors about modules not being found in the browser:
- Use a bundler: The library needs to be bundled with webpack, rollup, or esbuild for browser use
- Check examples: See the
examples/folder for working browser examples
Check out the examples/ folder for complete working examples:
- basic-usage/ - Simple HTML/JavaScript example
- react-example/ - React component example
Contributions are welcome! Feel free to:
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
MIT License - feel free to use this library in personal or commercial projects.
Built with:
Made with ❤️ for the developer community. Happy coding!