Row & Column Layout in TerraPDF

Core Concept

The name describes how children are arranged, not the shape of the container itself.

Element	Direction	Axis
`Column`	Top → Bottom	Vertical
`Row`	Left → Right	Horizontal

Column

A Column stacks its children vertically, one below the other — like a column of text in a newspaper.

Code

┌──────────────────┐
│     Item 1       │
├──────────────────┤
│     Item 2       │
├──────────────────┤
│     Item 3       │
└──────────────────┘

Fluent API

container.Column(col =>
{
    col.Spacing(10); // vertical gap between items in points

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

What happens internally

Measure() accumulates height for each item and tracks the maximum width.
Draw() advances the cursor downward (curY) after each item.

Row

A Row arranges its children horizontally, side by side — like seats in a cinema row.

Code

┌──────────┬──────────┬──────────┐
│  Item 1  │  Item 2  │  Item 3  │
└──────────┴──────────┴──────────┘

Fluent API

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

    row.AutoItem().Text("Auto-sized");        // takes its natural content width
    row.RelativeItem(2).Text("2x wide");      // takes 2x the share of remaining space
    row.RelativeItem(1).Text("1x wide");      // takes 1x the share of remaining space
    row.ConstantItem(80).Text("Fixed 80pt");  // always exactly 80 points wide
});

Item sizing options

Method	Behaviour
`AutoItem()`	Width = natural content width (measured first)
`RelativeItem(weight = 1)`	Width = proportional share of remaining space after auto/constant items (default weight = 1)
`ConstantItem(pts)`	Width = fixed number of PDF points, always

What happens internally

CalculateWidths() resolves all item widths from available space.
Measure() accumulates widths and tracks the maximum height.
Draw() advances the cursor to the right (curX) after each item.

Combining Row & Column

Row and Column are designed to be nested freely to build any layout.

Example: Two-column page layout

// Side-by-side columns, each containing stacked content
container.Row(row =>
{
    row.RelativeItem().Column(left =>
    {
        left.Spacing(8);
        left.Item().Text("Left heading");
        left.Item().Text("Left body text...");
    });

    row.ConstantItem(20); // spacer

    row.RelativeItem().Column(right =>
    {
        right.Spacing(6);
        right.Item().Text("Right heading");
        right.Item().Text("Right body text...");
    });
});

Result:

Code

┌─────────────────────┬────┬─────────────────────┐
│  Left heading       │    │  Right heading       │
│  Left body text...  │    │  Right body text...  │
└─────────────────────┴────┴─────────────────────┘

Example: Header + body + footer (Column wrapping Rows)

container.Column(page =>
{
    page.Spacing(12);

    // Header row
    page.Item().Row(header =>
    {
        header.RelativeItem().Text("Logo");
        header.RelativeItem().Text("Title");
        header.AutoItem().Text("Page 1");
    });

    // Body content
    page.Item().Text("Main body paragraph text goes here...");

    // Footer row
    page.Item().Row(footer =>
    {
        footer.RelativeItem().Text("Company Name");
        footer.AutoItem().Text("Confidential");
    });
});

Result:

Code

┌──────────────────────────────────────────┐
│  Logo          Title            Page 1   │  ← Row (header)
├──────────────────────────────────────────┤
│  Main body paragraph text goes here...   │  ← Column item
├──────────────────────────────────────────┤
│  Company Name                Confidential│  ← Row (footer)
└──────────────────────────────────────────┘

Quick Reference

Code

Column  =  vertical stacking   (think: stack of pancakes)
Row     =  horizontal stacking (think: seats in a cinema row)

Tip: This is the same convention used by CSS Flexbox (flex-direction: column / row), Flutter (Column / Row widgets) — so the mental model transfers directly.

← Components & Templates README →