QR Code

A QR (Quick Response) Code is used to provide information or link which can be accessed by scanning the code with an app or a smartphone.

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

Properties

value

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

To use the QR code machine in your project, run the following command in your command line:

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

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

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

This command will install the framework agnostic QR code logic and the reactive utilities for your framework of choice.

Anatomy

To set up the QR code correctly, you'll need to understand its anatomy and how we name its parts.

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

Usage

First, import the QR code package into your project

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

The QR code package exports two key functions:

• machine — The state machine logic for the QR code widget.
• connect — The function that translates the machine's state to JSX attributes and event handlers.

Next, import the required hooks and functions for your framework and use the QR code machine in your project 🔥

import * as qrCode from "@zag-js/qr-code"
import { useMachine, normalizeProps } from "@zag-js/react"
import { useId } from "react"

export function QRCode() {
  const [state, send] = useMachine(
    qrCode.machine({
      id: useId(),
      value: "https://github.com/chakra-ui",
    }),
  )

  const api = qrCode.connect(state, send, normalizeProps)

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

import * as qrCode from "@zag-js/qr-code"
import { normalizeProps, useMachine } from "@zag-js/solid"
import { createMemo, createUniqueId } from "solid-js"

export function QRCode() {
  const [state, send] = useMachine(
    qrCode.machine({
      id: createUniqueId(),
      value: "https://github.com/chakra-ui",
    }),
  )

  const api = createMemo(() => qrCode.connect(state, send, normalizeProps))

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

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

  const controls = useControls(qrCodeControls)

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

  const api = computed(() => qrCode.connect(state.value, send, 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

To set the value of the QR code, pass the value property to the machine.

const [state, send] = useMachine(
  qrCode.machine({
    // ...
    value: "https://example.com",
  }),
)

Setting the correction level

Error correction allows for the QR code to be blocked or resized while still recoganizable. 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 [state, send] = useMachine(
  qrCode.machine({
    value: "...",
    encoding: { ecc: "H" },
  }),
)

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

Adding an overlay logo

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, you can use the api.getDataURL method.

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

Styling guide

Earlier, we mentioned that each QR code part has a data-part attribute added to them to select and style them in the DOM.

[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 value to encode.
• idsPartial<{ root: string; frame: string; }>The element ids.
• encodingQrCodeGenerateOptionsThe qr code encoding options.
• 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.