QR Code

Display text or URLs as scannable standard QR Codes in the terminal. QRCodeRenderable renders QR Code Model 2 modules with half-block cells so the symbol stays square in terminal character geometry.

Install the QR code package separately:

bun install @opentui/qrcode

Basic Usage

Renderable API

import { createCliRenderer } from "@opentui/core"
import { QRCodeRenderable } from "@opentui/qrcode"

const renderer = await createCliRenderer()

const qr = new QRCodeRenderable(renderer, {
  id: "docs-link",
  content: "https://opentui.com/docs/getting-started",
  quietZone: 4,
  scale: 2,
})

renderer.root.add(qr)

React JSX

import { createRoot } from "@opentui/react"
import { registerQRCode } from "@opentui/qrcode/react"

registerQRCode()

createRoot(renderer).render(
  <qr-code
    content="https://opentui.com/docs/getting-started"
    quietZone={4}
    scale={2}
    foregroundColor="#111827"
    backgroundColor="#ffffff"
  />,
)

Solid JSX

import { render } from "@opentui/solid"
import { registerQRCode } from "@opentui/qrcode/solid"

registerQRCode()

render(() => (
  <qr_code
    content="https://opentui.com/docs/getting-started"
    quietZone={4}
    scale={2}
    foregroundColor="#111827"
    backgroundColor="#ffffff"
  />
))

Sizing

QRCodeRenderable measures itself from the encoded QR version, the quiet zone, and the requested scale. The default fit: "contain" lets the QR code shrink to fit constrained parents while preserving a valid square module grid.

const qr = new QRCodeRenderable(renderer, {
  content: "opentui.com",
  quietZone: 4,
  scale: 2,
  fit: "contain",
})

Use fit: "none" when you want the configured scale to be the only rendered size.

quietZone must be at least 4 modules for standard QR Code. OpenTUI validates the matrix and quiet-zone geometry, but scanner reliability still depends on terminal font, cell aspect ratio, display contrast, and camera conditions.

Fallback Content

When a container is too small to render even a scale-1 QR code, show fallback text instead of an empty area:

const qr = new QRCodeRenderable(renderer, {
  content: "https://opentui.com/docs/getting-started",
  fallbackContent: "Resize for QR",
  fallbackColor: "#94a3b8",
})

Error Correction

Set errorCorrectionLevel with the QR package error correction enum:

import { ErrorCorrectionLevel, QRCodeRenderable } from "@opentui/qrcode"

const qr = new QRCodeRenderable(renderer, {
  content: "opentui.com",
  errorCorrectionLevel: ErrorCorrectionLevel.H,
})

Higher error correction improves resilience but can increase the QR version and rendered size for longer content.

Properties