TerraFluent.Pdf.Reporting · v2.2.1

True PDF files, zero dependencies

A pure managed C# PDF 1.7 writer — invoices, reports, statements, labels, and certificates composed from fluent layout primitives. No native binaries, no headless browser, no third-party packages.

View on GitHub NuGet Getting started

dotnet add package TerraFluent.Pdf.Reporting

Quick start

A complete PDF in one lambda

Page setup, styled header, content column, page-numbered footer — published straight to a PDF that opens in every major viewer. Deterministic, code-first output with no browser engine to babysit.

Targets .NET 8 (LTS), .NET 9, and .NET 10 (LTS)
Built-in Helvetica, Times, and Courier families — no font embedding needed
Metric and imperial units via Unit helpers

using TerraFluent.Pdf.Reporting.Core;
using TerraFluent.Pdf.Reporting.Helpers;

PdfDocument.Create(container =>
{
    container.Page(page =>
    {
        page.Size(PageSize.A4);
        page.Margin(2, Unit.Centimetre);
        page.DefaultTextStyle(s => s.FontSize(11));

        page.Header()
            .Text("My Report").Bold().FontSize(24)
            .FontColor(Color.Blue.Darken2);

        page.Content().Column(col =>
        {
            col.Spacing(8);
            col.Item().Text("Hello, TerraFluent.Pdf.Reporting!");
            col.Item()
               .Margin(6).Background(Color.Grey.Lighten4).Padding(10)
               .Text("Indented callout box").Bold();
        });

        page.Footer().AlignCenter().Text(t =>
        {
            t.Span("Page ");
            t.CurrentPageNumber().FontSize(9);
            t.Span(" / ");
            t.TotalPages().FontSize(9);
        });
    });
})
.PublishPdf("output.pdf");
        

Tables

Tables that paginate themselves

Relative and fixed-width columns, styled header rows, and full decorator support on every cell. Header rows repeat automatically on every continuation page when a table spans multiple pages.

RelativeColumn / ConstantColumn definitions
Backgrounds, padding, borders, and alignment per cell
Material-style Color palette with shade scales

container.Table(table =>
{
    table.ColumnsDefinition(cols =>
    {
        cols.RelativeColumn(4);
        cols.RelativeColumn(1);
        cols.ConstantColumn(70);
    });

    table.HeaderRow(row =>
    {
        row.Cell().Background("#1a4a8a").Padding(6)
           .Text("Description").Bold().FontColor(Color.White);
        row.Cell().Background("#1a4a8a").Padding(6).AlignCenter()
           .Text("Qty").Bold().FontColor(Color.White);
        row.Cell().Background("#1a4a8a").Padding(6).AlignRight()
           .Text("Price").Bold().FontColor(Color.White);
    });

    foreach (var item in lineItems)
    {
        table.Row(row =>
        {
            row.Cell().Padding(6).Text(item.Name);
            row.Cell().Padding(6).AlignCenter().Text(item.Qty.ToString());
            row.Cell().Padding(6).AlignRight().Text($"${item.Price:N2}");
        });
    }
});
        

Barcodes & QR codes

Code 128 and QR, rendered as vectors

Code 128 barcodes with optional human-readable captions, and a full ISO/IEC 18004 QR generator — versions 1–40, error-correction levels L/M/Q/H — drawn as vector rectangles that stay crisp at any zoom.

Custom module and background colours
Configurable quiet zones
Drop them anywhere — columns, rows, even table cells

container.Barcode("SKU-00042-A", width: 260, height: 50,
    hexColor: "#1A3C5E", showCaption: true);

container.QrCode("https://terrafluent.dev/", size: 90,
    level: QrErrorCorrectionLevel.Q);
        

Security

AES-256 encryption by default

Password-protect documents with the PDF 2.0 Standard Security Handler (Revision 6) — SHA-2 key derivation, no MD5 or RC4 in the chain. Legacy AES-128 remains available for very old viewers. Built entirely on System.Security.Cryptography.

User and owner passwords
Fine-grained PdfPermissions flags — print, copy, edit, fill forms
Opens in Acrobat, Chrome, Edge, Firefox, Preview, and more

PdfDocument.Create(container =>
{
    container.Encrypt(new EncryptionOptions
    {
        UserPassword  = "open123",
        OwnerPassword = "admin456",
        Permissions   = PdfPermissions.Print | PdfPermissions.CopyText,
    });

    container.Page(page =>
    {
        page.Size(PageSize.A4);
        page.Content().Text("This PDF is password-protected.").Bold();
    });
})
.PublishPdf("protected.pdf");
        

Navigation

Automatic TOC, bookmarks, and links

A navigable Table of Contents is generated from your H1()–H6() headings by the two-pass layout engine. Add hierarchical PDF bookmarks, clickable hyperlinks, and internal GoTo links between sections.

container.TableOfContents() — placed wherever you call it
Anchor-based bookmarks track rendered content automatically
Hyperlink() and InternalLink() annotations

PdfDocument.Create(container =>
{
    // TOC page is placed first
    container.TableOfContents(p =>
    {
        p.Size(PageSize.A4);
        p.Margin(2, Unit.Centimetre);
    });

    container.Page(page =>
    {
        page.Content().Column(col =>
        {
            col.Item().H1("Chapter 1");
            col.Item().Text("Body text…");
            col.Item().H2("1.1 Details");
        });
    });
}).PublishPdf("output.pdf");
        

Vector graphics

A fluent canvas for drawing

Draw lines, rectangles, rounded boxes, circles, ellipses, Bézier paths, polygons, and grids directly inside any layout slot — perfect for custom charts, dividers, and diagrams, with no imaging library required.

Top-left origin, PDF-point coordinates
Chainable drawing commands
Fills the available width at the height you specify

container.Canvas(120, c =>
{
    c.FillRect(0, 0, 200, 80, Color.Blue.Lighten4);
    c.StrokeRect(0, 0, 200, 80, Color.Blue.Darken2, 1.5);
    c.Line(0, 40, 200, 40, Color.Blue.Medium, 0.5);
});
        

Templates

Branded pages in one call

Five predefined templates — Corporate, Modern, Minimal, Elegant, and Cover — give a full-page background, decorative artwork, header, and footer in a single UseTemplate(...) call, so a document looks designed instead of default. Built from the same public fluent API, so a custom template is just as reachable.

Gradients, background images, and vector page decoration
Customizable via TemplateOptions — title, accent color, logo, footer
PdfTemplate.Create(...) for a fully custom, reusable template

page.UseTemplate(Templates.Corporate, opts =>
{
    opts.Title       = "Q3 Financial Report";
    opts.Subtitle    = "Prepared for the Board of Directors";
    opts.AccentColor = Color.Teal.Darken2;
    opts.LogoPath    = "logo.png";
    opts.FooterText  = "Confidential — Acme Inc.";
});

page.Content().Padding(30).Column(col =>
{
    col.Item().Text("Executive summary...").Justify();
});
        

Fonts & Unicode

Any typeface, any script

FontFamily.Register embeds a TrueType font as a Unicode composite font — full glyph coverage beyond the built-in fonts' Windows-1252 range, with pure-C# Devanagari shaping (matra reordering, conjunct ligatures, reph) for text set in a registered Indic font.

Regular, bold, italic, and bold-italic variants per family
From a file path, byte[], or Stream
No external packages — parsing and embedding are pure C#

FontFamily.Register("Brand", "fonts/Brand-Regular.ttf");
FontFamily.Register("Brand", "fonts/Brand-Bold.ttf", bold: true);

page.DefaultTextStyle(s => s.FontFamily("Brand"));
page.Content().Text("Héllo, Привет, Γειά σου, नमस्ते").FontSize(18);
        

v2.2.1

What's new

Predefined page templates — Corporate, Modern, Minimal, Elegant, and Cover, applied with page.UseTemplate(...), plus gradients, background images, and vector page decoration to build your own.
Custom font embedding — FontFamily.Register for any TrueType font, with pure-C# Devanagari shaping for Indic scripts.
columnSpan/rowSpan table fixes — spanned cells no longer get overlapped, tall spanned rows now grow to fit, and a rowSpan group stays intact across a page break.
Templates.Modern redesigned — a full-bleed accent rail replaces the previous gradient-and-ribbon treatment.

Full changelog →

Documentation

Guides for every feature

From your first page to encrypted, bookmarked, barcode-laden documents — each guide is versioned with the code.

Getting StartedYour first PDF LayoutColumn, Row, and Table Text & SpansStyling and page numbers DecoratorsPadding, borders, backgrounds TemplatesBranded pages in one call Custom FontsAny typeface, full Unicode EncryptionAES-256, permissions Vector GraphicsCanvas, shapes, charts Table of ContentsAuto-generated from headings BookmarksHierarchical PDF outlines

FAQ

Frequently asked questions

Is TerraFluent.Pdf.Reporting really free for commercial use?

Yes. It is released under the MIT license — use it in closed-source and commercial products at no cost, with no revenue caps, royalties, watermarks, or feature-limited tiers.

How does TerraFluent.Pdf.Reporting compare to iTextSharp, QuestPDF, or PDFsharp?

iText (iTextSharp) is AGPL licensed, which requires a commercial license for most closed-source use. QuestPDF's Community license is free only below a company-revenue threshold. PDFsharp is MIT but uses an imperative drawing model. TerraFluent.Pdf.Reporting offers a fluent, composable, code-first API under a plain MIT license with zero runtime dependencies.

Does TerraFluent.Pdf.Reporting convert HTML to PDF?

No. It is a code-first PDF generator — you compose documents from C# layout primitives (Column, Row, Table, Text, Image), which means no headless browser, deterministic output, and fast rendering. If your source content is already HTML, an HTML-to-PDF converter is a better fit.

Does it run on Linux, macOS, and in Docker?

Yes. It is 100% managed C# with no native binaries, so it runs on any platform supported by .NET 8, 9, or 10 — including Alpine-based Docker images, Azure Functions, and AWS Lambda — with nothing extra to install.

Can it create password-protected PDFs?

Yes. Documents can be encrypted with AES-256 (the default) or AES-128 for legacy viewers, with user and owner passwords plus fine-grained permission flags for printing, copying, and editing.

Can I brand a PDF without designing a page from scratch?

Yes. Five predefined page templates (Corporate, Modern, Minimal, Elegant, Cover) give a full-page branded background, header, and footer in one page.UseTemplate(...) call — fully customizable via TemplateOptions, or build an entirely custom template with the same public fluent API.

Does it support custom fonts and non-Latin scripts?

Yes. FontFamily.Register embeds a TrueType font as a Unicode composite font, so any typeface and any script the font covers — Cyrillic, Greek, Devanagari with full shaping and reordering — renders correctly, beyond the built-in fonts' Windows-1252 range.

Ships anywhere modern .NET runs

Targets .NET 8, .NET 9, and .NET 10 — Windows, Linux, macOS, Docker, Azure Functions, and AWS Lambda, with nothing native to install. MIT licensed.

Get started Browse samples