TerraPDF Features

Feature Overview

Explore TerraPDF's capabilities organized by functional area. Click any feature name to learn more.

Text & Typography

Full control over text presentation with an expressive fluent API. Style individual spans, manage line height, and apply Material Design colors.

Text Styling

Multi-Span Formatting

Combine multiple styles within a single text block using .Span() for inline variations:

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

Font Control

Control font properties per text block with chainable methods:

container.Text("Sample text")
    .FontSize(14)
    .FontColor(Color.Grey.Darken2)
    .LineHeight(1.6)
    .AlignJustify();

Layout Containers

Compose complex page layouts using flexible container elements that handle flow, alignment, and pagination automatically.

Column Layout

Stacks children vertically with configurable spacing and alignment options. Content flows naturally across pages.

container.Column(col =>
{
    col.Spacing(6);
    col.AlignItemsLeft(); // Left, Center, or Right alignment
    col.Item().Text("First section");
    col.Item().Text("Second section");
});

Row Layout

Arranges children horizontally with flexible sizing: proportional, fixed, or auto-width based on content.

container.Row(row =>
{
    row.Spacing(8);
    row.RelativeItem(2).Text("Takes 2/3 width");  // proportional sizing
    row.RelativeItem(1).Text("Takes 1/3 width");
    row.AutoItem().Text("Auto width");             // fits content
    row.ConstantItem(80).Text("80 points");       // fixed width
});

Table Layout

Grid-based tables with column definitions, repeating header rows, cell spanning, and full styling control.

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

    table.HeaderRow(row =>
    {
        row.Cell().Background("#1a4a8a").Text("Product").Bold();
        row.Cell().Background("#1a4a8a").Text("Qty").Bold();
        row.Cell().Background("#1a4a8a").AlignRight().Text("Price").Bold();
    });

    table.Row(row =>
    {
        row.Cell().Text("Widget");
        row.Cell().Text("5");
        row.Cell().AlignRight().Text("$99.99");
    });
});

Layers

Stack content in layers for backgrounds, watermarks, and foreground overlays. Useful for letterheads and decorative elements.

Inlined Layout

Inline flow layout where children wrap automatically like words in a paragraph. Elements arranged horizontally and wrap to next line when out of space.

Decorators & Styling

Chainable decorators for spacing, backgrounds, borders, and rounded corners. Composed from outside in: Margin → Background → Padding → Content.

Spacing

// Padding (inside border/background)
container.Padding(10);
container.PaddingTop(4).PaddingBottom(4);
container.Padding(0.5, Unit.Centimetre);

// Margin (outside border/background)
container.Margin(10);
container.MarginVertical(8);
container.Margin(0.5, Unit.Centimetre);

Backgrounds

container.Background("#1a4a8a");           // solid colour
container.Background(Color.Blue.Medium);   // using Material palette

Borders

// Simple border
container.Border(1.5, "#1a4a8a");  // width + color
container.Border(1);                 // 1pt black (default)

// Rounded border
container.RoundedBorder(radius: 8, lineWidth: 1, color: "#1a4a8a");

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

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

Lines

container.LineHorizontal(1.5, "#1a4a8a");  // horizontal divider
container.LineVertical(1);                    // vertical separator (1pt black)

Rounded Boxes

Combine background fill with rounded border in a single decorator. Ideal for callout boxes and highlighted content.

Aspect Ratio

Constrain child content to maintain width-to-height proportion. Use for images or fixed-ratio containers.

Page & Document

Page Configuration

Configure page size, margins, background colour, and default text style. All standard ISO page sizes included.

page.Size(PageSize.A4);
page.Margin(2, Unit.Centimetre);
page.PageColor(Color.White);
page.DefaultTextStyle(s => s.FontSize(11));

Headers & Footers

Define persistent header and footer regions that automatically repeat on every page. Main content flows between them with pagination.

page.Header()
    .Background("#1a4a8a")
    .Padding(8)
    .Text("My Report").Bold().FontColor(Color.White);

page.Footer()
    .AlignCenter()
    .Text(t =>
    {
        t.Span("Page ");
        t.CurrentPageNumber();
        t.Span(" / ");
        t.TotalPages();
    });

Page Breaks

Force a new page at any point inside a Column:

container.Column(col =>
{
    col.Item().Text("Content on page 1");
    col.PageBreak();                // Explicit page break
    col.Item().Text("Content on page 2");
});

Page Numbers

Insert current page number and total page count anywhere in the document. Automatically resolves during the two-pass rendering phase.

Page Orientation

Switch between portrait and landscape:

page.Size(PageSize.Landscape(PageSize.A4));
page.Size(PageSize.Portrait(PageSize.Letter));

Navigation & Links

Hyperlinks

Create clickable links to external URLs or email addresses. Wrap any content element:

// Text hyperlink
container.Hyperlink("https://example.com").Text("Visit website");

// Image hyperlink
container.Hyperlink("https://github.com/sahebansari/TerraPDF")
        .Image("logo.png", 120);

Internal Links

Jump to specific pages within the document using GoTo actions:

container.InternalLink(pageNumber: 5, topPosition: 72)
       .Text("Go to Chapter 5");

Table of Contents

Automatic TOC generation from H1–H6 headings. Generates clickable internal links and hierarchical numbering. Page numbers are accurate through the two-pass rendering system.

container.TableOfContents(toc =>
{
    toc.Size(PageSize.A4);
    toc.Margin(2, Unit.Centimetre);
    toc.DefaultTextStyle(s => s.FontSize(11));
});

PDF Bookmarks

Generate hierarchical PDF bookmarks (outlines) for navigation in PDF readers. Create parent-child relationships and precise page targeting.

c.Bookmark("Chapter 1", 1);
c.Bookmark("Section 1.1", 1, "Chapter 1");  // child of Chapter 1
c.Bookmark("Appendix", 5, 144);             // with Y-position

Media & Graphics

Images

Embed PNG and JPEG images with automatic aspect ratio preservation and alignment support:

// Fill available width, preserve aspect ratio
container.Image("photo.jpg");

// Fixed width with alignment
container.AlignCenter().Image("logo.png", 120);

Vector Graphics Canvas

Draw vector graphics directly inside any layout container. The canvas fills the available width and uses a top-left coordinate system in PDF points.

container.Canvas(120, c =>
{
    c.FillRoundedRect(0, 0, 180, 70, 8, Color.Blue.Lighten4);
    c.StrokeRoundedRect(0, 0, 180, 70, 8, Color.Blue.Darken2, 1.5);
    c.Line(0, 90, 260, 90, Color.Grey.Lighten2, 0.5);
    c.Path(p => p
        .MoveTo(40, 110)
        .LineTo(80, 40)
        .LineTo(120, 110)
        .Close()
        .Fill(Color.Orange.Medium));
});

The Canvas API includes lines, rectangles, rounded rectangles, circles, ellipses, arbitrary Bezier paths, polygons, and grid helpers for charts and diagrams.

Dynamic Components

Optimize memory for large documents with deferred content generation. Content is generated only when needed during rendering rather than eagerly computed.

Debug Visualisation

Debug areas and pointers help diagnose layout issues during development by highlighting element boundaries and providing context in error messages.

Security & Encoding

AES-128 PDF Encryption

Protect generated PDFs with the PDF Standard Security Handler using user passwords, owner passwords, and fine-grained permission flags.

Document.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.");
    });
})
.PublishPdf("protected.pdf");

WinAnsi Character Coverage

TerraPDF maps text through WinAnsiEncoding for built-in Type 1 fonts, covering printable ASCII, Windows-1252 typographic specials, and Latin-1 characters.

container.Text("Français, señor, São Paulo, € 1,299.00");
container.Text("Pages 42–47 and TerraPDF™");

Characters outside WinAnsiEncoding, such as many Latin Extended-A/B glyphs, should be replaced or avoided when using the built-in PDF fonts.

Reusability & Components

IComponent — Reusable Content Blocks

Encapsulate reusable UI elements like callouts, address blocks, or cards:

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 anywhere
container.Component(new CalloutBox("Important note"));

IDocument — Reusable Document Templates

Separate document structure from data. Create templates for invoices, reports, or letters that can be unit tested and reused.

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().Column(col =>
            {
                col.Item().Text($"Invoice #{_data.Number}").Bold();
                col.Item().Text($"Total: {_data.Total:C}");
            });
        });
    }
}

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

Conditional Rendering

Show or hide content based on runtime conditions:

container.Column(col =>
{
    col.Item().Text("Always shown");

    col.Item().ShowIf(isVip)
        .Text("VIP exclusive offer");

    col.Item().ShowIf(showDiscount)
        .Background(Color.Green.Lighten4)
        .Text("Discount applied!");
});

Metadata & Document Properties

Document Metadata

Set standard PDF document properties that appear in viewer dialogs:

Document.Create(c =>
{
    c.MetadataTitle("Quarterly Report Q1 2025");
    c.MetadataAuthor("Acme Finance Division");
    c.MetadataSubject("Financial Performance Review");
    c.MetadataKeywords("finance, quarterly, report, 2025");
    c.MetadataCreator("Acme Reporting Engine v3.2");

    c.Page(p => p.Size(PageSize.A4).Content().Text("..."));
})
.PublishPdf("report.pdf");

Content Direction

Full support for right-to-left (RTL) languages. Set direction at page or container level:

page.ContentFromRightToLeft()
    .Column(col =>
    {
        col.Item().Text("مرحبا بالعالم");  // Arabic RTL text
    });

Headings H1–H6

Semantic heading elements with sensible defaults. Automatically register with TOC and bookmark systems.

Lists

Ordered (numbered) and unordered (bulleted) lists with automatic numbering and custom markers.

Output & Units

Flexible output destinations and intuitive measurement system for seamless integration into any workflow.

Output Options

Generate PDFs in the format that fits your application architecture:

Length Units

Specify units directly in API calls — TerraPDF handles all conversions automatically. No manual point calculations needed.

Built-in Page Sizes

All standard ISO and North American paper sizes included. Landscape and portrait variants available via PageSize.Landscape() and PageSize.Portrait().

Full ISO A0–A6 series included. All dimensions in PDF points (1/72 inch).

Colors

Material Design colour palette built-in, with darken/lighten variants and direct hex string support.

// 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.Blue.Lighten1 ... Color.Blue.Lighten4
Color.Green.Darken2  Color.Green.Medium  Color.Green.Lighten1 ... Color.Green.Lighten4
Color.Grey.Darken2   Color.Grey.Medium   Color.Grey.Lighten1 ... Color.Grey.Lighten4
Color.Orange.Medium
Color.Purple.Medium

// Custom hex colors
container.Background("#1a4a8a");
container.Border(1, "#2ec27e");

// Constants
Color.White  // "#FFFFFF"
Color.Black  // "#000000"

All color-accepting methods support both Color constants and hex strings like "#RRGGBB".

Developer Experience

Built for productivity with a clean, fully managed architecture that integrates seamlessly into any .NET project.