TerraPDF 1.4.0

TerraPDF

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

📚 To know more about it and documentation and sample codes. Please visit its website https://terrapdf.com/

New in 1.4.0: AES-256 encryption by default, plus bytes/stream image sources, anchor-based bookmarks, and the immutable TextStyle callback for multi-span text.

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 and .NET 9
• Text styling — bold, italic, bold-italic, strikethrough, underline, font size, colour
• Three built-in font families — Helvetica, Times, Courier — via FontFamily(), no embedding needed
• 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
• PNG and JPEG image embedding
• 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
• 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 — user password, owner password, and fine-grained permission flags (PdfPermissions) via container.Encrypt(); AES-128 remains available for compatibility
• Images from bytes and streams — Image(byte[]) / Image(Stream) with transparency and deduplication
• Anchor-based bookmarks — bookmark content directly to rendered elements and keep destinations accurate
• Full WinAnsiEncoding character coverage
• Vector graphics canvas — lines, rectangles, rounded rectangles, circles, ellipses, arbitrary Bézier paths, polygons, and grid helpers via container.Canvas()
• Fluent, composable API

Installation

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");

Full Documentation

For complete API reference and detailed guides, visit the docs directory:

• Getting Started — Installation, Quick Start, and basic usage
• Text & Spans — Single-span and multi-span text, styling, page numbers
• Layout — Column, Row, and Table layouts with alignment and spacing
• Row and Column Layout — Detailed Row and Column layout examples
• Decorators — Padding, margin, backgrounds, borders, and styling
• Images — PNG and JPEG embedding with sizing and alignment
• Page Sizes & Units — Built-in page sizes and unit conversions
• Colors — Material Design color palette with shades
• Encryption & Security — AES-256 by default, with AES-128 compatibility mode and permission flags
• Vector Graphics — Canvas API, shapes, paths, grids, and charts
• Table of Contents — Automatic TOC generation from headings
• Bookmarks — PDF bookmarks and outlines
• Components & Templates — Reusable components and document templates
• Metadata — Document metadata (Title, Author, Subject, Keywords, Creator)
• Unicode & Character Encoding — WinAnsiEncoding and character coverage
• Samples — Complete working examples demonstrating all features

Building from Source

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

Requires .NET 8 SDK or later.

Contributing

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

Changelog

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

Security

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

License

MIT — see LICENSE for details.