API reference

Entry points

QRCodeProps

<QRCode> also forwards a ref to the <svg> element and passes through any other SVG attribute, such as id, onClick or data-*. toSVGString reads only the props above.

DotStyle

CornerOptions

interface CornerOptions {
  dot?: {
    style?: 'square' | 'rounded' | 'circle'; // inner 3×3 block
    color?: string;
  };
  square?: {
    style?: 'square' | 'rounded' | 'extra-rounded' | 'circle'; // outer 7×7 ring
    color?: string;
  };
}

When corner.square.style is 'extra-rounded' and corner.dot.style is unset, the dot defaults to 'rounded'. When corner.square.style is 'circle', the dot defaults to 'circle'.

LogoOptions

interface LogoOptions {
  src?: string;        // https, relative path, blob:, or data:image/… URI
  element?: ReactNode; // takes priority over src when both provided
  size?: number;       // 0–1 relative to max safe area; ECL auto-picked; default 0.4
  aspectRatio?: number; // width / height; measured from src when omitted
  margin?: number;     // space between logo and cleared area, in modules; default 0
  hideDots?: boolean;  // clear dots behind logo area; default true
  radius?: number;     // corner radius, 0 (square) to 1 (fully rounded); default 0
}

ECL is auto-picked based on size: ≤ 0.25 → L (≤ 15% width), ≤ 0.44 → M (≤ 20%), ≤ 0.69 → Q (≤ 25%), ≤ 1.0 → H (≤ 30%). If errorCorrectionLevel is set explicitly, the size is clamped to that ECL's safe limit. Aspect ratio is auto-detected: landscape logos get a proportionally reduced height so they never overflow the QR.
hideDots uses an SVG mask, so transparent backgrounds are fully supported.
radius is a share of the logo's shorter side, so 1 turns a square logo into a circle. It clips src and element alike.

Security: javascript: and non-image data: URIs in src are silently rejected. Never pass unsanitised user input as element, which renders verbatim inside <foreignObject>.

QROptions

interface QROptions {
  errorCorrectionLevel?: 'L' | 'M' | 'Q' | 'H'; // default: 'M'
  version?: number; // 1–40, auto by default
}

Export Helpers

import { toSVGString, toDataURL } from '@ttsalpha/qrcode';

// From a React Server Component or any server-only module, import the
// entry with no client boundary:
// import { toSVGString } from '@ttsalpha/qrcode/server';

// Server-side SVG string, no DOM, no React
const svg = toSVGString({ value: 'https://example.com', size: 512 });

// PNG data URL via Canvas (browser-only)
const png = await toDataURL({ value: 'https://example.com', size: 512 });

// Two-times pixel density for print or retina
const png2x = await toDataURL(
  { value: 'https://example.com', size: 512 },
  { scale: 2 },
);

// JPEG with quality
const jpg = await toDataURL(
  { value: 'https://example.com', size: 512 },
  { format: 'jpeg', quality: 0.9 },
);

// Download link
const link = document.createElement('a');
link.href = await toDataURL({ value: 'https://example.com' });
link.download = 'qrcode.png';
link.click();

toSVGString takes the props in the table above and returns a static SVG markup string, useful for SSR, saving to a database, or copying to clipboard. It renders without React, so logo.element throws; pass logo.src instead, or render <QRCode>.
Import from @ttsalpha/qrcode/server inside a React Server Component. The root entry is a client boundary, so every export of it becomes a client reference there.
@ttsalpha/qrcode/core exports the same toSVGString, typed without React. It is plain JavaScript, so React Native apps import it from there.
toDataURL is browser-only (requires the Canvas API). JPEG automatically fills a white background when backgroundColor is 'transparent'.

React Native and Expo

@ttsalpha/qrcode/native draws the same symbols as <QRCode> with react-native-svg, which is an optional peer dependency. Install it with npx expo install react-native-svg on Expo, or pnpm add react-native-svg otherwise.

import { QRCode } from '@ttsalpha/qrcode/native';

export default function Pay() {
  return (
    <QRCode
      value="https://example.com"
      size={240}
      dotStyle="rounded"
      corner={{ square: { style: 'extra-rounded' } }}
      logo={{ src: require('./logo.png'), radius: 0.3 }}
      onError={(error) => console.warn(error.message)}
    />
  );
}

Requirements: react-native-svg 14 or newer, React Native 0.75 or newer (the encoder uses the global TextEncoder), and a Metro that resolves package exports, which is the default from React Native 0.79 and Expo SDK 53. On an older setup, set config.resolver.unstable_enablePackageExports = true in metro.config.js.

value, size, margin, dotStyle, dotColor, backgroundColor, corner and qr work exactly as in QRCodeProps. Everything else an <Svg> accepts (style, testID, onLayout, …) is passed through. There is no className, and idPrefix is not needed.

NativeLogoOptions

interface NativeLogoOptions {
  src?: string | number; // a URL, or a local asset from require('./logo.png')
  svg?: string;          // the logo as SVG markup; wins over src
  size?: number;         // as in LogoOptions
  aspectRatio?: number;  // native cannot measure an image: square unless set
  margin?: number;       // as in LogoOptions
  hideDots?: boolean;    // as in LogoOptions
  radius?: number;       // as in LogoOptions
}

For a vector logo, pass its markup as svg rather than as src. Native cannot measure an image, so a logo is square unless you set aspectRatio.

Getting an image

import Svg from 'react-native-svg';

const ref = useRef<React.ElementRef<typeof Svg>>(null);

<QRCode ref={ref} value="https://example.com" />;

ref.current?.toDataURL((base64) => {
  // PNG, base64 without the data: prefix
});

<QRCode> forwards its ref to the Svg, which can rasterise itself. For an SVG string, to save an .svg file or render with SvgXml, import toSVGString from @ttsalpha/qrcode/core.

Not supported on native

logo.element: there is no <foreignObject>, so a warning is logged in development and the logo is skipped; use logo.src or logo.svg. The toDataURL(props) helper needs a canvas, so use the ref above. className and web-only <svg> props such as onClick and data-*.

Core

@ttsalpha/qrcode/core is the part every renderer is built on: plain JavaScript with no React and no DOM, so it runs on a server, in a worker and in React Native. buildQR(props) returns a QRGeometry in a square coordinate space of viewBox units, ready to draw with any renderer.

import { buildQR } from '@ttsalpha/qrcode/core';

const geometry = buildQR({ value: 'https://example.com', size: 256 });

interface QRGeometry {
  size: number; // rendered width and height
  viewBox: number; // side of the square viewBox
  ecLevel: 'L' | 'M' | 'Q' | 'H'; // after logo sizing
  background?: string; // absent when transparent
  modules?: { d: string; fill: string }; // all data modules, one path
  finders: Array<{
    square: { d: string; fill: string; fillRule?: 'evenodd' }; // 7×7 ring
    dot: { d: string; fill: string }; // 3×3 dot
  }>;
  clear?: { x: number; y: number; width: number; height: number }; // cut out of the dots
  logo?: { x: number; y: number; width: number; height: number; radius: number; src?: string };
  warnings: string[];
}

Draw the background, then modules and finders with clear knocked out of them, then logo. The props are those of QRCodeProps minus the React-only ones. logo.custom: true reserves the logo area without a src, for a logo the renderer draws itself. Invalid input throws a RangeError or TypeError, as in <QRCode>.

HTTP API — /qr

Render a QR straight from a URL, no install needed. Paste the link into any <img> tag, email, or doc. Pick the format with format=svg|png|jpg and pass colors as plain hex (color=14b8a6). The quickest way to build one: configure it in the playground and hit “Copy link”. Output is deterministic per URL and cached on the CDN.

<!-- SVG (default) -->
<img src="https://qrcode.ttsalpha.com/qr?data=https://example.com" alt="QR code" />

<!-- PNG output -->
<img src="https://qrcode.ttsalpha.com/qr?data=Hello&dot=rounded&color=14b8a6&format=png" />

<!-- With a center logo -->
<img src="https://qrcode.ttsalpha.com/qr?data=https://example.com&logo=https://example.com/logo.png" />