✨ glim-qr-code

A production-ready, lightweight, and beautiful QR code generator for React & Next.js.

Brought to you by glimlang.xyz

---

🚀 Why glim-qr-code?

Built from the ground up for modern React and Next.js applications, glim-qr-code resolves the common headaches developers face with QR generation:

• Zero Hydration Mismatch: Next.js App & Pages Router safe out of the box (uses "use client" transparently).
• Beautiful Presets: Supports classic square, beautiful dots, and modern rounded styles.
• Embedded Logos: Centered logos with padding/backgrounds are handled mathematically for you.
• Export Ready: Seamlessly download as PNG, JPG, or copy raw SVG.
• Micro Bundle: Extremely lightweight relying only on raw layout calculation, omitting massive canvas dependencies.

---

📦 Installation

npm install glim-qr-code

---

🛠️ Developer Architecture (How it works under the hood)

For our fellow developers, here is how the library is structured:

1. useGlimQRCode (The Brains): A headless hook that converts your string payload into a deterministic 2D binary matrix [[1, 0, 1], ...]. It runs purely in JavaScript memory.
2. GlimQRCode (The Muscles): A React UI Component that ingests the 2D matrix. Depending on your choice of renderAs="svg" (default and highly recommended for crispness) or renderAs="canvas", it mathematically plots each bit.
3. QRCodeFormatters (The Translators): A pure utility object formatting strings specifically for smartphones (e.g., WIFI:S:MyNet...).

---

🎨 Usage & Examples

1. The Basic React / Next.js Setup

Just mount it and go.

import { GlimQRCode } from 'glim-qr-code';

export default function App() {
  return (
    <GlimQRCode 
      value="https://github.com/developer/glim-qr-code" 
      size={250}
      color="#1e293b" // Tailwind Slate 900
      bgColor="#f8fafc" // Tailwind Slate 50
    />
  );
}

2. Beautiful "Dots" Style with Custom Logo

If you want something that stands out—try type: "dots". If adding a logo, the library automatically bumps errorCorrectionLevel="H" so the QR remains scannable!

import { GlimQRCode } from 'glim-qr-code';

export function StyledBrandQR() {
  return (
    <GlimQRCode 
      value="https://mywebsite.com" 
      size={300}
      dotsOptions={{ type: 'dots', color: '#B45309' }}
      imageSettings={{
        src: '/assets/my-logo.png', // Any valid URL or public path
        width: 60,
        height: 60,
        bgColor: '#FFFFFF', // Creates a safe zone behind the logo
        margin: 4,
        borderRadius: 12
      }}
      caption="Scan to visit us!"
    />
  );
}

3. VCard, Wi-Fi, Email with formatters

We provide QRCodeFormatters so you never have to memorize obscure syntax again.

import { GlimQRCode, QRCodeFormatters } from 'glim-qr-code';

export function WiFiConnect() {
  // Generates WIFI:S:Starbucks;T:WPA;P:AwesomeCoffee123;;
  const wifiPayload = QRCodeFormatters.wifi('Starbucks', 'AwesomeCoffee123', 'WPA');

  return (
    <GlimQRCode 
      value={wifiPayload} 
      size={200}
      dotsOptions={{ type: 'rounded' }} 
    />
  );
}

4. Downloading the QR Code Programmatically

We expose a ref handle (GlimQRCodeRef) enabling you to trigger downloads natively.

import { useRef } from 'react';
import { GlimQRCode, GlimQRCodeRef } from 'glim-qr-code';

export function DownloadableInvoice() {
  const qrRef = useRef<GlimQRCodeRef>(null);

  const handleDownload = () => {
    // Supports "png", "jpeg", or "svg"
    qrRef.current?.download("png", "customer-invoice-qr");
  };

  return (
    <div style={{ textAlign: "center" }}>
      <GlimQRCode ref={qrRef} value="INV-2026-0599" size={250} />
      <button onClick={handleDownload} style={{ marginTop: "16px" }}>
        Download Receipt
      </button>
    </div>
  );
}

---

🎛️ API Reference

<GlimQRCode /> Properties

Prop	Type	Default	Description
value	string	Required	The exact payload to encode (URL, Text, JSON).
size	number	256	Square width/height in pixels.
color	string	'#000000'	Foreground color (the dots).
bgColor	string	'#FFFFFF'	Background color.
errorCorrectionLevel	'L' | 'M' | 'Q' | 'H'	'M'	Scanning redundancy (L=7%, M=15%, Q=25%, H=30%).
renderAs	'svg' | 'canvas'	'svg'	Under-the-hood rendering engine. SVG scales infinitely.
margin	number	4	The quiet zone block boundary.
dotsOptions	{ type, color }	{ type: 'square' }	Types available: 'square', 'dots', 'rounded'.
imageSettings	LogoOptions	undefined	Config object for dropping an image in the center.
caption	string	undefined	Text displayed neatly below the code.
alt	string	'QR Code'	ARIA compliance tag for screen readers.

Utility Formatters: QRCodeFormatters

• QRCodeFormatters.text(text)
• QRCodeFormatters.link(url)
• QRCodeFormatters.phone(number)
• QRCodeFormatters.email(address, subject?, body?)
• QRCodeFormatters.wifi(ssid, password?, encryption?, hidden?)
• QRCodeFormatters.json(data)

---

🌍 Community

Join the glimlang developer community and help us build amazing tools!

• Website: glimlang.xyz
• GitHub: github.com/glimlang

---

💖 Contributing

We welcome PRs to make this package even better!

1. Clone repository
2. npm install
3. Modify logic in src/
4. Run npm run build

📄 License

MIT License. Created with ❤️ by glimlang.xyz for the open-source community.