TerraPDF

A free, pure C# library designed for fast and reliable PDF generation.

📚 Documentation: https://github.com/sahebansari/TerraPDF/tree/master/docs

New in 2.4.0: Documents render 2–30× faster with 60–95% fewer allocations, and existing code needs no changes. Text layout, tables, PNG images, custom fonts, QR codes, and the vector canvas are all faster; a logo used in every document is converted once per process. Built-in font widths now match the Adobe metrics, so text containing curly quotes or bullets may wrap slightly differently. See the Changelog.

New in 2.3.0: Canvas paths take linear and radial gradient fills (FillLinearGradient, FillRadialGradient), every stroked shape and path can be dashed, and a canvas can place clickable links (Link, InternalLink), outline entries (Bookmark), and vector QR codes (QrCode) at absolute positions. Grid() now fills the canvas and ShowIf(false) now hides chained content. See Vector Graphics and the Canvas Extras sample.

New in 2.2.0: The vector canvas places images — PNG and JPEG from a file path, byte[], or Stream, in an absolute rectangle, with Stretch, Contain, Cover, CoverTopLeft, and CropTopLeft fit modes and scoped clipping. It also draws elliptical arcs and pie sectors (PathDescriptor.Arc/Sector, FillPie/StrokePie/DrawPie), dashed strokes with a phase, and text rotated around its baseline point. See Vector Graphics, Images, and the Canvas Media sample.

New in 2.1.0: Font embedding subsets automatically — FontFamily.Register(...) embeds only the glyphs a document actually shows, with a composite-glyph closure pass so accented letters and Devanagari conjuncts keep every component they depend on. The vector canvas also gained constant-alpha transparency (opacity on every primitive, via /ExtGState) and baseline-anchored text. See the Font Subsetting sample.

New in 2.0.1: Table cells span columns and rows correctly — Cell(columnSpan:) no longer overlaps the cell after it, Cell(rowSpan:) reserves its columns in the rows below, and a spanned cell grows the rows it covers instead of overflowing. Tables also paginate in every position: a header-less table splits across pages, a table placed straight into page.Content() splits, and a page break is never allowed to fall inside a row span. No public API changed. See Layout and the Table Spans sample.

New in 2.0.0: Custom font embedding — FontFamily.Register(...) loads a TrueType font (brand typefaces, or scripts beyond WinAnsiEncoding like Cyrillic and Greek) and uses it via the same TextStyle.FontFamily(...) API as the built-in families — including automatic, pure-C# Devanagari-aware rendering (conjunct ligatures, reph, and below-base 'ra' forms, no native shaping engine). See Custom Fonts.

Also: Code128 barcodes and QR codes (ISO/IEC 18004, versions 1-40, all four error correction levels) via container.Barcode(...) and container.QrCode(...) — rendered as vector-filled rectangles, no raster image pipeline, placeable anywhere a Column, Row, or Table cell can go. TerraPDF also multi-targets .NET 10 (LTS) alongside .NET 8 and 9.

TerraPDF is a lightweight, zero-dependency, pure C# library for generating professional PDF 1.7 documents programmatically. It provides a fluent, composable API that covers the full document-authoring lifecycle — from page layout and rich text to tables, images, hyperlinks, and multi-page pagination — with no native binaries, no third-party runtime packages, and no licensing restrictions.

No native dependencies, no third-party packages
Targets .NET 8, .NET 9, and .NET 10
Text styling — bold, italic, bold-italic, strikethrough, underline, font size, colour
Configurable line-height multiplier per text block
Per-span formatting inside mixed-style text blocks
Margin and padding decorators with full unit support
Background fills and borders (full, rounded, and per-edge)
Rounded-corner borders and filled rounded boxes
Per-edge borders — BorderTop, BorderBottom, BorderLeft, BorderRight
Horizontal and vertical alignment
Column, Row, and Table layouts — with column- and row-spanning table cells
PNG and JPEG image embedding — from file paths, byte[], or Stream, with transparency and deduplication
Horizontal and vertical rule lines
Explicit page breaks via PageBreak()
Clickable hyperlink (URI) annotations via Hyperlink()
Internal document links (GoTo) via InternalLink()
Automatic Table of Contents generation from H1–H6 headings
PDF bookmarks / outlines with hierarchical nesting — anchor-based via container.Bookmark("Title") or manual page-number targeting
Document metadata (Title, Author, Subject, Keywords, Creator)
Conditional rendering via ShowIf
Reusable components via IComponent
Headers, footers, and page numbers
AES-256 PDF encryption by default via container.Encrypt() — AES-128 remains available as a legacy opt-in
Vector graphics canvas via container.Canvas() — lines and dashed strokes, shapes, arbitrary Bezier paths, arcs and pie sectors, positioned images with fit/crop modes, rotated text, and grid helpers
Barcodes — Code128 (Subset B) via container.Barcode()
QR codes — ISO/IEC 18004 via container.QrCode()
Custom font embedding — FontFamily.Register(...) embeds a TrueType font (brand typefaces, Cyrillic, Greek, and beyond WinAnsiEncoding) used via the same FontFamily() API as the built-in families, with automatic Devanagari-aware shaping
Full WinAnsiEncoding character coverage
Fluent, composable API

Installation

Terminal

dotnet add package TerraPDF

Quick Start

using TerraPDF.Core;
using TerraPDF.Helpers;

Document.Create(container =>
{
    container.Page(page =>
    {
        page.Size(PageSize.A4);
        page.Margin(2, Unit.Centimetre);
        page.PageColor(Color.White);
        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, TerraPDF!");
                col.Item().Text("This paragraph is italic.").Italic();
                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");

API Overview

Document entry points

Method	Description
`Document.Create(Action<IDocumentContainer>)`	Inline composition callback
`Document.Create(IDocument)`	Reusable `IDocument` class

Page configuration

page.Size(PageSize.A4);
page.Margin(2, Unit.Centimetre);   // page margin
page.PageColor(Color.White);
page.DefaultTextStyle(s => s.FontSize(11));
page.Header()   // returns IContainer
page.Content()  // returns IContainer
page.Footer()   // returns IContainer

Text

Single-string text

container.Text("Hello, world!")
    .Bold()
    .SemiBold()
    .Italic()
    .Strikethrough()
    .Underline()
    .FontSize(18)
    .LineHeight(1.5)  // line-height multiplier (default ≈ 1.4)
    .FontColor(Color.Blue.Darken2)
    .AlignLeft()      // default
    .AlignCenter()
    .AlignRight()
    .Justify();

Multi-span text

Each Span(), CurrentPageNumber(), and TotalPages() returns a SpanDescriptor so formatting applies only to that span, not to the whole block.

container.Text(t =>
{
    t.Span("Normal  ");
    t.Span("Bold  ").Bold();
    t.Span("Italic  ").Italic();
    t.Span("Struck  ").Strikethrough();
    t.Span("Coloured  ").FontColor(Color.Red.Medium);
    t.Span("Large").FontSize(16).FontColor("#1a4a8a");
});

Page numbers in footers

container.Text(t =>
{
    t.Span("Page ").FontSize(9).FontColor(Color.Grey.Medium);
    t.CurrentPageNumber().FontSize(9).FontColor(Color.Grey.Medium);
    t.Span(" / ").FontSize(9);
    t.TotalPages().FontSize(9);
});

Layout

Column — stacks children vertically

container.Column(col =>
{
    col.Spacing(6);                       // gap between items in points
    col.AlignItemsLeft();                 // default
    col.AlignItemsCenter();
    col.AlignItemsRight();

    col.Item().Text("First");
    col.Item().Text("Second");
});

Row — arranges children horizontally

container.Row(row =>
{
    row.Spacing(8);                       // gap between items in points

    row.RelativeItem(2).Text("2x wide"); // proportional share of remaining space
    row.RelativeItem(1).Text("1x wide");
    row.AutoItem().Text("Auto width");   // natural content width
    row.ConstantItem(80).Text("80 pt");  // fixed width in points
});

Table — grid with repeating header rows

container.Table(table =>
{
    table.ColumnsDefinition(cols =>
    {
        cols.RelativeColumn(4);   // proportional
        cols.RelativeColumn(1);
        cols.ConstantColumn(60);  // fixed width in points
    });

    // HeaderRow repeats on every continuation page
    table.HeaderRow(row =>
    {
        row.Cell().Background("#1a4a8a").Padding(6).Text("Description").Bold().FontColor(Color.White);
        row.Cell().Background("#1a4a8a").Padding(6).Text("Qty").Bold().FontColor(Color.White);
        row.Cell().Background("#1a4a8a").Padding(6).AlignRight().Text("Amount").Bold().FontColor(Color.White);
    });

    table.Row(row =>
    {
        row.Cell().Padding(6).Text("Web Development");
        row.Cell().Padding(6).Text("1");
        row.Cell().Padding(6).AlignRight().Text("$2,500.00");
    });
});

Decorators

Decorators are chainable and compose from the outside in: .Margin() → .Background() → .Padding() → content

Padding — inner spacing (inside background / border)

container.Padding(10)                    // all sides
container.PaddingVertical(8)             // top + bottom
container.PaddingHorizontal(12)          // left + right
container.PaddingTop(4)
container.PaddingBottom(4)
container.PaddingLeft(6)
container.PaddingRight(6)

// All padding methods also accept a Unit:
container.Padding(0.5, Unit.Centimetre)

Margin — outer spacing (outside background / border)

container.Margin(10)                     // all sides
container.MarginVertical(8)              // top + bottom
container.MarginHorizontal(12)           // left + right
container.MarginTop(4)
container.MarginBottom(4)
container.MarginLeft(6)
container.MarginRight(6)

// All margin methods also accept a Unit:
container.Margin(0.5, Unit.Centimetre)

Padding vs Margin .Margin(10).Background("red").Padding(5).Text("Hi") — the red background starts after the 10 pt margin gap; the text is inset 5 pt from the red edge.

Background and Border

container.Background("#1a4a8a")
container.Border(1.5, "#1a4a8a")        // line width + colour
container.Border(1)                      // black by default

// Rounded-corner border
container.RoundedBorder(radius: 8, lineWidth: 1, hexColor: "#1a4a8a")

// Filled rounded box (background + border)
container.RoundedBox(radius: 8, fillHexColor: "#E3F2FD", borderHexColor: "#1a4a8a")

// Per-edge borders
container.BorderTop(1.5, "#1a4a8a")
container.BorderBottom(1)
container.BorderLeft(3, Color.Red.Medium)
container.BorderRight(1, Color.Grey.Lighten2)

Page Break

// Force a new page at this position inside a Column
container.PageBreak();

Hyperlink

// Wrap any content in a clickable URI annotation
container.Hyperlink("https://example.com").Text("Click here");
container.Hyperlink("https://example.com").Image("logo.png", 120);

Internal Link

Wrap content in a clickable internal hyperlink that jumps to a specific page and optional vertical position:

container.InternalLink(pageNumber, topPosition).Text("Go to section");

This creates a /GoTo action in the PDF. The automatic Table of Contents uses internal links to make each entry clickable.

Alignment

// Horizontal
container.AlignLeft()
container.AlignCenter()
container.AlignRight()

// Vertical
container.AlignMiddle()
container.AlignBottom()

Lines

container.LineHorizontal(1.5, "#1a4a8a")   // horizontal rule
container.LineVertical(1)                   // vertical rule (black)

Conditional rendering

container.ShowIf(isAdmin).Text("Admin panel");

Images

// Fill available width, preserve aspect ratio (PNG or JPEG)
container.Image("path/to/image.png");
container.Image("path/to/photo.jpg");

// Fixed width in points, can be positioned with alignment
container.AlignCenter().Image("logo.png", 120);

Barcodes & QR Codes

Both render as vector-filled rectangles — no raster image pipeline — so they stay crisp at any zoom and can be placed inside any Column, Row, or Table cell.

// Code128 (Subset B) barcode, auto-fills available width
container.Barcode("TERRAPDF-2026");

// With explicit size, colour, and a caption below the bars
container.Barcode("SKU-00042-A", width: 260, height: 50,
    hexColor: "#1A3C5E", showCaption: true);

// QR code (ISO/IEC 18004), auto-fills available width (capped to a square)
container.QrCode("https://terrapdf.example/p/SKU-10231");

// With explicit size and error correction level
container.QrCode("https://terrapdf.example/", size: 90,
    level: QrErrorCorrectionLevel.Q);

QrErrorCorrectionLevel is L, M (default), Q, or H — higher levels tolerate more damage/occlusion at the cost of a denser code.

Headings

TerraPDF provides six levels of section headings: .H1() through .H6(). Each heading uses sensible defaults (size + weight), which you can further customise via the fluent TextDescriptor API.

container.H1("Chapter Title").FontColor(Color.Blue.Darken2);
container.H2("Section Title").Underline();
container.H3("Subsection");

Default heading styles

Level	Font size	Style
H1	24 pt	Bold
H2	20 pt	Bold
H3	16 pt	Bold
H4	14 pt	Italic
H5	12 pt	Bold
H6	11 pt	Regular

Call container.TableOfContents() to add a contents page that is automatically populated with all headings in the document. Headings appear with correct logical page numbers (excluding the TOC page itself) and clickable internal links that jump to the exact physical page.

Document.Create(container =>
{
    // Create a Table of Contents page
    container.TableOfContents(p =>
    {
        p.Size(PageSize.A4);
        p.Margin(2, Unit.Centimetre);
        p.DefaultTextStyle(s => s.FontSize(11));
    });

    // Chapters with headings
    container.Page(p =>
    {
        p.Content()
            .H1("Introduction")
            .H2("Getting Started")
            .H3("Installation")
            .H4("NuGet Package");
    });

    container.Page(p =>
    {
        p.Content()
            .H1("Core Features")
            .H2("Text & Typography")
            .H2("Layout Containers")
            .H2("Tables");
    });
})
.PublishPdf("toc_demo.pdf");

Note: Page numbers displayed in the TOC start from 1 for the first page after the TOC (i.e., the TOC page is treated as page 0). The internal links point to the correct physical pages, accounting for the TOC's actual page count.

Two-pass rendering TerraPDF performs an initial measurement pass to collect heading positions and page numbers, then emits the final PDF with accurate TOC links.

Reusable Components

public class CalloutBox : IComponent
{
    private readonly string _text;
    public CalloutBox(string text) => _text = text;

    public void Compose(IContainer container) =>
        container
            .Margin(6).Background(Color.Blue.Lighten4).Padding(10)
            .Text(_text).Italic();
}

// Usage
container.Component(new CalloutBox("Note: this is important."));

Reusable Document Template

public class InvoiceDocument : IDocument
{
    private readonly InvoiceData _data;
    public InvoiceDocument(InvoiceData data) => _data = data;

    public void Compose(IDocumentContainer container)
    {
        container.Page(page =>
        {
            page.Size(PageSize.A4);
            page.Margin(2, Unit.Centimetre);
            page.Content().Text($"Invoice #{_data.Number}").Bold().FontSize(24);
        });
    }
}

// Usage
Document.Create(new InvoiceDocument(data)).PublishPdf("invoice.pdf");

Output Methods

var composer = Document.Create(...);

// To file
composer.PublishPdf("output.pdf");

// To byte array (HTTP responses, email attachments, etc.)
byte[] bytes = composer.PublishPdf();

// To any writable stream
composer.PublishPdf(stream);

Built-in Page Sizes

Constant	Width × Height (pt)
`PageSize.A0`	2383.94 × 3370.39
`PageSize.A1`	1683.78 × 2383.94
`PageSize.A2`	1190.55 × 1683.78
`PageSize.A3`	841.89 × 1190.55
`PageSize.A4`	595.28 × 841.89
`PageSize.A5`	419.53 × 595.28
`PageSize.A6`	297.64 × 419.53
`PageSize.Letter`	612.00 × 792.00
`PageSize.Legal`	612.00 × 1008.00
`PageSize.Tabloid`	792.00 × 1224.00
`PageSize.Executive`	521.86 × 756.00

// Landscape variant of any size
page.Size(PageSize.Landscape(PageSize.A4));

Built-in Units

Enum value	Description
`Unit.Point`	PDF native unit (1 pt = 1/72 inch) — default
`Unit.Millimetre`	1 mm ≈ 2.835 pt
`Unit.Centimetre`	1 cm ≈ 28.35 pt
`Unit.Inch`	1 in = 72 pt

Built-in Colours

// Named shades (Material Design palette)
Color.Red.Darken2      Color.Red.Darken1
Color.Red.Medium       Color.Red.Lighten1  ...  Color.Red.Lighten4
Color.Blue.Darken2     Color.Blue.Medium   ...
Color.Green.Darken2    Color.Green.Medium  ...
Color.Grey.Darken2     Color.Grey.Medium   Color.Grey.Lighten1 ...
Color.Orange.Medium
Color.Purple.Medium
// Convenience constants
Color.White            // "#FFFFFF"
Color.Black            // "#000000"

Building from Source

Terminal

git clone https://github.com/sahebansari/TerraPDF.git
cd TerraPDF
dotnet build
dotnet test

Requires the .NET 10 SDK (the repository's global.json pins to it, with rollForward: latestMajor). The library itself still targets .NET 8, .NET 9, and .NET 10 at runtime.

Contributing

Contributions are welcome! Please read Contributing for coding standards, project structure, how to run tests, and the pull-request process.

Changelog

All notable changes are documented in Changelog, following the Keep a Changelog format.

Security

To report a vulnerability, please follow the responsible-disclosure process described in Security. Do not open a public issue for security problems.

License

MIT — see LICENSE for details.

← Row & Column Layout Changelog →