# How to embed a QR code in HTML

> Three ways: an img tag whose src is the UseQR API URL (one line, nothing to host), the /q/{data}.png direct path for markdown and READMEs, or inline SVG pasted into the page for zero external requests. Always set width and height, meaningful alt text, and loading="lazy" for below-the-fold codes.

Source: https://useqr.app/docs/how-to/how-to-embed-a-qr-code-in-html · Last reviewed 2026-08-21 · UseQR is free forever, no signup.

---

## 1. The img tag: simplest

```html
<img src="https://useqr.app/api/v1/qr?data=https%3A%2F%2Fexample.com%2Fapp&size=300"
     width="150" height="150"
     alt="Scan to open the app download page"
     loading="lazy">
```

The [keyless API](/docs/developers/free-qr-code-api-no-key) returns the PNG directly.
Notes that matter:

- **URL-encode the payload**, an unencoded `&` in your data splits the query string and
  silently truncates the code's contents.
- **Set `width` and `height`** to prevent layout shift, and keep them equal, a
  rectangular rendering of a square code may fail to scan.
- **`loading="lazy"`** for below-the-fold codes saves the request until needed.
- `size=300` with `width="150"` gives 2× pixel density for high-DPI displays.

## 2. The /q/ path, for markdown and READMEs

Markdown image syntax cannot always carry long query strings comfortably, so UseQR also
serves codes at a bare path. Everything between `/q/` and `.png`, URL-encoded, is the
payload:

```markdown
![Scan to open the demo](https://useqr.app/q/https%3A%2F%2Fexample.com%2Fdemo.png)
```

Drops into GitHub READMEs, documentation sites, and
[anything that renders markdown](/docs/how-to/how-to-make-a-qr-code-in-notion).

## 3. Inline SVG: zero external requests

For pages that must not depend on a third-party request (offline apps, privacy-strict
sites, emails where remote images are blocked) paste the code's SVG markup straight into
the document:

```html
<figure role="img" aria-label="Scan to open example.com">
  <!-- paste the downloaded SVG here -->
</figure>
```

Generate the code, [download the SVG](/docs/how-to/how-to-make-a-qr-code-svg), open it in
a text editor and paste. The file is typically 2–6 KB (smaller than most icons) scales
perfectly with CSS, and renders with **no request to anyone**. This is the strongest
option for payloads you would rather not put in a URL, such as WiFi credentials; the
code was generated client-side and the markup never mentions a third party. To generate
codes at runtime instead, use a JavaScript library: the trade-offs are in
[generating QR codes in JavaScript](/docs/developers/generate-a-qr-code-in-javascript).

## 4. Sizing and styling rules on screen

- **≥ 150 CSS px** displayed, for arm's-length scanning of a monitor; when and where an
  on-screen code makes sense at all is covered in
  [adding a QR code to a website](/docs/how-to/how-to-add-a-qr-code-to-a-website).
- **Preserve the quiet zone**: no CSS that crops it (`overflow:hidden` on a tight
  container), covers it (badges, borders), or tints it. The margin is part of the code.
- **No CSS filters, opacity or transforms** on the image. Anything that lowers edge
  contrast or skews the grid costs scans, and dark-mode `filter: invert()` rules are a
  notorious killer. Handle themes explicitly instead, per
  QR codes on dark-mode sites.
- **Alt text describes the destination and offers the alternative** ("Scan to open
  example.com/app, or use the link below"), not the word "QR code". Full guidance in
  [alt text and screen readers](/docs/design/qr-code-alt-text-and-screen-readers). And
  keep an actual link next to the code for everyone who cannot scan.

## 5. Verify the rendered page

Scan the code off the live page with a phone, and paste the image URL or a screenshot
into the [validator](/validate) to confirm the payload decodes exactly, encoding
mistakes (step 1) are invisible until something decodes them.

## Gotchas

- **CDN and proxy image optimisers** (site builders love them) recompress or resize
  images; a code squeezed through aggressive WebP conversion can lose its edges. Exempt
  the code's path, or inline the SVG.
- **Print stylesheets**: if the page may be printed, ensure the code prints at ≥ 2 cm.
- **CSP-strict sites**: the img route needs `img-src https://useqr.app`; inline SVG needs
  nothing.

Build the code and copy either URL form: [make a QR code](/url?data=https://example.com).

## FAQ

### What is the HTML code to embed a QR code?
An img tag pointing at a QR API: img src="https://useqr.app/api/v1/qr?data=your-encoded-link&size=300" with equal width and height and descriptive alt text. No hosting or key needed.

### How do I embed a QR code without any external request?
Download the code as SVG and paste the markup inline into your HTML. It renders locally, weighs a few kilobytes, scales with CSS, and works offline and in blocked-image contexts.

### How do I put a QR code in a GitHub README?
Use markdown image syntax with the direct path: ![alt](https://useqr.app/q/your-encoded-data.png). The URL-encoded payload sits between /q/ and .png.

### Why does my embedded QR code encode the wrong URL?
Almost always a missing URL-encoding step, an & or # in the payload split the API query string. Encode the data parameter and verify the rendered code with a decoder.

## Try it

- https://useqr.app/url
- https://useqr.app/validate