Fluent C# API

Overview

EggPdf.Fluent lets you describe a document with C# method calls. It builds the same DOM the HTML parser would produce and hands it to the normal pipeline — cascade, layout, pagination, paint, PDF writer — so there is no HTML string in the middle, no escaping to get wrong, and the output is byte-for-byte the kind of PDF the HTML API makes. Because it is the same engine, anything HTML/CSS can express, the fluent API can express (see escape hatches).

It ships inside the main EggPdf package — there is nothing extra to install. Add using EggPdf.Fluent; and call Document.Create(...).

dotnet add package EggPdf

Quick start

using EggPdf.Fluent;

byte[] pdf = Document.Create(doc => doc
    .Title("Invoice INV-142")
    .Page(page => page
        .Size(PageSize.A4)
        .Margin(top: 70, right: 30, bottom: 50, left: 30)
        .Header(h => h.Text("Acme Corp").Bold().FontSize(18))
        .Footer(f => f.AlignCenter().PageNumberOfTotal())      // "Page 2 of 5"
        .Watermark("DRAFT")
        .Content(c =>
        {
            c.Heading(HeadingLevel.H1, "Invoice");              // also a PDF bookmark
            c.Item().Row(row =>
            {
                row.RelativeItem().Text("Bill to: Jane Doe");
                row.ConstantItem(Length.Mm(40)).AlignRight().Text("2026-09-24");
            });
            c.Item().Table(table =>
            {
                table.Header(h => { h.Cell().Text("Item").Bold(); h.Cell().Text("Qty").Bold(); });
                foreach (var line in lines)
                    table.Row(r => { r.Cell().Text(line.Name); r.Cell().Text(line.Qty.ToString()); })
                         .AvoidBreakInside();
            });
            c.Item().PinBottom().Border(1, Colors.Gray).Padding(10).Text("Signature");
        })))
    .Render();

Document.Create(...) returns a DocumentBuilder with Render(), RenderAsync(ct) and RenderToFileAsync(path, ct).

Building step by step

The nested form above is one style. You can equally create the document, keep it in a variable, and fill in the header, footer and body in separate statements — or separate methods. Every callback method has a parameterless twin that returns the thing to fill in (Header(), Footer(), Content(), Row(), Table(), Grid(...), BulletList(), NumberedList(), Column()), and Document.New() / AddPage() replace Document.Create / Page. Both styles produce byte-identical PDFs.

var doc  = Document.New().Title("Report");
var page = doc.AddPage().Size(PageSize.A4).Margin(30);

page.Header().Text("Acme").Bold();
page.Footer().AlignCenter().PageNumberOfTotal();

var body = page.Content();
body.Heading(HeadingLevel.H1, "Summary");
body.Item().Text("Quarterly results");
AddSalesTable(body);                       // ordinary helper method: one per report section

byte[] pdf = doc.Render();                 // or RenderAsync(ct) / RenderToFileAsync(path, ct)

static void AddSalesTable(ColumnDescriptor content)
{
    var table = content.Item().Table();
    table.Header(h => { h.Cell().Text("Region").Bold(); h.Cell().Text("Sales").Bold(); });
    table.Row(r => { r.Cell().Text("North"); r.Cell().Text("1,200"); });
}

• Page settings can be changed at any point before rendering (page.Size(...) after adding content is fine) — the @page rule is written when the document is built.
• page.Content() can be called more than once; items append in call order.
• Rendering builds and freezes the document. You can render it again (identical output), but any further change — AddPage(), Text(...), Bold(), Title(...), … — throws InvalidOperationException rather than being silently lost. Call Build() to freeze it explicitly.
• The nested callbacks also accept normal statements and calls to helper methods that take a Container/ColumnDescriptor, so you can mix the two styles freely.

Method chaining

Styling and configuration methods return the object they were called on, so they chain (.Text("Hi").FontSize(20).Bold().Padding(8)). The methods that add a child (Item, Cell, RelativeItem, ConstantItem, Heading, table Header/Row) normally return that child, which is what lets you style it. Each also has an overload taking a callback that returns the parent instead, so siblings chain too and a whole document is one expression:

Document.Create(doc => doc
    .Title("Chained")
    .Page(p => p.Size(PageSize.A4).Margin(30).Content(c => c
        .Item(i => i.Text("Intro").Bold())
        .Heading(HeadingLevel.H2, "Section", h => h.FontColor(Colors.Navy))
        .Item(i => i.Row(r => r
            .Gap(5)
            .RelativeItem(x => x.Text("Left"))
            .ConstantItem(60, x => x.Text("Mid"))
            .RelativeItem(2, x => x.Text("Wide"))))
        .Item(i => i.Grid(2, g => g
            .Item(x => x.Text("G1"))
            .Item(2, x => x.Text("Spans both columns"))))
        .Item(i => i.BulletList(l => l.Item(x => x.Text("One")).Item(x => x.Text("Two"))))
        .Item(i => i.Table(t => t
            .Header(h => h.Cell(x => x.Text("Item")).Cell(x => x.Text("Qty")), r => r.Background(Colors.LightGray))
            .Row(r => r.Cell(x => x.Text("Widget")).Cell(x => x.Text("3")), r => r.AvoidBreakInside()))))))
    .Render();

The table overloads take a second callback that styles the row box itself. All three styles — chained, nested statements, and step by step — can be mixed freely and produce identical PDFs. Pages chain through Page(...): doc.Page(...).Page(...).

Structure

The builder is a tree of small descriptor types; each callback receives the one you need next:

Typed values — no magic strings

A misspelled CSS keyword, color or unit is silently ignored by a CSS engine, which makes for PDFs that look wrong with no error anywhere. Every typed method therefore takes a typed value, and constructing an invalid one fails immediately.

Numeric ranges are checked too: Opacity (0–1), FontWeight (1–1000), LineHeight (positive), grid column counts and spans (≥ 1). Plain string parameters remain only where the value is genuinely free text: content, URLs and paths, ids and class names, font family names, titles.

Content

Text and styling

c.Item()
    .Text("Quarterly report")
    .FontSize(20).Bold().FontColor(Colors.Navy)
    .LetterSpacing(Length.Px(0.5f)).TextTransform(TextCase.Uppercase)
    .Padding(8, 12).Background(Color.FromHex("#f1f5f9"))
    .Border(1, Colors.LightGray, BorderLineStyle.Dashed).BorderRadius(6)
    .BoxShadow(0, 2, 6, Color.FromRgba(0, 0, 0, 64));

Column and Row

A column is normal block flow (Item() per child). A row is a flex container: items are RelativeItem(weight) (shares remaining space) or ConstantItem(width) (fixed). The row itself is styled through RowDescriptor:

c.Item().Row(row =>
{
    row.Gap(12).JustifyContent(FlexJustify.SpaceBetween).AlignItems(FlexAlign.Center).Wrap();
    row.RelativeItem(2).Text("Wide");
    row.RelativeItem(1).Text("Narrow");
    row.ConstantItem(Length.Mm(30)).Text("Fixed");
});

Grid

c.Item().Grid(new[] { GridTrack.Fr(1), GridTrack.Fr(2) }, g =>
{
    g.Gap(10).AutoRows(Length.Px(40));
    g.Item().Text("A");
    g.Item().Text("B");
    g.Item(columnSpan: 2).Text("Spans both columns");
});
c.Item().Grid(3, g => { /* three equal columns */ });

Tables

table.Header(...) emits a real <thead>, which repeats at the top of every continuation page when the table spans pages (see Tables). Header and Row return the row so you can style it — .AvoidBreakInside() keeps a row from splitting across a page break. Cells default to 4×8 px padding and a light 1 px border; restyle any cell through the returned Container. Tables default to 100% width with collapsed borders.

Lists, images, links, headings

c.Item().BulletList(l => { l.Item().Text("One"); l.Item().Text("Two"); });
c.Item().NumberedList(l => l.Item().Text("First"));
c.Item().Image("logo.png", widthPx: 80, heightPx: 40);      // path, URL or data: URI
c.Item().Hyperlink("https://example.com", "Visit us");
c.Heading(HeadingLevel.H2, "Section");                       // real <h2>: bookmark + PDF/UA heading

Relative image paths resolve against DocumentDescriptor.BasePath(...). Headings must be created with Heading(...) (not a styled Item()) — bookmarks and the accessibility structure tree key off the real h1–h6 tags.

Internal links

Give a box an id and link to it. The link is a real PDF destination (page + position), so it jumps forward or backward to any page:

c.Item().Hyperlink("#terms", "See the terms");
// ...
c.Item().Id("terms").Text("Terms and conditions");

Pages, headers, footers

page.Size(PageSize.Letter.Landscape())
    .Margin(top: 60, right: 20, bottom: 60, left: 20)   // reserve room for the header/footer
    .Header(h => h.Text("Confidential").FontColor(Colors.Gray))
    .Footer(f => f.AlignRight().PageNumberOfTotal(prefix: "Page ", separator: " / "))
    .Watermark("DRAFT", fontSize: Length.Px(120), rotationDegrees: -35, opacity: 0.1f, color: Colors.Red)

• Sizes: PageSize.A3/A4/A5/Letter/Legal, .Landscape(), or new PageSize(widthMm, heightMm).
• Header / footer repeat on every physical page of the group (position: fixed). They don't push content down — leave room with the page margins.
• Page numbers: CurrentPageNumber(), TotalPages(), PageNumberOfTotal(). CSS allows a single generated ::after per element, so use one of these per Container — a second call on the same container throws instead of silently replacing the first. Use separate containers (e.g. row items) for separate pieces.
• Watermark is composed from position: fixed, transform and opacity — there is no dedicated watermark feature in the CSS engine either.
• PinBottom() pins a box (e.g. a signature block) to the bottom of whichever page the preceding content ends on.

Multiple page groups (mixed sizes)

Content that overflows a page flows onto the next automatically. Call Page(...) more than once to change size or orientation partway through — the first group is the base @page rule and each later group gets its own named page (CSS Paged Media named pages):

Document.Create(doc => doc
    .Page(p => p.Size(PageSize.A4).Content(c => c.Item().Text("Report body")))
    .Page(p => p.Size(PageSize.A4.Landscape()).Content(c => c.Item().Text("Wide appendix table"))));

Document-level options

Document.Create(doc => doc
    .Title("Annual report").Author("Finance team").Language("en")
    .BasePath(@"C:\assets")                                  // resolves relative images/fonts/CSS
    .FontFace("Brand Sans", "fonts/brand.ttf", weight: 700)
    .Css(".total { font-weight: 700 } @media print { .noprint { display: none } }")
    .Conformance(PdfAConformance.PdfA2b)                     // PDF/A archival
    .Tagged()                                                // PDF/UA accessible
    .Page(...));

Escape hatches

When a feature has no typed method yet, four explicitly unchecked hatches guarantee you are never blocked. They are named Raw* on purpose, so unchecked strings are visible at every call site:

c.Item().RawStyle("column-count", "2");                     // any CSS declaration
c.Item().RawAttribute("data-section", "intro");              // any HTML attribute
c.Item().Raw("<dl><dt>Term</dt><dd>Definition</dd></dl>");   // any HTML markup, spliced into the tree
doc.Css("@page :first { @top-center { content: 'Cover' } }"); // any stylesheet

Validation and errors

• Invalid typed values throw at the call site: Color.FromHex("red") and Length.Px(float.NaN) throw ArgumentException/ArgumentOutOfRangeException.
• Out-of-range numbers (Opacity(1.5f), FontWeight(0), Grid(0, ...), Heading((HeadingLevel)9, ...)) throw ArgumentOutOfRangeException.
• A second page-number/generated-content call on one container throws InvalidOperationException.
• Rendering problems behave exactly as in the HTML API (missing images and fonts degrade gracefully; PDF/A rule violations throw).

How it works

Fluent calls accumulate typed style declarations per element. When Document.Create returns, they are serialized once into style/class attributes on an in-memory HtmlDocument, which is passed to HtmlToPdf.RenderDocument(...) — the same entry the HTML string API reaches after parsing. See Architecture. Because nothing is generated as text, content is never HTML-escaped or re-parsed, and a fluent document and the equivalent HTML render identically.

API reference

Every public type and member of EggPdf.Fluent, with its purpose. This section is generated from the code and its XML doc comments (dotnet run --project tools/EggPdf.DocGen), so it always matches the API; the same summaries appear as IntelliSense in your editor. A callback overload takes an Action and returns the parent (for chaining); the parameterless overload returns the child (to style it or fill it in with separate statements).

Types: Document, DocumentBuilder, DocumentDescriptor, PageDescriptor, ColumnDescriptor, Container, RowDescriptor, GridDescriptor, ListDescriptor, TableDescriptor, TableRowDescriptor, Color, Colors, Length, CssTransform, GridTrack, PageSize, and the keyword enums.

Document (static)

Entry point for defining PDF content in C# instead of HTML. It builds a DOM directly from the fluent calls and hands it to HtmlToPdf unchanged -- same cascade/layout/paint/ PDF-write pipeline as the HTML API, just without ever going through an HTML string. Two styles, same result: declarative (Create, one callback) or step by step (New).

var doc = Document.New().Title("Report"); var page = doc.AddPage().Size(PageSize.A4); page.Header().Text("Acme"); page.Footer().PageNumberOfTotal(); var body = page.Content(); body.Item().Text("Hello"); byte[] pdf = doc.Render();

DocumentBuilder

The finished document, ready to render. Returned by Create.

DocumentDescriptor

Root of the fluent builder: a document is one or more page groups, plus document-wide PDF options. Build it either declaratively inside Create's callback, or step by step: var doc = Document.New(); var page = doc.AddPage(); page.Header().Text("..."); ... doc.Render(); Both produce the same document. Once built or rendered a document is frozen -- further changes throw.

PageDescriptor

Configures one page group's size, margins, running header/footer/watermark and content. Size/margin become an injected @page rule (named, for every group after the first -- see Page); content becomes the group's stacked (Column) body, the same way HTML's <body> is.

ColumnDescriptor

Builds the stacked (top-to-bottom) children of a Column.

Container

A single box in the document tree (a <div> under the hood). Every content-producing fluent call (Column, Row, page content, row/column items) hands back a Container, so text and styling always apply to "whatever was placed last". Styling takes typed values (Color, Length, keyword enums); the Raw* methods are the explicit, unchecked escape hatches.

RowDescriptor

Builds the side-by-side (flex) children of a Row.

GridDescriptor

Builds the cells of a CSS grid container (Grid).

ListDescriptor

Builds the <li> items of a bullet (<ul>) or numbered (<ol>) list.

TableDescriptor

Builds a table's <thead> and <tbody> rows.

TableRowDescriptor

Builds one table row's cells.

Color (struct)

A validated color. There is deliberately no implicit conversion from string: a typo like "rde" must fail at the call site (FromHex throws) rather than be silently ignored by the CSS engine. default(Color) is fully transparent.

Colors (static)

Common named colors, as Color values.

Named colors: Transparent, Black, White, Red, Green, Blue, Yellow, Orange, Purple, Pink, Brown, Navy, Teal, Gray, LightGray, DarkGray.

Length (struct)

A CSS length with its unit. A bare number converts implicitly to pixels, so Width(200) still works; use Mm, Percent etc. for anything else. default(Length) is 0px.

CssTransform (struct)

A 2D transform, composable with Then: CssTransform.Rotate(10).Then(CssTransform.Scale(1.2f)).

GridTrack (struct)

One column of a Grid.

PageSize (struct)

A page's physical dimensions in millimeters, matching CSS @page { size: ... }.

Keyword enums