QuestPDF Companion: Live PDF Preview and Hot Reload

Iterating on a PDF layout by regenerating the file, opening it in a viewer, and squinting at the diff is slow. QuestPDF's Companion app removes that loop: it renders your document live and refreshes as you change the code. This guide covers what the Companion is, how to wire up hot reload, what it shows that a flat PDF cannot, and where it fits in a real workflow. It requires QuestPDF 2024.10 or newer; everything here targets 2026.5.0.

What is the QuestPDF Companion app?

The Companion is a desktop previewer that pairs with your .NET project. Instead of writing a PDF to disk on every change, you point your document at the Companion and it displays the rendered result, refreshing when you re-run. It also surfaces layout information a flat PDF does not, which is what makes it more than a viewer. The app is a separate download that runs alongside your IDE.

How do I preview a document live?

Build the document as usual, then call the Companion method instead of (or alongside) GeneratePdf:

using QuestPDF.Fluent;
using QuestPDF.Helpers;
using QuestPDF.Infrastructure;

QuestPDF.Settings.License = LicenseType.Community;

var document = Document.Create(container =>
{
    container.Page(page =>
    {
        page.Size(PageSizes.A4);
        page.Margin(2, Unit.Centimetre);
        page.Content().Text("Edit me and re-run to see the preview update.");
    });
});

// Streams the document to the Companion app (default HTTP port 12500)
document.ShowInCompanion();

With the Companion app running, each execution updates the preview. You adjust margins, spacing, or table widths and see the effect immediately without writing a file to disk.

Wiring up hot reload

Live preview becomes a tight loop with hot reload. Start your application in DEBUG mode with "Hot Reload on Save" enabled, and on every file save the document refreshes in the Companion without a full restart. The communication runs over a local HTTP port (12500 by default), which you can override by passing a port to ShowInCompanion(port) if something else is using it. The features page documents the supported workflow.

What the Companion shows you

This is where it earns its place over a PDF viewer. The Companion can:

• Highlight the visible layout structure, so you see how containers are sized and nested.
• Show the attributes of a selected element (padding, size, alignment).
• Present the document as a tree, so you can navigate the hierarchy instead of scrolling pages.
• Render in light or dark mode to match your environment.

For debugging an overflow or a spacing bug, seeing the layout tree is far faster than inferring the problem from a generated page.

ShowInCompanion and the older previewer

If you are on an older codebase you may see ShowInPreviewer() instead. The Companion is the current tool, and ShowInCompanion() is its method, available from QuestPDF 2024.10 onward. If the method is missing, your package version predates the Companion; upgrade before wiring it up. The repository for the app lives at github.com/QuestPDF/QuestPDF.Companion.

Why it speeds up the inner loop

Three concrete wins:

• No file churn. You are not generating and opening output.pdf dozens of times.
• Faster layout debugging. Overflow and spacing problems are visible directly, not inferred from a static page.
• Tighter feedback. Change code, save, look. The cycle drops from many seconds to near-instant for small edits.

It is a development-time tool. Production code still calls GeneratePdf (or generates to a stream); the Companion is for the authoring phase only.

From preview to production output

The Companion is a development aid; production code generates the file or bytes directly from the same document definition you previewed. The switch is one call:

// Development: live preview in the Companion
document.ShowInCompanion();

// Production: generate bytes, or GeneratePdf("file.pdf") for a file
byte[] pdf = document.GeneratePdf();

Keep the ShowInCompanion() call behind a debug check or remove it before shipping; the production path never touches the Companion.

An HTML-first preview loop

The Companion is the right tool for code-first layouts. If your document is built from HTML and CSS, the Companion does not apply because QuestPDF does not accept HTML input.

IronPDF is a commercial library that renders HTML files through a Chromium engine, which means your browser stays the live preview tool. It converts an HTML file to PDF using Chromium, so the file you tweak in the browser is the same one that becomes the PDF. A workflow using it looks like this:

using IronPdf;

IronPdf.License.LicenseKey = "YOUR-LICENSE-KEY";

var renderer = new ChromePdfRenderer();

// Render the very file you have open in the browser
var pdf = renderer.RenderHtmlFileAsPdf("preview.html");

pdf.SaveAs("preview.pdf");

This produces a PDF from the HTML file on disk. The trade-offs compared to QuestPDF plus the Companion:

• Your browser remains the live preview tool with no separate previewer to install.
• It requires a paid commercial license.
• The Chromium engine adds over 100 MB to the deployment footprint.
• On Linux, native dependencies (libgdiplus, system fonts) must be present.

For fluent C# documents, QuestPDF and the Companion carry none of those costs: pure managed .NET, free under the community threshold, no Chromium layer.

Common Companion pitfalls

• App not running. ShowInCompanion() streams to the desktop app; start the app first or nothing appears.
• Not in DEBUG with hot reload. The live refresh depends on "Hot Reload on Save" in a DEBUG run.
• Package too old. ShowInCompanion() needs QuestPDF 2024.10+; older versions only have ShowInPreviewer().
• Port in use. The default 12500 can clash; pass an explicit port to ShowInCompanion(port).
• Shipping it. Do not leave ShowInCompanion() in production code paths; it is a development aid.

FAQ

Is the Companion app required to use QuestPDF?
No. It is an optional development aid; QuestPDF generates PDFs without it.

Does the Companion affect production?
No. You call ShowInCompanion() only while developing; production code generates the PDF directly.

Does it hot reload on every keystroke?
It refreshes when the document is rendered again, which with "Hot Reload on Save" means on each save.

Which version do I need?
QuestPDF 2024.10 or newer for ShowInCompanion(); the app itself is a separate download.

Is the Companion covered by the Community license?
Yes, the Community tier (free under the $1M revenue threshold) includes the development tooling; confirm specifics on the project's site.

What does your current PDF iteration loop look like?

Are you regenerating a file and opening it in a viewer on every change, or have you found a faster setup? I'd like to know what friction points people hit before finding the Companion.

Takeaways

For code-first .NET PDF work, the QuestPDF Companion is the most practical development tool available: no license cost, no extra runtime dependency, and a layout tree that makes spacing bugs obvious. Call ShowInCompanion(), run in DEBUG with hot reload, and iterate without regenerating files by hand. The only time it is not your fastest loop is when the document is HTML-first, where a browser plus an HTML renderer is the natural fit instead.

If your pipeline is HTML-first, try IronPDF free for 30 days to see if it fits your templates.