It's a QR Code

Introducion

"It's a QR Code" is a web component that show its text content in QR code image

Getting started

CDN

To use a CDN all you need is to add the following code in the HTML page:

<script type="module" src="https://cdn.jsdelivr.net/gh/OmarCastro/its-a-qrcode@0.4.0/dist/qrcode.element.min.js?named=qr-code"></script>

NPM

If you wish to import from npm and use a bundler, you can install the its-a-qrcode package

npm install its-a-qrcode

Not all bundlers support query strings, it is recommended to import and register the component, like the following code:

import element from 'its-a-qrcode'

customElements.define('qr-code', element)

Examples

Hello world

<qr-code>Hello world</qr-code>

Resize

Hello world

<qr-code class="resizable-qr-code">Hello world</qr-code>

.resizable-qr-code {
    width: 100%;
    height: 100%;                
    --qrcode-resize: true;
}

To enable qr code resize, one of the values are supported: true, yes, enable, enabled. It is case insensitive (Yes equals to yes). Any other value disables it

Whitespace processing

To be easier to handle specific data types, the text content is processed before turning into a QR Code, mostly whitespace, as to be more flexible on where to put the content.

The next examples in this section will show the QR Code content with visible whitespaces to get which symbol represents. The next list can be used as a guide to understand the symbols

Carriage Return (\r), will print ⏎
Line Feed (\n), will print ¶
space will print ⸱
Tab (\t) will print →

The next example shows that even with space and new lines the content is the trimmed text. This is the default behaviour

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua

<qr-code>
    
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua
    
</qr-code>

For specific data types the content is processed differently. One example is VCARD content.

If the element text content begins with "BEGIN:VCARD", it will apply de vcard preprocessor which does the following actions:

dedent using the first letter position as the amount of characters to dedent
remove blank lines (empty lines and lines with whitespace only)
fold lines if it passes the 75 character limit (RFC6350 section-3.2)
convert lines to CRFL (RFC6350 section-3.2)

BEGIN:VCARD VERSION:4.0 FN:Lorem Ipsum N:Ipsum;Lorem;;;ing. jr,M.Sc. EMAIL;TYPE=work:lorem.ipsum@viagenie.com NOTE:Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Semper eget duis at tellus at urna condimentum mattis. Ultrices vitae auctor eu augue. END:VCARD

<qr-code>
    
    BEGIN:VCARD
    VERSION:4.0

    FN:Lorem Ipsum
    N:Ipsum;Lorem;;;ing. jr,M.Sc.
    EMAIL;TYPE=work:lorem.ipsum@viagenie.com

    NOTE:Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Semper eget duis at tellus at urna condimentum mattis. Ultrices vitae auctor eu augue.

    END:VCARD
    
</qr-code>

Custom process

As you can see, the objective of the processing the whitespace is to simply write the content without needing to deal with specific details, as well to reduce the QRCode size. You can choose a custom process before converting to QR code by setting data-whitespace attribute, the next list shows the supported processes

pre Put element textContent as is, and turns it as QR Code image content, just overrides the default behaviour
Aliases: none
trim Remove all leading and trailing whitespace from element text content
dedent Remove common leading whitespace from every line in text
dedent-from-first-line Remove leading whitespace from every line in text. The maximum amount of leading whitespace is the whitespace amount in the first non blank line
trim-line Remove all leading and trailing whitespace from every line in element text
Aliases: trim-lines
no-empty-line Remove all empty lines in element text content
Aliases: no-empty-lines
no-blank-line Remove all empty of lines with only whitespace characters in element text content
Aliases: no-blank-lines
vcard Applies vCard process as described previously
vevent Applies vEvent process, it does exaclty the same process as the vCard, so it is pratically an alias but it is not inteded to be

The next example can be used to test the data-pre-processing, multiple pre processes can be applied by adding them to the data-data-whitespace attibute separated by space (e.g. data-whitespace="trim dedent") the order of execution will be from left to right

BEGIN:VCARD VERSION:4.0 FN:Lorem Ipsum N:Ipsum;Lorem;;;ing. jr,M.Sc. EMAIL;TYPE=work:lorem.ipsum@viagenie.com NOTE:Lorem ipsum dolor sit amet END:VCARD

<qr-code data-whitespace="vcard">
    BEGIN:VCARD
    VERSION:4.0
    FN:Lorem Ipsum
    N:Ipsum;Lorem;;;ing. jr,M.Sc.
    EMAIL;TYPE=work:lorem.ipsum@viagenie.com
    NOTE:Lorem ipsum dolor sit amet
    END:VCARD
</qr-code>

Data types

URL link

To create a link using a QR code just put the URL link as the component text

https://omarcastro.github.io/its-a-qrcode/

<qr-code>
    https://omarcastro.github.io/its-a-qrcode/
</qr-code>

E-mail address

To encode an e-mail address like sean@example.com, one could simply encode sean@example.com. However to ensure it is recognized as an e-mail address, it is advisable to create a proper mailto: URL from the address: mailto:sean@example.com. All of the standard mailto: tricks/links should work here as well. Readers should open a blank e-mail message to the given address.

-- Barcode Contents Wiki, https://github.com/zxing/zxing/wiki/Barcode-Contents#e-mail-address, last read: 2023/10/29

So, put mailto: with the email address

mailto:someone@yoursite.com

<qr-code>mailto:someone@yoursite.com</qr-code>

Telephone

A tel URI should be used to encode a telephone number, to ensure that the digits are understood as a telephone number. Further, you should generally use the most complete version of a telephone number possible (i.e., country code + area code + number). For example, to encode the US phone number 212-555-1212, one should encode tel:+1-212-555-1212. This tel URI includes a "+1" prefix that will make it usable outside the United States. All of the standard mailto: tricks/links should work here as well. Readers should open a blank e-mail message to the given address.

-- Barcode Contents Wiki, https://github.com/zxing/zxing/wiki/Barcode-Contents#telephone-numbers, last read: 2023/10/29

tel:+12125551212

<qr-code>tel:+12125551212</qr-code>

vCard

As written previously on previously on data-pre-process section, QR code has support for vCard without worrying much about the specifics as it does some pre-processing to make it tolerant to the vCard specification.

BEGIN:VCARD VERSION:4.0 FN:Simon Perreault N:Perreault;Simon;;;ing. jr,M.Sc. BDAY:--0203 GENDER:M EMAIL;TYPE=work:simon.perreault@viagenie.ca END:VCARD

<qr-code>
    BEGIN:VCARD
    VERSION:4.0
    FN:Simon Perreault
    N:Perreault;Simon;;;ing. jr,M.Sc.
    BDAY:--0203
    GENDER:M
    EMAIL;TYPE=work:simon.perreault@viagenie.ca
    END:VCARD
</qr-code>

Calendar Events

There is also another process that is executed when the content starts with "BEGIN:VEVENT" to create calendar events

BEGIN:VEVENT SUMMARY:Summer+Vacation! DTSTART:20180601T070000Z DTEND:20180831T070000Z END:VEVENT

<qr-code>
    BEGIN:VEVENT
    SUMMARY:Summer+Vacation!
    DTSTART:20180601T070000Z
    DTEND:20180831T070000Z
    END:VEVENT
</qr-code>

Error correction level

When generating a QR Code, you can choose between different levels of error correction (EC). Error correction helps, that a QR Code stays readable, even if some pixels are missing. Sometimes this is done on purpose when placing a logo in the QR Code, but sometimes the code just gets damaged, like CDs get scratched, but they will be still readable by CD players. There are 4 different levels of QR Code error correction

Level L - up to 7% damage
Level M - up to 15% damage
Level Q - up to 25% damage
Level H - up to 30% damage (recommend for QR Codes with an embedded logo)

The higher the EC level, the more pixels of the QR Code may be damaged, but the bigger the QR Code gets. The following example shows the QR Code with the same data for all four types of EC levels:

Lorem ipsum dolor sit amet

<qr-code data-error-correction-level="L">Lorem ipsum dolor sit amet</qr-code>

Lorem ipsum dolor sit amet

<qr-code data-error-correction-level="M">Lorem ipsum dolor sit amet</qr-code>

Lorem ipsum dolor sit amet

<qr-code data-error-correction-level="Q">Lorem ipsum dolor sit amet</qr-code>

Lorem ipsum dolor sit amet

<qr-code data-error-correction-level="H">Lorem ipsum dolor sit amet</qr-code>

As you can see the QR Code with the same data encoded gets bigger the higher the error correction level is. You can set the EC level by setting the data-error-correction-level value, the supported values are the short and long names of the EC level, so the supported values are L,Low,M,Medium,Q,Quartile,H,High. It is case insensitive, so LOW equals to Low

Multiple data on QR Code

<qr-code class="qr-code--body-dot-style">
<data>hello world</data>
<data>123456</data>
</qr-code>

hello world 123456

Styling

Color

To customize the QR code color you can use the --qrcode-color CSS property. This property has support to various value groups

/* dark color */
--qrcode-color: red;

/* dark color | light-color  */
--qrcode-color: red #eee;

/* dark color | light-color | corner color */
--qrcode-color: green #eee rgba(0, 0, 200, 0.8);

/* dark color | light-color | corner border color | corner center color */
--qrcode-color: green #eee rgba(0, 0, 200, 0.8) blue;

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua

<qr-code class="example--color__qrcode-color">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua</qr-code>

.example--color__qrcode-color {
    
    --qrcode-color: red beige blue green;
}

It is possible to use separate CSS properties to define the color of a specific part of the QR Code. The next code shows the supported CSS properties

/* color */
--qrcode-dark-color: red;

/* color */
--qrcode-light-color: white;

/* color */
--qrcode-corner-color: white;

/* color | color */
--qrcode-corner-color: white #f00;

/* color */
--qrcode-corner-border-color: gray;

/* color */
--qrcode-corner-center-color: blue;

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua

<qr-code class="example--color__qr">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua</qr-code>

.example--color__qr {

    --qrcode-dark-color: rgba(0, 0, 200, 0.8);

    --qrcode-light-color: pink;

    --qrcode-corner-color: black #f00;
}

Shape style

It is possible to defined the shape of the dark spots of the QR Code by setting the style. There are the following supported style values, they are case insensitive

default - the default square style
rounded - black spots will have rounded corners
square - the same style as the default one, the difference with the default style is on the corner patterns, to forces the corner to use the same style as if the body style is the default one
dot - paints circle dots for each cell

To customize the QR code color you can use the --qrcode-style CSS value the value has support to various values

/* body style */
--qrcode-style: rounded;

/* body style | corner border style  */
--qrcode-style: dot square;

/* body style | corner border style | corner center style */
--qrcode-style: dot rounded square;

Hello world

<qr-code class="styled-qr-code">Hello world</qr-code>

.styled-qr-code {
    width: 100%;
    height: 100%;        
    --qrcode-style: dot dot dot;        
    --qrcode-resize: true;
}

Like color styling, it is possible to use separate CSS properties to define the style of a specific part of the QR Code. The next code shows the supported CSS properties

/* body style */
--qrcode-dot-style: dot;

/* corner border style */
--qrcode-corner-border-style: square;

/* corner center style */
--qrcode-corner-center-style: rounded;

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua

<qr-code class="styled-qr-code2">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua</qr-code>

.styled-qr-code2 {
    --qrcode-dot-style: dot;

    --qrcode-corner-border-style:rounded;

    --qrcode-corner-center-style: square;
    width: 100%;
    height: 100%;        
    --qrcode-resize: true;

}

Margin

It is recommended to have a margin for QR code readers to indentify and parse QR Codes.

The default margin is 4 modules, or 4 cells in a QR code grid, you can define the amount of modules to define the QRCode margin by setting --qrcode-margin, only 0 and positive integers values are accepted, in case of invalid or absent --qrcode-margin value, the default margin is applied

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua

<qr-code class="margin-qr-code">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua</qr-code>

.margin-qr-code {

    --qrcode-margin:4;

    width: 100%;
    height: 100%;        
    --qrcode-resize: true;

}