Skip to main content
Sponsor on OpenCollective
View Zag.js on Github

QR Code

A QR code encodes information or links that can be scanned with a phone or app.

Good to know: The QR code encoding logic is built on top of the uqr library.

1.35.2 (latest)Visualize LogicView Source
Loading...

Features

  • Renders an SVG element (good for SSR)
  • Customize the size of the QR code in pixels
  • Set the error correction level
  • Customize the background and foreground color

Installation

Install the QR code package:

npm install @zag-js/qr-code @zag-js/vue
# or
yarn add @zag-js/qr-code @zag-js/vue

Anatomy

Check the QR code anatomy and part names.

Each part includes a data-part attribute to help identify them in the DOM.

Usage

Import the QR code package:

import * as qrCode from "@zag-js/qr-code"

These are the key exports:

  • machine - State machine logic.
  • connect - Maps machine state to JSX props and event handlers.

Then use the framework integration helpers:

<script setup lang="ts">
  import * as qrCode from "@zag-js/qr-code"
  import { normalizeProps, useMachine } from "@zag-js/vue"

  const controls = useControls(qrCodeControls)

  const service = useMachine(qrCode.machine, {
    id: "1",
    value: "https://github.com/chakra-ui",
  })

  const api = computed(() => qrCode.connect(service, normalizeProps))
</script>

<template>
  <div v-bind="api.getRootProps()">
    <svg v-bind="api.getFrameProps()">
      <path v-bind="api.getPatternProps()" />
    </svg>
    <div v-bind="api.getOverlayProps()">
      <img
        src="https://avatars.githubusercontent.com/u/54212428?s=88&v=4"
        alt=""
      />
    </div>
  </div>
</template>

Setting the QR code value

Set value to control the encoded content.

const service = useMachine(qrCode.machine, {
  // ...
  value: "https://example.com",
})

Setting an initial value

Use defaultValue for an uncontrolled initial value.

const service = useMachine(qrCode.machine, {
  defaultValue: "https://example.com",
})

Listening for value changes

Use onValueChange to react when the encoded value changes.

const service = useMachine(qrCode.machine, {
  onValueChange(details) {
    // details => { value: string }
    console.log(details.value)
  },
})

Setting pixel size

Use pixelSize to control QR code density.

const service = useMachine(qrCode.machine, {
  value: "https://example.com",
  pixelSize: 8,
})

Setting the correction level

Error correction allows for the QR code to be blocked or resized while still recognizable. In some cases where the link is too long or the logo overlay covers a significant area, the error correction level can be increased.

The QR code machine accepts the following error correction levels:

  • L: Allows recovery of up to 7% data loss (default)
  • M: Allows recovery of up to 15% data loss
  • Q: Allows recovery of up to 25% data loss
  • H: Allows recovery of up to 30% data loss

To set the error correction level, pass the encoding.ecc or encoding.boostEcc context property.

const service = useMachine(qrCode.machine, {
  value: "...",
  encoding: { ecc: "H" },
})

The alternative is to enlarge the QRCode by increasing the size of the svg element.

To add a logo overlay to the QR code, render the image part. The logo will be automatically centered within the QR code.

<div {...api.getRootProps()}>
  <svg {...api.getFrameProps()}>{/** ... */}</svg>
  <div {...api.getOverlayProps()}>
    <img src="..." alt="" />
  </div>
</div>

Changing the color

To change the color of the QR code, set the fill attribute on the path part.

[data-scope="qr-code"][data-part="pattern"] {
  fill: green;
}

To change the background color of the QR code, set the background-color

[data-scope="qr-code"][data-part="frame"] {
  background-color: white;
}

Exporting the QR code

To export the QR code as an image, use api.getDataUrl.

api.getDataUrl("image/png").then((url) => {
  // do something with the URL (like download it)
})

You can also use api.getDownloadTriggerProps to create a download button.

<button
  {...api.getDownloadTriggerProps({
    mimeType: "image/png",
    fileName: "qr-code",
  })}
>
  Download QR
</button>

Styling guide

Each part includes a data-part attribute you can target in CSS.

[data-scope="qr-code"][data-part="root"] {
  /* Styles for the root part */
}

[data-scope="qr-code"][data-part="frame"] {
  /* Styles for the svg part */
}

[data-scope="qr-code"][data-part="pattern"] {
  /* Styles for the path */
}

[data-scope="qr-code"][data-part="overlay"] {
  /* Styles for the logo */
}

Methods and Properties

Machine Context

The QR code machine exposes the following context properties:

  • valuestringThe controlled value to encode.
  • defaultValuestringThe initial value to encode when rendered. Use when you don't need to control the value of the qr code.
  • idsPartial<{ root: string; frame: string; }>The element ids.
  • encodingQrCodeGenerateOptionsThe qr code encoding options.
  • onValueChange(details: ValueChangeDetails) => voidCallback fired when the value changes.
  • pixelSizenumberThe pixel size of the qr code.
  • dir"ltr" | "rtl"The document's text/writing direction.
  • idstringThe unique identifier of the machine.
  • getRootNode() => ShadowRoot | Node | DocumentA root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.

Machine API

The QR code api exposes the following methods:

  • valuestringThe value to encode.
  • setValue(value: string) => voidSet the value to encode.
  • getDataUrl(type: DataUrlType, quality?: number) => Promise<string>Returns the data URL of the qr code.
Edit this page on GitHub
On this page