How to Embed a QR Code on a Web Page Properly
Embedding a QR code on a web page sounds trivial, but a careless embed fails in ways that are easy to miss: the image stretches and softens, screen readers announce a meaningless filename, the link wraps nothing, or the image is hotlinked from a URL that disappears. A good embed does four things. It points at a stable image URL you control, it sets a width that matches the layout without distorting the square, it carries alt text that tells a screen-reader user what the code does, and it optionally wraps the image in a link to the same destination, so desktop visitors who cannot scan can still click through.
Alt text deserves more care than it usually gets. A QR code is not decorative, so an empty alt attribute is wrong, and a filename such as qr-code-final-v3.png is worse. The alt text should say what scanning the code achieves: QR code: scan to visit our site, or QR code: scan to view the menu. That single sentence makes the embed usable for someone who cannot see the pattern, and it also gives search engines a truthful description of the image. Keep it to one short sentence; the surrounding page copy can carry the details.
Width and aspect ratio are the two technical details that decide whether the embedded code stays scannable. Set only the width and let the height follow automatically, so the code stays perfectly square. Forcing both a width and a height, or stretching the image with CSS to fill a container, turns the square modules into rectangles and makes scanning unreliable. On responsive pages, the max-width rule in the generated code keeps the image from overflowing small screens while preserving the square. If the embed must sit in a fixed-size card, size the card to the image, not the image to the card.
Choose the embed format from the job. A plain img tag is right for most pages: a blog post, a landing page, a footer. A figure with a caption is right when the code needs a visible label under it, such as Scan to view the menu, because the caption is visible to everyone, not just screen readers. An iframe is rarely the best choice for a QR image; it isolates the image from the page, adds loading overhead, and can be blocked by strict content-security policies. Use iframe only when you are embedding a whole hosted page that happens to contain a code, not the image itself.
Finally, treat the image URL as a commitment. An embed that points at a temporary upload, a staging server, or a link shortener you do not control will break silently, leaving a broken-image icon where the code used to be. Host the QR image on your own domain, at a URL you intend to keep, and check the embed after publishing by loading the page in a fresh browser tab and scanning the code off the screen. If the destination ever changes, update the code image and the link wrapper together, because a clickable link that points to the old destination while the code points to the new one is a contradiction that confuses visitors and search engines alike.