QuestPDF

https://www.questpdf.com/
Admin
QuestPDF is a production-ready C# library for code-first PDF generation that enables developers to...
Tokens:132,364
Snippets:1,138
Trust Score:8.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install QuestPDF Previewer tool

Source: https://www.questpdf.com/document-previewer.html

Installs the QuestPDF Previewer as a global .NET tool on your local development environment.

```csharp
dotnet tool install QuestPDF.Previewer --global
```

--------------------------------

### Start QuestPDF Previewer application

Source: https://www.questpdf.com/document-previewer.html

Starts the standalone QuestPDF Previewer application. Optionally specify an HTTP port; the default is 12500.

```text
questpdf-previewer

// specify HTTP port on which previewer will communicate (default is 12500)
questpdf-previewer 12345
```

--------------------------------

### Install QuestPDF NuGet package

Source: https://www.questpdf.com/quick-start.html

Installs the QuestPDF NuGet package via the .NET CLI. Run this command in the terminal to add the QuestPDF package to your project.

```bash
dotnet add package QuestPDF
```

--------------------------------

### DebugArea example with grid layout

Source: https://www.questpdf.com/api-reference/debug-area.html

A complete example showing DebugArea with a grid layout. It sets width, height, padding, and uses a debug area with a label and color, then creates a 3-column grid with spacing and placeholder items.

```csharp
container
    .Width(250)
    .Height(250)
    .Padding(25)
    .DebugArea("Grid example", Colors.Blue.Medium)
    .Grid(grid =>
    {
        grid.Columns(3);
        grid.Spacing(5);

        foreach (var _ in Enumerable.Range(0, 8))
            grid.Item().Height(50).Placeholder();
    });
```

--------------------------------

### Example: AspectRatio with FitArea

Source: https://www.questpdf.com/api-reference/aspect-ratio.html

Example of constraining a container to a 3:4 aspect ratio with FitArea. The container is 300x300 and the content is centered and displayed with a grey background. Be aware that impossible constraints may cause a layout exception.

```csharp
container
    .Width(300)
    .Height(300)
    .AspectRatio(3f/4f, AspectRatioOption.FitArea)
    .Background(Colors.Grey.Lighten2)
    .AlignCenter()
    .AlignMiddle()
    .Text("3:4 Content Area");
```

--------------------------------

### Section and SectionLink Usage Example

Source: https://www.questpdf.com/api-reference/section.html

A complete C# example showing how to create a document with sections, section links, and page number references using QuestPDF's fluent API.

```APIDOC
## Section and SectionLink Usage Example

### Description
This example demonstrates how to use the `Section` and `SectionLink` methods in QuestPDF to create a document with a table of contents and linked content sections. It also shows how to display the page number of each section using `BeginPageNumberOfSection`.

### Code Example
```csharp
Document
    .Create(document =>
    {
        document.Page(page =>
        {
            page.Size(PageSizes.A5.Landscape());
            page.DefaultTextStyle(x => x.FontSize(20));
            page.Margin(25);

            page.Content()
                .Column(column =>
                {
                    var terms = new[]
                    {
                        ("Bit", "The smallest unit of data in computing, representing either a 0 or a 1. Multiple bits are combined to form bytes, which are used to store larger data values."),
                        ("Byte", "A unit of digital information that consists of 8 bits. A byte is commonly used to store a single character of text, such as a letter or a number, in computer memory."),
                        ("Binary", "A number system that uses only two digits, 0 and 1, which are the fundamental building blocks of computer operations. Computers process and store all data in binary format, including text, images, and instructions."),
                        ("Array", "A data structure that stores a fixed-size sequence of elements, all of the same type, in a contiguous block of memory. Arrays allow quick access to elements using an index and are commonly used to manage collections of data.")
                    };

                    // title
                    column.Item().Extend().AlignMiddle().AlignCenter().Text("Programming Glossary").FontSize(32).Bold();
                    column.Item().PageBreak();
                    
                    // table of contents
                    column.Item().PaddingBottom(25).Text("Table of Contents").FontSize(24).Bold().Underline();
                    
                    foreach (var term in terms)
                    {
                        column.Item()
                            .PaddingBottom(10)
                            .SectionLink($"term-{term}")
                            .Text(text =>
                            {
                                text.Span("Term ");
                                text.Span(term.Item1).Bold();
                                text.Span(" on page ");
                                text.BeginPageNumberOfSection($"term-{term}");
                            });
                    }
                    
                    // content
                    foreach (var term in terms)
                    {
                        column.Item().PageBreak();
                        
                        column.Item()
                            .Section($"term-{term}")
                            .Text(text =>
                            {
                                text.Span(term.Item1).Bold().FontColor(Colors.Blue.Darken2);
                                text.Span(" - ");
                                text.Span(term.Item2);
                            });
                    }
                });
        });
    })
    .GeneratePdf("sections.pdf");
```

### Methods Used
- `Section(string name)` - Defines a named section in the document.
- `SectionLink(string name)` - Creates a clickable link to a section.
- `BeginPageNumberOfSection(string name)` - Displays the page number where the specified section starts.

### Parameters
- `name` (string) - The unique identifier of the section. Must match between `Section` and `SectionLink`.

### Notes
- Sections can span multiple pages.
- Section links allow navigation to the designated section.
- Page numbers for sections are useful for tables of contents and cross-referencing.
```

--------------------------------

### Add image from binary array, file name, or stream

Source: https://www.questpdf.com/api-reference/image/basics.html

Shows three ways to add an image: from a byte array, a file name, or a stream. The binary array example reads a file with File.ReadAllBytes, the file name example uses a relative path, and the stream example uses a FileStream.

```csharp
// 1) a binary array
byte[] imageData = File.ReadAllBytes("path/to/logo.png")
container.Image(imageData)

// 2) a fileName
container.Image("path/myFile.png")

// 3) a stream
using var stream = new FileStream("logo.png", FileMode.Open);
container.Image(stream);
```

--------------------------------

### BackgroundColor example

Source: https://www.questpdf.com/concepts/prototyping.html

Creates a 5-column grid of 25 squares, each filled with a random bright background color. Useful for testing layout and color distribution.

```csharp
.Grid(grid =>
{
    grid.Columns(5);
    grid.Spacing(5);

    foreach (var _ in Enumerable.Range(0, 25))
    {
        grid.Item()
            .Height(50)
            .Width(50)
            .Background(Placeholders.BackgroundColor());
    }
});
```

--------------------------------

### C# Example: Combining SkipOnce and ShowOnce for Multi-Page Glossary Header

Source: https://www.questpdf.com/api-reference/skip-once.html

This example shows how to use SkipOnce and ShowOnce together to display a header that shows 'Continued' on the second and subsequent pages when a glossary term spans multiple pages. The SkipOnce element omits the ' (continued)' text on the first page, while ShowOnce ensures the term title appears only on the first page.

```csharp
container
    .Column(column =>
    {
        var terms = new[]
        {
            ("Repository", "A centralized storage location for source code and related files, typically managed using version control systems like Git. Repositories allow multiple developers to collaborate on projects, track changes, and maintain version history."),
            ("Version Control", "A system that tracks changes to code over time, enabling developers to collaborate efficiently, revert to previous versions, and maintain a structured development workflow. Popular version control tools include Git, Mercurial, and Subversion."),
            ("Abstraction", "A programming concept that hides complex implementation details and exposes only the necessary parts. Abstraction helps simplify code and allows developers to focus on high-level design rather than low-level implementation details."),
            ("Namespace", "A container that groups related identifiers, such as variables, functions, and classes, to prevent naming conflicts in a program. Namespaces are commonly used in large projects to organize code efficiently."),
        };
        
        column.Spacing(15);
        
        foreach (var term in terms)
        {
            column.Item().Decoration(decoration =>
            {
                decoration.Before()
                    .DefaultTextStyle(x => x.FontSize(24).Bold().FontColor(Colors.Blue.Darken2))
                    .Column(innerColumn =>
                    {
                        innerColumn.Item().ShowOnce().Text(term.Item1);
                        
                        innerColumn.Item().SkipOnce().Text(text =>
                        {
                            text.Span(term.Item1);
                            text.Span(" (continued)").Light().Italic();
                        });
                    });

                decoration.Content().Text(term.Item2);
            });
        }
    });
```

--------------------------------

### SkipOnce Example

Source: https://www.questpdf.com/api-reference/skip-once.html

Demonstrates combining SkipOnce and ShowOnce to display a 'Continued' header on the second and subsequent pages when a glossary term spans multiple pages.

```APIDOC
## SkipOnce

### Description
If the container spans multiple pages, its content is omitted on the first page and then displayed on the second and subsequent pages. A common use-case is displaying a consistent header across pages but conditionally showing/hiding specific fragments on the first page.

### Usage
- `container.SkipOnce().ShowOnce()` ensures the child element is displayed only on the second page.
- `container.SkipOnce().SkipOnce()` starts displaying the child element from the third page onwards.
- `container.ShowOnce().SkipOnce()` draws nothing, as the order of invocation is important.

### Example
```csharp
container
    .Column(column =>
    {
        var terms = new[]
        {
            ("Repository", "A centralized storage location for source code and related files, typically managed using version control systems like Git. Repositories allow multiple developers to collaborate on projects, track changes, and maintain version history."),
            ("Version Control", "A system that tracks changes to code over time, enabling developers to collaborate efficiently, revert to previous versions, and maintain a structured development workflow. Popular version control tools include Git, Mercurial, and Subversion."),
            ("Abstraction", "A programming concept that hides complex implementation details and exposes only the necessary parts. Abstraction helps simplify code and allows developers to focus on high-level design rather than low-level implementation details."),
            ("Namespace", "A container that groups related identifiers, such as variables, functions, and classes, to prevent naming conflicts in a program. Namespaces are commonly used in large projects to organize code efficiently."),
        };
        
        column.Spacing(15);
        
        foreach (var term in terms)
        {
            column.Item().Decoration(decoration =>
            {
                decoration.Before()
                    .DefaultTextStyle(x => x.FontSize(24).Bold().FontColor(Colors.Blue.Darken2))
                    .Column(innerColumn =>
                    {
                        innerColumn.Item().ShowOnce().Text(term.Item1);
                        
                        innerColumn.Item().SkipOnce().Text(text =>
                        {
                            text.Span(term.Item1);
                            text.Span(" (continued)").Light().Italic();
                        });
                    });

                decoration.Content().Text(term.Item2);
            });
        }
    });
```
```

--------------------------------

### Positive Padding Example

Source: https://www.questpdf.com/api-reference/padding.html

Adds empty space around content using positive padding values. The example sets vertical padding to 10, left padding to 20, and right padding to 40, with a background color to visualize the padding.

```csharp
container
    .Width(250)
    .PaddingVertical(10)
    .PaddingLeft(20)
    .PaddingRight(40)
    .Background(Colors.Grey.Lighten2)
    .Text("Sample text");
```

--------------------------------

### Run application with dotnet watch

Source: https://www.questpdf.com/document-previewer.html

Starts your application with hot-reload support when using the QuestPDF Previewer from the terminal.

```text
dotnet watch
```

--------------------------------

### DefaultTextStyle example with inheritance and overrides

Source: https://www.questpdf.com/api-reference/default-text-style.html

Complete example showing how DefaultTextStyle applies to all nested Text elements. Demonstrates inheritance, overriding with Underline(false) and FontColor, and a nested DefaultTextStyle that changes the underline type and font color.

```csharp
container
    .Width(400)
    .Padding(25)
    .DefaultTextStyle(x => x.Bold().Underline())
    .Column(column =>
    { 
        column.Spacing(10);
        
        column.Item().Text("Inherited bold and underline");
        
        column.Item()
            .Text("Disabled underline, inherited bold and adjusted font color")
            .Underline(false).FontColor(Colors.Green.Darken2);

        column.Item()
            .DefaultTextStyle(x => x.DecorationWavy().FontColor(Colors.LightBlue.Darken3))
            .Text("Changed underline type and adjusted font color");
    });
```

--------------------------------

### ScaleToFit container example in C#

Source: https://www.questpdf.com/api-reference/scale-to-fit.html

Shows how to use the ScaleToFit container to scale text content within a column of items with varying sizes. The example iterates over sizes from 200x100 to 450x175, applying a border, padding, and ScaleToFit to each item. Note that this container may introduce performance overhead for complex content and scales the available space, not the content directly.

```csharp
container.Column(column =>
{
    const string text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.";

    foreach (var i in Enumerable.Range(4, 5))
    {
        column
            .Item()
            .Shrink()
            .Border(1)
            .Padding(15)
            .Width(i * 50) // sizes from 200x100 to 450x175
            .Height(i * 25)
            .ScaleToFit()
            .Text(text);
    }
});
```

--------------------------------

### Color Property Example

Source: https://www.questpdf.com/api-reference/shadow.html

Demonstrates the Color property by applying red, green, and blue shadows with a blur of 10.

```csharp
.Row(row =>
{
    row.Spacing(50);
    
    var colors = new[]
    {
        Colors.Red.Darken2,
        Colors.Green.Darken2,
        Colors.Blue.Darken2
    };
    
    foreach (var color in colors)
    {
        row.ConstantItem(100)
            .AspectRatio(1)
            .Shadow(new BoxShadowStyle
            {
                Color = color,
                Blur = 10
            })
            .Background(Colors.White);
    }
});
```

--------------------------------

### Image scaling methods

Source: https://www.questpdf.com/api-reference/image/basics.html

Documentation for the Image element's scaling methods (FitWidth, FitHeight, FitArea, FitUnproportionally) and an example of their usage.

```APIDOC
## Image scaling

### Description
Controls how the Image element adjusts to available space. By default, the image scales to fill the full width of its container while maintaining its aspect ratio.

### Methods

#### FitWidth
Scales the image to fill the full width of its container. This is the default behavior.

#### FitHeight
Stretches the image vertically to fit the full available height. Often used with height-constraining elements like `Height`, `MaxHeight`, etc.

#### FitArea
Combines `FitWidth` and `FitHeight`. Resizes the image to utilize all available space, preserving its aspect ratio. Fills width or height based on container size. An optimal and safe choice.

#### FitUnproportionally
Adjusts the image to fill all available space, disregarding original proportions. This can lead to distorted scaling and is generally not recommended for most cases.

### Example
```csharp
.Column(column =>
{
    column.Item().PaddingBottom(5).Text("FitWidth").Bold();
    column.Item()
        .Width(200)
        .Height(150)
        .Border(4)
        .BorderColor(Colors.Red.Medium)
        .Image("photo.jpg")
        .FitWidth();

    column.Item().Height(15);

    column.Item().PaddingBottom(5).Text("FitHeight").Bold();
    column.Item()
        .Width(200)
        .Height(100)
        .Border(4)
        .BorderColor(Colors.Red.Medium)
        .Image("photo.jpg")
        .FitHeight();
    
    column.Item().Height(15);

    column.Item().PaddingBottom(5).Text("FitArea 1").Bold();
    column.Item()
        .Width(200)
        .Height(100)
        .Border(4)
        .BorderColor(Colors.Red.Medium)
        .Image("photo.jpg")
        .FitArea();
    
    column.Item().Height(15);
    
    column.Item().PaddingBottom(5).Text("FitArea 2").Bold();
    column.Item()
        .Width(200)
        .Height(150)
        .Border(4)
        .BorderColor(Colors.Red.Medium)
        .Image("photo.jpg")
        .FitArea();
    
    column.Item().Height(15);

    column.Item().PaddingBottom(5).Text("FitUnproportionally").Bold();
    column.Item()
        .Width(200)
        .Height(50)
        .Border(4)
        .BorderColor(Colors.Red.Medium)
        .Image("photo.jpg")
        .FitUnproportionally();
});
```

### Warning
This component may try to enforce size constraints that are impossible to meet. For example, the container may require more space than is available, or may try to squeeze its child into less space than possible. Such scenarios result in a layout exception.
```

--------------------------------

### Report columns configuration

Source: https://www.questpdf.com/concepts/dynamic-composition/configurable-tables.html

Creates a list of ReportColumn instances for the example report, specifying constant or relative sizing and property names.

```csharp
var reportColumns = new List<ReportColumn>
{
    new(Header: "SKU",        IsConstantWidth: true,  Size: 100, PropertyName: "sku"),
    new(Header: "Product",    IsConstantWidth: false, Size: 3,   PropertyName: "name"),
    new(Header: "Warehouse",  IsConstantWidth: false, Size: 2,   PropertyName: "warehouse"),
    new(Header: "In stock",   IsConstantWidth: true,  Size: 90,  PropertyName: "stock"),
    new(Header: "Unit price", IsConstantWidth: true,  Size: 110, PropertyName: "price")
};
```

--------------------------------

### Inlined usage example

Source: https://www.questpdf.com/api-reference/inlined.html

Shows how to configure the Inlined component with spacing, baseline alignment, and center alignment, then add multiple items using the RandomBlock helper.

```csharp
.Background(Colors.Grey.Lighten3)
.Padding(25)
.Border(1)
.Background(Colors.White)
.Inlined(inlined =>
{
    inlined.Spacing(25);
    inlined.BaselineMiddle();
    inlined.AlignCenter();
    
    foreach (var _ in Enumerable.Range(0, 15))
        inlined.Item().Element(RandomBlock);
});
```

--------------------------------

### Text placeholder example

Source: https://www.questpdf.com/concepts/prototyping.html

Shows how to display text placeholders in a column layout with a bold label and the placeholder value. Uses a local function AddItem to reduce repetition.

```csharp
.Column(column =>
{
    column.Spacing(15);

    AddItem("Name", Placeholders.Name());
    AddItem("Email", Placeholders.Email());
    AddItem("Phone", Placeholders.PhoneNumber());
    AddItem("Date", Placeholders.ShortDate());
    AddItem("Time", Placeholders.Time());
    
    void AddItem(string label, string value)
    {
        column.Item().Text(text =>
        {
            text.Span($"{label}: ").Bold();
            text.Span(value);
        });
    }
});
```

--------------------------------

### SimpleComponent: Generates a list of numbers from a range

Source: https://www.questpdf.com/api-reference/lazy.html

Defines a component that renders a title and a list of numbers from Start to End. Used by the normal, lazy, and lazy-with-cache examples.

```csharp
class SimpleComponent : IComponent
{
    public required int Start { get; init; }
    public required int End { get; init; }
    
    public void Compose(IContainer container)
    {
        container.Decoration(decoration =>
        {
            decoration.Before()
                .Text($"Numbers from {Start} to {End}")
                .FontSize(20).Bold().FontColor(Colors.Blue.Darken2);
        
            decoration.Content().Column(column =>
            {
                foreach (var i in Enumerable.Range(Start, End - Start + 1))
                    column.Item().Text($"Number {i}").FontSize(10);
            });
        });
    }
}
```

--------------------------------

### Generate a basic PDF with QuestPDF

Source: https://www.questpdf.com/quick-start.html

Creates a simple PDF document with a header, content column, and footer using QuestPDF's Fluent API. The example sets the page size to A4, a 2 cm margin, and a default font size of 20. It generates the PDF to "hello.pdf" and includes a commented line for setting the license.

```csharp
using QuestPDF.Fluent;
using QuestPDF.Helpers;
using QuestPDF.Infrastructure;

// TODO: set your license here:
// QuestPDF.Settings.License = LicenseType.Evaluation;

Document.Create(container =>
{
    container.Page(page =>
    {
        page.Size(PageSizes.A4);
        page.Margin(2, Unit.Centimetre);
        page.PageColor(Colors.White);
        page.DefaultTextStyle(x => x.FontSize(20));
        
        page.Header()
            .Text("Hello PDF!")
            .SemiBold().FontSize(36).FontColor(Colors.Blue.Medium);
        
        page.Content()
            .PaddingVertical(1, Unit.Centimetre)
            .Column(x =>
            {
                x.Spacing(20);
                
                x.Item().Text(Placeholders.LoremIpsum());
                x.Item().Image(Placeholders.Image(200, 100));
            });
        
        page.Footer()
            .AlignCenter()
            .Text(x =>
            {
                x.Span("Page ");
                x.CurrentPageNumber();
            });
    });
})
.GeneratePdf("hello.pdf");
```

--------------------------------

### Generate PDF files with overloads

Source: https://www.questpdf.com/concepts/generating-output.html

Shows how to create a document and generate PDF output using three overloads: saving to a file, returning a byte array, and saving to a stream.

```csharp
var document = Document.Create(document =>
{
    document.Page(page =>
    {
        page.Content().Text("Your invoice content");
    });
});

// generate PDF and save it to a file
document.GeneratePdf("document.pdf");

// generate PDF and return it as a byte array
var byteArray = document.GeneratePdf();

// generate PDF and save it to a stream
using var stream = new FileStream("document.pdf", FileMode.Create);
document.GeneratePdf(stream);
```

--------------------------------

### Without Blur (Fast) Example

Source: https://www.questpdf.com/api-reference/shadow.html

Applies shadows with Blur = 0 for a sharper appearance and better performance. Shows two squares with offset shadows, one with square corners and one with rounded corners.

```csharp
.Row(row =>
{
    row.Spacing(50);

    row.ConstantItem(100)
        .AspectRatio(1)
        .Shadow(new BoxShadowStyle
        {
            Color = Colors.Grey.Lighten1,
            Blur = 0, 
            OffsetX = 8,
            OffsetY = 8
        })
        .Border(1, Colors.Black)
        .Background(Colors.White);
    
    row.ConstantItem(100)
        .AspectRatio(1)
        .Shadow(new BoxShadowStyle
        {
            Color = Colors.Grey.Lighten1,
            Blur = 0,
            OffsetX = 8,
            OffsetY = 8
        })
        .Border(1, Colors.Black)
        .CornerRadius(16)
        .Background(Colors.White);
});
```

--------------------------------

### Generate images with custom settings

Source: https://www.questpdf.com/concepts/generating-output.html

Shows how to configure image generation settings (format, compression quality, DPI, transparent background) and use them with both overloads.

```csharp
using QuestPDF.Infrastructure;

var imageGenerationSettings = new ImageGenerationSettings
{
    ImageFormat = ImageFormat.Png,
    ImageCompressionQuality = ImageCompressionQuality.High,
    RasterDpi = 288,
    UseTransparentBackground = false
};

IEnumerable<byte[]> imagesAsByteArrays = document.GenerateImages(imageGenerationSettings);

// or

document.GenerateImages(imageIndex => $"image{imageIndex}.png", imageGenerationSettings);
```

--------------------------------

### StopPaging() example

Source: https://www.questpdf.com/api-reference/stop-paging.html

Use StopPaging() to render the element only on the first page, omitting any part that doesn't fit. The example shows a fixed-size container with a long book description; without StopPaging the content would flow to subsequent pages.

```csharp
const string bookDescription = "\"Master Modern C# Development\" is a comprehensive guide that takes you from the basics to advanced concepts in C# programming. Perfect for beginners and intermediate developers looking to enhance their skills with practical examples and real-world applications. Covering object-oriented programming, LINQ, asynchronous programming, and the latest .NET features, this book provides step-by-step explanations to help you write clean, efficient, and scalable code. Whether you're building desktop, web, or cloud applications, this resource equips you with the knowledge and best practices to become a confident C# developer.";

container
    .Width(400)
    .Height(300)
    .StopPaging()
    .Decoration(decoration =>
    {
        decoration.Before().Text("Book description:").Bold();
        decoration.Content().Text(bookDescription);
    });
```

--------------------------------

### Width example with MinWidth and MaxWidth

Source: https://www.questpdf.com/api-reference/width.html

Shows how text content adjusts to specified width constraints. The container sets an exact width of 300, with padding and a column that applies MinWidth(200) and MaxWidth(100) to items. Be aware that impossible constraints may cause a layout exception.

```csharp
container
    .Width(300)
    .Padding(25)
    .Column(column =>
    {
        column.Spacing(25);
        
        column.Item()
            .MinWidth(200)
            .Background(Colors.Grey.Lighten3)
            .Text("Lorem ipsum");
        
        column.Item()
            .MaxWidth(100)
            .Background(Colors.Grey.Lighten3)
            .Text("dolor sit amet");
    });
```

--------------------------------

### PreventPageBreak example in C#

Source: https://www.questpdf.com/api-reference/prevent-page-break.html

Use this method to keep a container's content together on its first page. The example shows a column with a fixed-height item and a text block wrapped with PreventPageBreak. If the text does not fit on the page, it moves to the next page.

```csharp
container.Column(column =>
{
    column.Item().Height(400).Background(Colors.Grey.Lighten3);
    column.Item().Height(30);

    column.Item()
        .PreventPageBreak()
        .Text(text =>
        {
            text.ParagraphSpacing(15);
            
            text.Span("Optimizing Content Placement").Bold().FontColor(Colors.Blue.Darken2).FontSize(24);
            text.Span("\n");
            text.Span("By carefully determining where to place a page break, you can avoid awkward text separations and maintain readability. Thoughtful formatting improves the overall user experience, making complex topics easier to digest.");
        });
});
```

--------------------------------

### Negative Padding Example

Source: https://www.questpdf.com/api-reference/padding.html

Uses a negative padding value to push content beyond the edges, increasing available space, similar to negative HTML margins. The example sets a base padding of 50 and then applies a horizontal padding of -25.

```csharp
container
    .Width(250)
    .Padding(50)
    .Background(Colors.Grey.Lighten2)
    .PaddingHorizontal(-25)
    .Text("Sample text with negative padding");
```

--------------------------------

### QuestPDF execution order example with Border, Background, Padding

Source: https://www.questpdf.com/concepts/code-patterns/execution-order.html

Shows how the order of chained methods (Border, Background, Padding) affects the visual result in QuestPDF. The four items demonstrate different orderings and label each with the sequence used. Use this to understand that method order is strict and changes the rendering outcome.

```csharp
container.Column(column =>
{
    column.Spacing(25);

    column.Item()
        .Border(1)
        .Background(Colors.Blue.Lighten4)
        .Padding(15)
        .Text("border → background → padding");
    
    column.Item()
        .Border(1)
        .Padding(15)
        .Background(Colors.Blue.Lighten4)
        .Text("border → padding → background");

    column.Item()
        .Background(Colors.Blue.Lighten4)
        .Padding(15)
        .Border(1)
        .Text("background → padding → border");
    
    column.Item()
        .Padding(15)
        .Border(1)
        .Background(Colors.Blue.Lighten4)
        .Text("padding → border → background");
});
```

--------------------------------

### Color Property

Source: https://www.questpdf.com/api-reference/shadow.html

Gets or sets the color of the shadow.

```APIDOC
## Color Property

### Description
Gets or sets the color of the shadow.

### Property
Color (Color)

### Example
```csharp
.Row(row =>
{
    row.Spacing(50);
    
    var colors = new[]
    {
        Colors.Red.Darken2,
        Colors.Green.Darken2,
        Colors.Blue.Darken2
    };
    
    foreach (var color in colors)
    {
        row.ConstantItem(100)
            .AspectRatio(1)
            .Shadow(new BoxShadowStyle
            {
                Color = color,
                Blur = 10
            })
            .Background(Colors.White);
    }
});
```
```

--------------------------------

### Apply image fitting options FitWidth, FitHeight, FitArea, FitUnproportionally

Source: https://www.questpdf.com/api-reference/image/basics.html

Shows how to apply each fitting option (FitWidth, FitHeight, FitArea, FitUnproportionally) to an Image element inside a Column. Each option is demonstrated with a bordered image of a specific size. Note that FitUnproportionally can distort the image and may cause layout exceptions if constraints are impossible to meet.

```csharp
.Column(column =>
{
    column.Item().PaddingBottom(5).Text("FitWidth").Bold();
    column.Item()
        .Width(200)
        .Height(150)
        .Border(4)
        .BorderColor(Colors.Red.Medium)
        .Image("photo.jpg")
        .FitWidth();

    column.Item().Height(15);

    column.Item().PaddingBottom(5).Text("FitHeight").Bold();
    column.Item()
        .Width(200)
        .Height(100)
        .Border(4)
        .BorderColor(Colors.Red.Medium)
        .Image("photo.jpg")
        .FitHeight();
    
    column.Item().Height(15);

    column.Item().PaddingBottom(5).Text("FitArea 1").Bold();
    column.Item()
        .Width(200)
        .Height(100)
        .Border(4)
        .BorderColor(Colors.Red.Medium)
        .Image("photo.jpg")
        .FitArea();
    
    column.Item().Height(15);
    
    column.Item().PaddingBottom(5).Text("FitArea 2").Bold();
    column.Item()
        .Width(200)
        .Height(150)
        .Border(4)
        .BorderColor(Colors.Red.Medium)
        .Image("photo.jpg")
        .FitArea();
    
    column.Item().Height(15);

    column.Item().PaddingBottom(5).Text("FitUnproportionally").Bold();
    column.Item()
        .Width(200)
        .Height(50)
        .Border(4)
        .BorderColor(Colors.Red.Medium)
        .Image("photo.jpg")
        .FitUnproportionally();
});
```

--------------------------------

### Create a basic table with header and data rows

Source: https://www.questpdf.com/api-reference/table/basics.html

Creates a basic table with a header row and six data rows. Defines columns using ConstantColumn and RelativeColumn, and uses the Header method to style header cells with borders and padding.

```csharp
.Table(table =>
{
    table.ColumnsDefinition(columns =>
    {
        columns.ConstantColumn(50);
        columns.RelativeColumn();
        columns.ConstantColumn(125);
    });

    table.Header(header =>
    {
        header.Cell().BorderBottom(2).Padding(8).Text("#");
        header.Cell().BorderBottom(2).Padding(8).Text("Product");
        header.Cell().BorderBottom(2).Padding(8).AlignRight().Text("Price");
    });
    
    foreach (var i in Enumerable.Range(0, 6))
    {
        var price = Math.Round(Random.Shared.NextDouble() * 100, 2);
         
        table.Cell().Padding(8).Text($"{i + 1}");
        table.Cell().Padding(8).Text(Placeholders.Label());
        table.Cell().Padding(8).AlignRight().Text($"${price}");
    }
});
```

--------------------------------

### Repeat element example in C#

Source: https://www.questpdf.com/api-reference/repeat.html

Uses the Repeat element to render a term label on every page where its definition appears. The example defines a list of terms and uses Decoration with Before and Content sections, applying Repeat() to the term text so it repeats across pages.

```csharp
container
    .Decoration(decoration =>
    {
        var terms = new[]
        {
            ("Algorithm", "A precise set of instructions that defines a process for solving a specific problem or performing a computation. Algorithms are the foundation of programming and are used to optimize tasks efficiently."),
            ("Bug", "An error, flaw, or unintended behavior in a program that causes it to produce incorrect or unexpected results. Debugging is the process of identifying, analyzing, and fixing these issues to improve software reliability."),
            ("Variable", "A named storage location in memory that holds a value, which can be modified during program execution. Variables make code dynamic and flexible by allowing data manipulation and retrieval."),
            ("Compilation", "The process of transforming human-readable source code into machine code (binary instructions) that a computer can execute. This process is performed by a compiler and often includes syntax checks, optimizations, and linking dependencies.")
        };
        
        decoration.Before().Text("Terms and their definitions:").Bold();
        
        decoration.Content().PaddingTop(15).Column(column =>
        {
            foreach (var term in terms)
            {
                column.Item().Row(row =>
                {
                    row.RelativeItem(2)
                        .Border(1)
                        .Background(Colors.Grey.Lighten3)
                        .Padding(15)
                        .Repeat()
                        .Text(term.Item1);
                
                    row.RelativeItem(3)
                        .Border(1)
                        .Padding(15)
                        .Text(term.Item2);
                });
            }
        });
    });
```

--------------------------------

### StopPaging

Source: https://www.questpdf.com/api-reference/stop-paging.html

Example demonstrating the StopPaging method on a container element.

```APIDOC
## StopPaging

### Description
Renders the element exclusively on the first page. Any portion of the element that doesn't fit is omitted.

### Method
Element extension method

### Usage
Call `.StopPaging()` on a container element to restrict it to the first page.

### Parameters
None

### Example
```csharp
const string bookDescription = "\"Master Modern C# Development\" is a comprehensive guide that takes you from the basics to advanced concepts in C# programming. Perfect for beginners and intermediate developers looking to enhance their skills with practical examples and real-world applications. Covering object-oriented programming, LINQ, asynchronous programming, and the latest .NET features, this book provides step-by-step explanations to help you write clean, efficient, and scalable code. Whether you're building desktop, web, or cloud applications, this resource equips you with the knowledge and best practices to become a confident C# developer.";

container
    .Width(400)
    .Height(300)
    .StopPaging()
    .Decoration(decoration =>
    {
        decoration.Before().Text("Book description:").Bold();
        decoration.Content().Text(bookDescription);
    });
```
```

--------------------------------

### Solid Color Border Example (C#)

Source: https://www.questpdf.com/api-reference/border.html

Applies a solid color border to relative items in a row. Uses predefined colors from the Colors palette and sets border width to 5. The example iterates over an array of colors and applies each to a separate item with padding and font color matching the border.

```csharp
.Row(row =>
{
    var colors = new[]
    {
        Colors.Red.Medium,
        Colors.Green.Medium,
        Colors.Blue.Medium
    };
    
    row.Spacing(25);
    
    foreach (var color in colors)
    {
        row.RelativeItem()
            .Border(5)
            .BorderColor(color)
            .Padding(15)
            .Text(color)
            .FontColor(color);
    }
});
```

--------------------------------

### Create an unordered list with bullet point images

Source: https://www.questpdf.com/api-reference/lists.html

Creates an unordered list by prepending each item with a bullet point image. Uses a Column with spacing and a Row per item, with a constant-width image column and a relative text column.

```csharp
container.Column(column =>
{
    column.Spacing(10);
    
    foreach (var i in Enumerable.Range(1, 7))
    {
        column.Item().Row(row =>
        {
            row.ConstantItem(26).Image("Resources/bulletpoint.png");
            row.ConstantItem(5);
            row.RelativeItem().Text(Placeholders.Label());
        });
    }
});
```

--------------------------------

### Generate a basic PDF with QuestPDF

Source: https://www.questpdf.com

Creates a simple PDF document with A4 size, 32-unit margin, and a centered text element with font size 24, then generates and shows the PDF.

```csharp
Document
    .Create(document =>
    {
        document.Page(page =>
        {
            page.Size(PageSizes.A4);
            page.Margin(32);

            page.Content()
                .Text("Hello PDF!")
                .FontSize(24);
        });
    })
    .GeneratePdfAndShow();
```

--------------------------------

### Layers

Source: https://www.questpdf.com/api-reference/layers.html

Documentation for the Layers element in QuestPDF, including its methods and usage example.

```APIDOC
## Layers

### Description
The Layers element adds content either underneath (as a background) or on top of (as a watermark) the main content. The main layer supports paging, can span multiple pages, and determines the container's target length. Additional layers can also span multiple pages and are repeated on each one.

### Methods
- **PrimaryLayer** - Sets the primary content for the container.
- **Layer** - Specifies an additional layer for the container.

### Usage Notes
- Exactly one `PrimaryLayer` must be defined.
- The order of code execution determines the drawing order:
  - If the layer is defined before the primary layer, it's drawn underneath the primary content (as a background).
  - If defined after the primary layer, it's drawn in front of the primary content (as a watermark).

### Example
A common use-case for this element is to add background content behind the main content.

```csharp
.Column(column =>
{
    column.Item().PaddingBottom(15).Text("Proposed Business Card Design:").Bold();
    
    column.Item()
        .AspectRatio(4 / 3f)
        .Layers(layers =>
        {
            layers.Layer().Image("Resources/card-background.jpg").FitUnproportionally();

            layers.PrimaryLayer()
                .OffsetY(75)
                .Column(innerColumn =>
                {
                    innerColumn.Item()
                        .AlignCenter()
                        .Text("Horizon Ventures")
                        .Bold().FontSize(32).FontColor(Colors.Blue.Darken2);

                    innerColumn.Item().AlignCenter().Text("Your journey begins here");
                });
        });
});
```
```

--------------------------------

### AspectRatio

Source: https://www.questpdf.com/api-reference/aspect-ratio.html

Documentation for the AspectRatio method in QuestPDF, including fitting options and an example.

```APIDOC
## AspectRatio

### Description
Constrains its content to maintain a given width-to-height ratio. The ratio can be specified as a number or a division of two numbers. Optionally, you can specify how the content should be adjusted to meet the aspect ratio.

### Method
AspectRatio

### Parameters
#### Ratio
- **ratio** (float) - Required - The width-to-height ratio. Can be a number or a division of two numbers.

#### Fitting Option (optional)
- **option** (AspectRatioOption) - Optional - Specifies how the content should be adjusted to meet the aspect ratio. Default is `AspectRatioOption.FitWidth`.

### Fitting Options
- **AspectRatioOption.FitWidth** - Adjusts content to occupy the full width available. Used as the default setting.
- **AspectRatioOption.FitHeight** - Adjusts content to fill the available height. Often used with height-constraining elements.
- **AspectRatioOption.FitArea** - Adjusts content to fill the available area while maintaining its aspect ratio. May result in the content fully occupying either the width or height, depending on its dimensions. Often used with constraining elements.

### Example
```csharp
container
    .Width(300)
    .Height(300)
    .AspectRatio(3f/4f, AspectRatioOption.FitArea)
    .Background(Colors.Grey.Lighten2)
    .AlignCenter()
    .AlignMiddle()
    .Text("3:4 Content Area");
```

### Warning
This component may try to enforce size constraints that are impossible to meet, resulting in a layout exception. Be careful when using it with constrained containers.
```

--------------------------------

### Set QuestPDF license type at startup

Source: https://www.questpdf.com/license/configuration.html

Place one of these lines at application startup to configure the license. Choose Community, Professional, or Enterprise based on eligibility. The library performs no network calls and all computations are local.

```csharp
QuestPDF.Settings.License = LicenseType.Community;
// or
QuestPDF.Settings.License = LicenseType.Professional;
// or
QuestPDF.Settings.License = LicenseType.Enterprise;
```

--------------------------------

### AlignBottom and AlignCenter example

Source: https://www.questpdf.com/api-reference/alignment.html

Shows how to combine vertical and horizontal alignment on a container. The container is sized 300x300, aligned to bottom and center, with a grey background and padding, containing a text element.

```csharp
container
    .Width(300)
    .Height(300)
    .AlignBottom()
    .AlignCenter()
    .Background(Colors.Grey.Lighten2)
    .Padding(10)
    .Text("Test");
```

--------------------------------

### Column Spacing with unit

Source: https://www.questpdf.com/api-reference/column.html

Optionally, you can specify the unit value for Spacing. The default is Unit.Points; this example uses Unit.Millimeters.

```csharp
column.Spacing(5, Unit.Millimeters);
```

--------------------------------

### Applying Predefined Typography

Source: https://www.questpdf.com/api-reference/text/basics.html

Demonstrates how to apply a predefined typography style compared to manual styling.

```csharp
container
    .Text("Report #123")
    .Style(Typography.Title);
    
// instead of

container    
    .Text("Report #123")
    .FontFamily("Helvetica")
    .FontColor(Colors.Black)
    .FontSize(20)
    .Bold();
```

--------------------------------

### Encrypt with Encryption256Bit

Source: https://www.questpdf.com/concepts/document-operations.html

Encrypts the PDF with 256-bit encryption, setting user and owner passwords and permissions similar to the 128-bit example.

```csharp
DocumentOperation
    .LoadFile("input.pdf")
    .Encrypt(new Encryption256Bit
    {
        UserPassword = "user123",
        OwnerPassword = "owner456",
        AllowPrinting = true,
        AllowModification = false,
        AllowContentExtraction = false,
        AllowFillingForms = true,
        AllowAssembly = false,
        AllowAnnotation = true,
        EncryptMetadata = true
    })
    .Save("encrypted-256bit.pdf");
```

--------------------------------

### ShowOnce Invoice Header Example

Source: https://www.questpdf.com/api-reference/show-once.html

Creates a professional invoice header using ShowOnce to display different content on the first page versus subsequent pages. The header includes a logo placeholder, invoice details, and a title that appears only on the first page. The content area generates dummy rows to demonstrate multi-page behavior.

```csharp
container
    .Decoration(decoration =>
    {
        decoration.Before().Column(column =>
        {
            column.Item()
                .ShowOnce()
                .Row(row =>
                {
                    row.ConstantItem(80).AspectRatio(4 / 3f).Placeholder();
                    row.ConstantItem(10);
                    row.RelativeItem()
                        .AlignMiddle()
                        .Column(innerColumn =>
                        {
                            innerColumn.Item().Text("Invoice #1234").FontSize(24).Bold();
                            innerColumn.Item().Text($"Generated on {DateTime.Now:d}").FontSize(16).Light();
                        });
                });
            
            column.Item()
                .SkipOnce()
                .Text("Invoice #1234").FontSize(24).Bold();
        });
        
        // generate dummy content
        decoration.Content()
            .PaddingTop(15)
            .ExtendHorizontal()
            .Column(column =>
            {
                column.Spacing(10);
                
                foreach (var i in Enumerable.Range(1, 15))
                {
                    column.Item()
                        .Height(30)
                        .Background(Colors.Grey.Lighten3)
                        .AlignCenter()
                        .AlignMiddle()
                        .Text($"{i}");
                }
            });
    });
```

--------------------------------

### Configure QuestPDF license in ASP.NET

Source: https://www.questpdf.com/examples/aspnet-integration.html

Configure the QuestPDF license in Startup.cs or Program.cs. This code should be executed only once, when the application starts or during its initialization step.

```csharp
// please kindly ensure what license is appropriate for your project
QuestPDF.Settings.License = LicenseType.Community;
```
Tokens:
Raw