---

title: QR code description: Display a scannable QR code from text content

QR code

QRCodeRenderable displays text or URLs as a QR Code Model 2 symbol. It uses half-block cells to keep the symbol square in terminal cell geometry.

For module matrices, terminal strings, SVG, and raw bytes, use the standalone QR encoder. The same package exports this encoder. It also supports explicit segments, ECI, GS1/FNC1, and structured append.

Availability

Install the QR code package separately:

bun add @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",
  quietZone: 4,
  scale: 2,
})

renderer.root.add(qr)

React JSX

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

registerQRCode()

const renderer = await createCliRenderer()
createRoot(renderer).render(
  <qr-code
    content="https://opentui.com/docs"
    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"
    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 a 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.

The content OPENTUI and a four-module quiet zone fit a version-one symbol:

    █▀▀▀▀▀█ ▀█▄▀█ █▀▀▀▀▀█
    █ ███ █ ▀ ▀▀█ █ ███ █
    █ ▀▀▀ █ ▀ ▀█  █ ▀▀▀ █
    ▀▀▀▀▀▀▀ █ ▀▄█ ▀▀▀▀▀▀▀
    ▄▄ ▄ ▀▀▄ █ ▄▀▄▀▄█▄█▄█
    ▄█▀▀█▄▀ █ ▀▀▀▄▄█ ▀█▄
     ▀  ▀ ▀▀█  ██▄ ▀▀ ▀ ▀
    █▀▀▀▀▀█ ▄▄▀ ▀▀▄ ▀█▄█▀
    █ ███ █  ▀███▀█ ▀▄▀
    █ ▀▀▀ █  █ ▀▀▀▀▀█▄▀▀█
    ▀▀▀▀▀▀▀  ▀ ▀   ▀ ▀▀

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",
  fallbackContent: "Resize for QR",
  fallbackColor: "#94a3b8",
})

Fallback painting currently indexes UTF-16 code units and writes one cell for each unit. Use one-cell Basic Multilingual Plane characters. Emoji, joined or combining graphemes, and wide characters can split, disappear, or misalign.

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

Related APIs

Use the QR encoder when you need a matrix or serialized output without a renderable. See Image for decoded image display.