npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

custom-qrcode-browser

v0.0.10

Published

[![Continuous Integrations](https://github.com/CyrilDesch/custom-qrcode-browser/actions/workflows/continuous-integrations.yaml/badge.svg?branch=main)](https://github.com/CyrilDesch/custom-qrcode-browser/actions/workflows/continuous-integrations.yaml) [![L

Downloads

28

Readme

Custom QRCode Browser

Continuous Integrations License Package tree-shaking Package dependency count npm stars

A lightweight, dependency-free library for generating highly customizable QR codes in browser environments. Leverage SVG to create stunning QR codes with unique designs and embedded logos. Fully documented for Angular and React, with no dependencies and just 40 kB after minification.

Table of Contents

🚀 Features

Customization

  • QR Code Shapes: Choose between square or circle designs.
  • Matrix Pixels: Customize pixel shapes like squares, circles, stars, and more.
  • Eyes & Eye Frames: Fully customize the shape and color of the eyes.
  • Logo Embedding: Add logos with adjustable size, background, and padding.
  • Alignment Patterns: Unique patterns for larger QR codes.
  • Colors & Gradients: Apply solid colors or various gradients to all elements.
  • Backgrounds: Set solid colors or use background images.
  • Timing Lines: Customize timing lines with different shapes and colors.

Additional Features

  • Data Support: Encode URLs, text, emails, phones, SMS, geolocations, WiFi credentials, and more.
  • Error Correction: Choose from LOW, MEDIUM, QUARTILE, or HIGH error correction levels.
  • Encoding Modes: Supports Numeric, Alphanumeric, Byte, and Kanji modes.
  • Declarative API: Use a simple JSON-based API to customize QR codes.

Performance & Compatibility

  • Lightweight: Only 40 kB after minification, with no external dependencies.
  • Browser Support: Works seamlessly in modern browsers and devices.
  • Responsive: Fully scalable QR codes using SVG.
  • Standards Compliant: Adheres to the ISO/IEC 18004 QR Code specification.

📦 Installation

Install the library using npm or yarn:

npm install custom-qrcode-browser
# or
yarn add custom-qrcode-browser

💻 Usage

Angular

1. Import and Configure

Create a new Angular component to render the QR code:

import {
  Component,
  OnChanges,
  Input,
  ViewChild,
  ElementRef,
  SimpleChanges,
} from "@angular/core";
import {
  QrCodeGenerator,
  QrOptionsConfig,
  QrDataConfig,
} from "custom-qrcode-browser";

@Component({
  selector: "app-custom-qr-code",
  standalone: true,
  template: `<svg #svgElement></svg>`,
})
export class CustomQrCodeComponent implements OnChanges {
  @Input() data!: QrDataConfig;
  @Input() options?: QrOptionsConfig;

  @ViewChild("svgElement", { static: true })
  svgElement!: ElementRef<SVGSVGElement>;

  ngOnChanges(changes: SimpleChanges): void {
    if (changes["data"] || changes["options"]) {
      this.generateQrCode();
    }
  }

  private generateQrCode(): void {
    if (this.svgElement && this.svgElement.nativeElement) {
      const qrCodeCore = QrCodeGenerator(this.svgElement.nativeElement, {
        data: this.data,
        options: this.options,
      });
      qrCodeCore.generateSvg();
    }
  }
}

2. Use the Component

See more on example.

<app-custom-qr-code [data]="data" [options]="options" />

React

1. Create the QRCode Component

import React, { useRef, useEffect } from "react";
import { QrCodeGenerator, QrCodeConfig } from "custom-qrcode-browser";

const QrCode: React.FC<QrCodeConfig> = (qrCodeConfig) => {
  const svgRef = useRef<SVGSVGElement | null>(null);

  useEffect(() => {
    if (svgRef.current) {
      const qrCodeCore = QrCodeGenerator(svgRef.current, qrCodeConfig);
      qrCodeCore.generateSvg();
    }
  }, [qrCodeConfig]);

  return <svg ref={svgRef} />;
};

export default QrCode;

2. Use the Component

See more on example.

const Example: React.FC = () => (
  <div style={{ width: 300 }}>
    <QrCode data={data} options={options} />
  </div>
);

export default App;

📋 API Documentation


► QrData

Describes the different kinds of information that can be scanned and interpreted by QR code readers.

Usage

const data: IQrData = {
  type: "Text", // or 'Url', 'Email', etc.
  data: {
    /* specific data fields */
  },
};

Supported Types and Fields

  • Text

    type: 'Text',
    data: {
      value: string; // Any text string
    }
  • Url

    type: 'Url',
    data: {
      url: string; // A valid URL
    }
  • Email

    type: 'Email',
    data: {
      email: string;              // Recipient email address
      copyTo?: string;            // CC email address (optional)
      subject?: string;           // Email subject (optional)
      body?: string;              // Email body content (optional)
    }
  • GeoPos

    type: 'GeoPos',
    data: {
      lat: number; // Latitude
      lon: number; // Longitude
    }
  • Bookmark

    type: 'Bookmark',
    data: {
      url: string;   // Bookmark URL
      title: string; // Bookmark title
    }
  • Wifi

    type: 'Wifi',
    data: {
      authentication?: 'WEP' | 'WPA' | 'nopass'; // Authentication type
      ssid?: string;                             // Network SSID
      psk?: string;                              // Password
      hidden?: boolean;                          // Hidden network flag
    }
  • Phone

    type: 'Phone',
    data: {
      phoneNumber: string; // Phone number
    }
  • SMS

    type: 'SMS',
    data: {
      phoneNumber: string; // Recipient phone number
      subject?: string;    // Message content (optional)
      isMMS?: boolean;     // Set true for MMS, false for SMS (default)
    }
  • BizCard

    type: 'BizCard',
    data: {
      firstName?: string;
      secondName?: string;
      job?: string;
      company?: string;
      address?: string;
      phone?: string;
      email?: string;
    }
  • VCard

    type: 'VCard',
    data: {
      name?: string;
      company?: string;
      title?: string;
      phoneNumber?: string;
      email?: string;
      address?: string;
      website?: string;
      note?: string;
    }
  • MeCard

    type: 'MeCard',
    data: {
      name?: string;
      address?: string;
      phoneNumber?: string;
      email?: string;
    }
  • Event

    type: 'Event',
    data: {
      uid?: string;
      stamp?: string;
      organizer?: string;
      start?: string;   // Format: YYYYMMDDTHHmmss
      end?: string;     // Format: YYYYMMDDTHHmmss
      summary?: string;
    }
  • GooglePlay

    type: 'GooglePlay',
    data: {
      appPackage: string; // App package name
    }

► QrOptions

Describes the different options available to customize QR codes.

Usage

const options: QrOptions = {
  sizeRatio: 0.8,
  errorCorrectionLevel: "HIGH",
  shapes: {
    /* shape configurations */
  },
};

Available Options

  • sizeRatio: number (between 0 and 1)

    Defines the size ratio of the QR code relative to its container.

  • errorCorrectionLevel: 'LOW' | 'MEDIUM' | 'QUARTILE' | 'HIGH'

    Error correction level; higher levels can restore more data if the code is damaged.

  • shapes: QrShapesConfig

    Customize the shapes of various QR code elements. See below for more details.


► QrShapesConfig

  • shapes.qrCode

    Shape of the overall QR code.

    shapes: {
      qrCode: {
        type: "Square" | "Circle";
        seed?: number; // Optional: used to vary randomness added pixel in Circle type
      }
    }
  • shapes.matrixPixel

    Shape of the individual pixels in the QR code matrix. See QrPixelShapeConfig and QrColorConfig for details.

    shapes: {
      matrixPixel: {
        pixelShape: QrPixelShapeConfig;
        color?: QrColorConfig;
      }
    }
  • shapes.eye

    Shape of the eyes (the three corner elements). See QrColorConfig for details.

    shapes: {
      eye: {
        type: 'Square' | 'Circle' | 'Rhombus';
        cornerRadius?: number; // Between 0 and 1, only for 'Square' type
        color?: QrColorConfig;
      };
    }
  • shapes.eyeFrame

    Shape of the eye frames. See QrPixelShapeConfig and QrColorConfig for details.

    shapes: {
      eyeFrame: {
        type: "Square" | "Circle";
        pixelShape: QrPixelShapeConfig;
        color?: QrColorConfig;
      }
    }
  • shapes.logo

    Embed a logo in the QR code. See QrColorConfig for details.

    shapes: {
      logo: {
        type: 'Circle' | 'Square' | 'Rhombus';
        image?: string | null;  // SVG or image URL
        sizeRatio?: number;      // Between 0 and 1
        padding?: number;        // In pixels
        color?: QrColorConfig;
      };
    }
  • shapes.timingLine

    Customize the timing lines. See QrPixelShapeConfig and QrColorConfig for details.

    shapes: {
      timingLine: {
        pixelShape: QrPixelShapeConfig;
        color?: QrColorConfig;
      }
    }
  • shapes.background

    Background options for the QR code. See QrColorConfig for details.

    shapes: {
      background: {
        image?: string;      // Image URL
        color?: QrColorConfig; // Background color
      };
    }
  • shapes.alignmentPattern

    Shape of the alignment patterns for larger QR codes. See QrPixelShapeConfig and QrColorConfig for details.

    shapes: {
      alignmentPattern: {
        type: "Square" | "Circle";
        pixelShape: QrPixelShapeConfig;
        color?: QrColorConfig;
      }
    }

► QrColorConfig

Describes the different color options available for QR code elements.

Usage

const color: QrColorConfig = {
  type: "Solid",
  value: "#000000",
};

Types and Options

  • Solid

    type: 'Solid',
    value: string; // Any valid CSS color value
  • LinearGradient

    type: 'LinearGradient',
    colors: Array<[number, string]>; // e.g., [[0, 'red'], [1, 'blue']]
    orientation: 'Horizontal' | 'Vertical' | 'LeftDiagonal' | 'RightDiagonal';
  • RadialGradient

    type: 'RadialGradient',
    colors: Array<[number, string]>;
    radius: number; // Between 0 and 1
  • SweepGradient

    type: 'SweepGradient',
    colors: Array<[number, string]>;

► QrPixelShapeConfig

Describes the different shape options available for individual pixels.

Usage

const pixelShape: QrPixelShapeConfig = {
  type: "RoundCorners",
  sizeRatio: 1,
  cornerRadius: 0.5,
};

Types and Options

  • type

    type: "Square" |
      "Circle" |
      "Star" |
      "Rhombus" |
      "Hexagon" |
      "Octagon" |
      "RoundCorners" |
      "StickyCorners" |
      "RoundCornersVertical" |
      "RoundCornersHorizontal";
  • sizeRatio

    sizeRatio: number; // Between 0 and 1
  • cornerRadius

    cornerRadius: number; // Between 0 and 1, only for "corner" shapes

📚 Examples

Example 1: Basic QR Code

const data: QrDataConfig = {
  type: "Url",
  data: { url: "https://example.com" },
};

const options: QrOptionsConfig = {
  sizeRatio: 1,
  errorCorrectionLevel: "MEDIUM",
};

Example 2: QR Code with Custom Shapes and Colors

const data: QrDataConfig = {
  type: "Text",
  data: { value: "Custom QR Code" },
};

const options: QrOptionsConfig = {
  sizeRatio: 0.9,
  errorCorrectionLevel: "HIGH",
  shapes: {
    qrCode: {
      type: "Square",
    },
    matrixPixel: {
      pixelShape: { type: "Hexagon", sizeRatio: 0.9 },
      color: {
        type: "LinearGradient",
        colors: [
          [0, "#ff0000"],
          [1, "#0000ff"],
        ],
        orientation: "Vertical",
      },
    },
    eye: {
      type: "Circle",
      color: {
        type: "LinearGradient",
        colors: [
          [0, "#ff0000"],
          [1, "#0000ff"],
        ],
        orientation: "Vertical",
      },
    },
    eyeFrame: {
      type: "Square",
      pixelShape: { type: "StickyCorners", cornerRadius: 0.2 },
      color: { type: "Solid", value: "#000000" },
    },
    background: {
      color: { type: "Solid", value: "#ffffff" },
    },
  },
};

Example 3: QR Code with Embedded Logo

const data: QrDataConfig = {
  type: "Url",
  data: { url: "https://github.com" },
};

const options: QrOptionsConfig = {
  sizeRatio: 1,
  errorCorrectionLevel: "LOW",
  shapes: {
    qrCode: {
      type: "Circle",
    },
    matrixPixel: {
      pixelShape: {
        type: "StickyCorners",
        cornerRadius: 0.5,
      },
    },
    logo: {
      type: "Circle",
      image:
        "https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png",
      sizeRatio: 0.4,
      padding: 1,
      color: { type: "Solid", value: "white" },
    },
  },
};

✋ FAQ

Why can't I scan my QR code?

Ensure that the QR code has sufficient contrast between the foreground and background colors. Avoid using too many colors or complex gradients that may hinder QR code scanners. Also, ensure the error correction level is set appropriately.

How can I improve error correction?

Set the errorCorrectionLevel in QrOptions to a higher value like 'HIGH' to improve the QR code's resilience to damage or distortion.

Can I use custom shapes for the QR code pixels?

Yes, you can customize pixel shapes using the QrPixelShapeConfig in shapes.matrixPixel.pixelShape.

📝 Contributing

Contributions are welcome! Here are some ideas to improve the library:

  • [ ] Add new shapes for the eye frame (e.g., multiple ways with rounded corners).
  • [ ] Implement random color options.
  • [ ] Add support for more data types.
  • [ ] Improve documentation and examples.

⚖️ License

Released under the MIT License.