🚀 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.