About qr-code

qr-code is a lightweight, no-dependency Web Component that renders QR codes as scalable vector graphics using the native HTML element syntax. Designed for flexibility, it requires no external frameworks or libraries and can be integrated via npm or a standalone script tag. The component generates standard QR codes from any string content while offering extensive customization through attributes for colors, margins, and aspect ratios. Users can embed a custom logo or icon in the center slot. A standout feature is its built-in animation system, which supports motion effects to draw attention or signal interactions. The library includes multiple preset animations such as Radial Ripple, Materialize In, and Fade In Center Out, addressing various user experience needs. Developers can also create fully custom animations by passing JavaScript functions to the animateQRCode method, controlling timing, easing, and visual transformations. The tool is useful for web applications requiring dynamic or branded QR codes, pay

b

Published by

bitjson

Visit View Profile

README.md

View on GitHub

`<qr-code>`

A no-framework, no-dependencies, customizable, animate-able, SVG-based <qr-code> HTML element. It's just a single, self-contained Web Component.

https://user-images.githubusercontent.com/904007/221692053-1f4ab516-0f63-40e4-b1da-1922ba906963.mp4

Announcement post – usage guidance and background information
Interactive demo – try the above demo in your browser

Usage

Import <qr-code> using your build system or framework (e.g. npm install @bitjson/qr-code), or use the standalone script in your HTML <head> element:

<script src="https://unpkg.com/@bitjson/[email protected]/dist/qr-code.js"></script>

Then use the component anywhere in your HTML <body> element:

<qr-code contents="https://bitjson.com"></qr-code>

Full Example

Here's an example in pure HTML using most features:

<qr-code
  id="qr1"
  contents="https://bitjson.com/"
  module-color="#1c7d43"
  position-ring-color="#13532d"
  position-center-color="#70c559"
  mask-x-to-y-ratio="1.2"
  style="
    width: 200px;
    height: 200px;
    margin: 2em auto;
    background-color: #fff;
  "
>
  <img src="assets/1.2-x-to-y-ratio-icon.svg" slot="icon" />
</qr-code>

<script>
  document.getElementById('qr1').addEventListener('codeRendered', () => {
    document.getElementById('qr1').animateQRCode('MaterializeIn');
  });
</script>

Animations

Animate in, animate on user interactions like URL hits or detected payments, and/or animate out when the QR code interaction is complete.

Several preset animations are available, simply run them with the element's animateQRCode method:

document.getElementById('qr1').animateQRCode('RadialRipple');

Available built-in presets:

FadeInTopDown
FadeInCenterOut
MaterializeIn
RadialRipple
RadialRippleIn

You can also design your own custom animations! Just pass a function to the qr-code's animateQRCode method, e.g.:

document
  .getElementById('qr1')
  .animateQRCode((targets, _x, _y, _count, entity) => ({
    targets,
    from: entity === 'module' ? Math.random() * 200 : 200,
    duration: 500,
    easing: 'cubic-bezier(.5,0,1,1)',
    web: { opacity: [1, 0], scale: [1, 1.1, 0.5] },
  }));

The built-in presets use this API internally, so review those for guidance and inspiration. Pull request for new presets are welcome!

Animation Previewer

The animation previewer makes fine-tuning animations much easier: try it by cloning this repo and running the live-reloading package script:

git clone https://github.com/bitjson/qr-code.git
cd qr-code
npm ci
npm start

Then work on your animation in src/index.html using the animation previewer (at the bottom right of the window) to test the last-run animation at various speeds, scrub through it manually, or play it in reverse.

Production build

Disable the just-animate player in src/components/qr-code/qr-code.tsx, then build:

npm run build

You can test the built component by pointing the script in index.html to dist/qr-code.js and opening the page via the local filesystem.

qr-code