How to Generate QR Codes in Quarkus Like a Pro

Learn how to generate, stream, and render QR codes in your apps with just a few lines of code.

Apr 11, 2025

QR codes are everywhere: Printed on packaging, embedded in emails, displayed on websites, or scanned for check-ins. In modern applications, generating QR codes dynamically improves user experience, automates workflows, and reduces friction in cross-device interactions.

In this tutorial, you’ll learn how to generate QR codes in a Quarkus application using the Quarkus QR Code extension backed by QR Code Generator, an open-source barcode generation library.

I’ll walk through:

QR code generation concepts and use cases
Downloading a QR-Code
Streaming a QR code as a Base64 image
Rendering QR codes server-side with Qute templates
Customizing QR code size, encoding, margin, and error correction

Why QR Codes?

QR (Quick Response) codes are two-dimensional barcodes that store data in a matrix of black and white squares. Unlike traditional 1D barcodes, which can only hold a small amount of numeric data, QR codes can encode several kilobytes of information — including URLs, UUIDs, geo-coordinates, contact information, or even entire JSON documents. Their structure allows for high data density and resilience through error correction, making them ideal for real-world environments where scratches, dirt, or low-quality printing may be an issue. QR codes are also universally scannable using smartphone cameras, enabling frictionless user experiences across mobile and desktop platforms without requiring proprietary apps or hardware.

From a backend developer’s perspective, QR codes bridge the gap between physical and digital workflows. You can generate them dynamically to represent session tokens, download links, one-time passwords, or payment payloads. They’re commonly used in logistics (package tracking), ticketing (event access), retail (product detail links), payments (wallet integration), and authentication (MFA or device pairing). They also shine in scenarios where users must transfer data across devices — for example, scanning a QR code on a desktop app to authenticate via a mobile phone. For developers building with Quarkus, adding QR code generation to a REST API or rendering it in a template can turn any service into a touchpoint between systems.

Getting Started

Create a new Quarkus project:

mvn io.quarkus.platform:quarkus-maven-plugin:3.21.2:create \
  -DprojectGroupId=org.acme \
  -DprojectArtifactId=qr-code-demo \
  -DclassName="org.acme.qr.QRCodeResource" \
  -Dpath="/qr" \
  -Dextensions="quarkus-qrcodegen, rest, quarkus-rest-qute"
cd qr-code-demo

This adds:

quarkus-qrcodegen: the Quarkiverse extension that integrates with QR Code Generator
rest: to expose QR code generation as a REST endpoint
quarkus-rest-qute: the server-side templating engine for HTML rendering with REST features

The Quarkus QR code extension supports multiple libraries depending on the use case and extension. This tutorial uses QR Code Generator.

1. Generate a QR Code

Let’s start by creating a QR code with QR Code Generator.

package org.acme.qr;

import java.util.Objects;

import io.nayuki.qrcodegen.QrCode;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class QRCodeService {
   
    public QrCode generateQrCode(String data) {
       QrCode qr = QrCode.encodeText(data, QrCode.Ecc.LOW);  
       return qr;
   }

public static String toSvgString(QrCode qr, int border, String lightColor, String darkColor, boolean download) {
	
    //...
}

public static String toBase64Image(QrCode qr, int scale, int border, int lightColor, int darkColor) {
    //...
}

This does little more than just using the library to return a qr code object. We also need to render this into something more useful to be displayed on the web. I spare you the toSvgString helper method here but you find it on my Github repository. While we are here, let’s also add the toBase64Image.

Download QR Code as SVG

Let’s download the QR-Code as SVG.

@Path("/qr")
public class QRCodeResource {

    @Inject
    QRCodeService qrCodeService;


    @GET
    @Path("/download/svg")
    @Produces(MediaType.APPLICATION_SVG_XML)
    public Response getQrCodeSVGDownload(@QueryParam("text") String text) {
        if (text == null || text.isBlank()) {
            return Response
                .status(Status.BAD_REQUEST)
                .entity("QR Code data cannot be null or empty")
                .type(MediaType.TEXT_PLAIN)
                .header("Content-Disposition", "attachment; filename=qrcode.svg")
                .build();
        }
        String svg = QRCodeService.toSvgString(qrCodeService.generateQrCode(text), 4, "#FFFFFF", "#000000", true);
        return Response.ok(svg)
            .header("Content-Disposition", "attachment; filename=qr-code.svg")
            .build();
    }

Hitting the endpoint with http://localhost:8080/qr/download/svg?text=https://quarkus.io prompts you to download a file: qr-code.svg.

Now we need to make sure we can also use this directly in HTML pages.

Render QR Code in HTML (with Quarkus Qute)

Now let’s use Qute to return an HTML page with the QR code embedded.

Create Template

Create a file at src/main/resources/templates/qrcode.html:

<!DOCTYPE html>
<html>
<head>
    <title>QR Code Rendered</title>
</head>
<body>
    <h1>QR Code</h1>
    <img src="data:image/png;base64, {base64Image}" alt="QR Code"/>
</body>
</html>

Add a Render Endpoint

@Path("/some-page")
public class QRCodePage {

    @Inject
    QRCodeService qrCodeService;


    private final Template qrcode;

    public QRCodePage(Template qrcode) {
        this.qrcode = requireNonNull(qrcode, "page is required");
    }

    @GET
    @Produces(MediaType.TEXT_HTML)
    public TemplateInstance get(@QueryParam("url") String url) {
        return qrcode.data("base64Image", QRCodeService.toBase64Image(qrCodeService.generateQrCode(url), 4, 4, 0x000000, 0xFFFFFF));
    }

}

This endpoint takes a url parameter as string and creates a new barcode and encodes it in bas64.

Visit:

http://localhost:8080/some-page?url=https://quarkus.io

You’ll see an HTML page with the rendered QR code.

4. Customize the QR Code

You can control the look and feel of the generated barcode in various ways. Take a look at the project website for details.

`5.`Container Considerations

We’ve only generated QR-Code data for on the fly usage as embedded images or download. If you need to generate and save files, make sure to remember doing this in a save way for containerized environments.

Avoid writing files to /home or the app directory
Prefer /tmp for temp files, or mount a writable volume
For stateless apps (e.g., REST), use Base64 or streamed image responses instead of writing to disk

Conclusion

QR code generation is a simple yet powerful capability you can seamlessly integrate into any Quarkus application. With the Quarkus QR Code extension powered by the QR Code Generator library, you can generate high-quality QR codes on demand. Whether you’re downloading them as a file, embedding them in HTML as Base64-encoded images. This tutorial showed how to implement both approaches, including a Qute-based server-side rendering example ideal for email templates and confirmation pages. With just a few lines of code, you can build secure, scannable experiences that enhance everything from document downloads to check-in flows and mobile interactions. The ability to customize size, margin, and error correction makes this solution flexible for both high-volume APIs and branded visual experiences. Whether you’re working on authentication, logistics, payments, or device setup, this extension gives you the tools to generate reliable, production-grade QR codes in a cloud-native way.

Find the full source code on my GitHub repository.