# Live QR

> A QR code that re-issues itself in place: only the tiles that change turn over, an expired code becomes its Refresh button, and a scan draws a check from its own tiles.

A QR code in a product is usually a static image, and when its link changes (a new amount, a fresh sign-in token) it blinks out and pops back, so nobody can tell whether the code on screen is the current one. Live QR is drawn tile by tile from its own encoder. When the value changes, the code never blanks: only the tiles that differ turn over, in a wave that runs out from the three eyes, and while a tile is edge-on it shows your colour, so a new code reads at a glance. Type fast and each tile simply turns on to the newest face; nothing flickers back. An expired code sinks to a faint grain from the middle out and becomes its own Refresh button, so a stale code can’t be scanned by mistake. When your server says the code was scanned, the code clears and its own tiles fly in from all around to draw a check, in stroke order. It encodes any text in byte mode (UTF-8), versions 1 to 40, at the four error-correction levels, with no package.

## Install

```bash
npx shadcn@latest add https://hairlineui.com/r/live-qr.json
```

Needs React 19, Tailwind CSS v4 and shadcn/ui theme variables (any style, light and dark). Icons from lucide-react.

- npm: `lucide-react`
- Hairline UI components it needs (the CLI installs them too): `status-button`, `text-morph`
- Docs and live preview: https://hairlineui.com/ui/live-qr
- Registry item (source): https://hairlineui.com/r/live-qr.json

## Usage

```tsx
import { LiveQR } from "@/components/live-qr";

<LiveQR value="https://pay.example.com/r/7Q4M?amount=12.00" label="Scan to pay" />
```

## Sign in with your phone

The server issues a short-lived token and reports when a phone has scanned it; the code expires, refreshes and confirms in place.

```tsx
"use client";
import * as React from "react";
import { LiveQR, type LiveQRStatus } from "@/components/live-qr";

export function PhoneSignIn() {
  const [token, setToken] = React.useState<{ id: string; expiresAt: number } | null>(null);
  const [status, setStatus] = React.useState<LiveQRStatus>("live");

  const issue = React.useCallback(async () => {
    const res = await fetch("/api/qr-login", { method: "POST" });
    if (!res.ok) throw new Error("Couldn’t get a code");
    setToken(await res.json());
    setStatus("live");
  }, []);

  React.useEffect(() => {
    void issue();
  }, [issue]);

  // Ask the server whether a phone has scanned it, and expire it on time.
  React.useEffect(() => {
    if (!token || status !== "live") return;
    const poll = window.setInterval(async () => {
      const res = await fetch(`/api/qr-login/${token.id}`);
      const { scanned } = await res.json();
      if (scanned) setStatus("scanned");
    }, 1500);
    const expire = window.setTimeout(() => setStatus("expired"), token.expiresAt - Date.now());
    return () => {
      window.clearInterval(poll);
      window.clearTimeout(expire);
    };
  }, [token, status]);

  return (
    <LiveQR
      value={token ? `https://example.com/login/qr/${token.id}` : ""}
      status={status}
      onRefresh={issue}
      label="Scan with your phone to sign in"
    />
  );
}
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` | `string` | – | What the code holds: a link, a payment request, an otpauth:// secret, any text. An empty string shows no code. |
| `status` | `"live" \| "expired" \| "scanned"` | `"live"` | Expired dims the code and shows Refresh; scanned draws the check. |
| `onRefresh` | `() => Promise<unknown> \| void` | – | Runs from the Refresh button on an expired code. Throw or reject to say Try again. Without it, the code just says it has expired. |
| `level` | `"L" \| "M" \| "Q" \| "H"` | `"M", or "H" with a logo` | Error correction: how much of the code can be covered or damaged and still scan. |
| `logo` | `ReactNode` | – | A mark in a clear square in the middle, drawn in the code’s ink. |
| `label` | `string` | `"QR code"` | What the code is, for screen readers, e.g. “Scan to pay Kept”. |
| `size` | `number` | `224` | Width in px; it shrinks with its container. |
| `color` | `string` | `"var(--primary)"` | The turning tiles and the check: any CSS colour. |
| `labels` | `{ refresh, refreshing, expired, scanned }` | – | The words on the button and the announcements. |

## States

- **arrive**: The first time it’s on screen the three eyes open from 55% with a slight overshoot (460ms), then every dark tile turns over from blank in a wave that runs out from the eyes, about 300ms across the code.
- **re-issue**: A new value: tiles that differ turn on a spring (about 250ms each), staggered by distance from the nearest eye. A tile turns about the axis facing away from that eye and shows your colour while it’s edge-on. A tile already turning when another change arrives turns on to the newest face instead of back.
- **grow**: When a longer value needs a bigger grid, the old code fades out over 200ms while the new one arrives.
- **expired**: The tiles shrink to 45% and fade to a faint grain from the middle out (380ms), the eyes dim, and the Refresh button rises out of a 4px blur in the middle. Refreshing shows Refreshing; a rejected refresh says Try again.
- **back to live**: The tiles grow back in the same wave as the new code turning over, so the fresh code arrives in one motion.
- **scanned**: The eyes close and the other tiles sink from the middle out (260ms) while tiles from all around the code fly in on a thrown curve (470ms each, staggered over 320ms in stroke order) and settle in your colour as a check. Back to live, they fly home.
- **reduced motion**: No turning, sinking or flying: each state is drawn in place.

## What it handles

A QR image that swaps when its link changes leaves people unsure which code is current, and an expired one still looks scannable.

- **Its own encoder**: Any text in byte mode, versions 1 to 40, levels L, M, Q and H, the best of eight masks; no dependency.
- **Changes in place**: Only the tiles that differ turn over, in a wave from the eyes, so a new code reads as new.
- **Steady grid**: A value that grows by a character keeps the same grid size, so the code doesn’t jump while you type.
- **Expired is unscannable**: The tiles sink to a grain and the code becomes the Refresh button; your onRefresh runs from it.
- **Scanned you can see**: Set status to scanned and the code’s own tiles draw a check, so the person knows to look at their phone.
- **A logo that still scans**: Pass logo and it sits in a clear square in the middle, with error correction raised to H.

## Replaces

a QR code package, a QR image endpoint, an expired-code overlay, a scanned confirmation, a refresh button

## Where it fits

- **Payment requests**: A code for a link with the amount in it, re-issued as the amount changes.
- **Sign in with your phone**: A short-lived login code that expires, refreshes and shows when the phone has it.
- **Two-factor setup**: The otpauth:// secret an authenticator app scans.
- **Continue on phone**: Hand a checkout, a document or an invite from desktop to phone.

## Notes

- The code is drawn dark on light in both themes (the plate takes your foreground colour in dark mode), because many scanners can’t read a light-on-dark code. A quiet zone of three modules sits inside the plate.
- The canvas is an image named by label. Expired and Scanned are announced politely from a status region outside it; a re-issue isn’t announced, so typing an amount stays quiet. The Refresh button is the only thing in the tab order, and only while the code is expired.
- One canvas draws every tile; each turning tile has its own spring and only ever turns forward. The frame loop sleeps once nothing moves, and the theme’s colours are read again when the theme changes.
- The encoder is plain TypeScript in live-qr-encode.ts, which installs with it, and was checked by decoding its output with an independent reader at all four levels and across versions. Installs Status button. With reduced motion every state is drawn in place.

License: MIT (https://hairlineui.com/license#components)
