Lazy Loading

Modern web pages often load content progressively as the user scrolls — images that only load when they enter the viewport, infinite-scroll feeds, or charts that render on first visibility. CobaltPdf's lazy load feature simulates user scrolling before the PDF is captured so this deferred content is included.

How It Works

When lazy loading is enabled, CobaltPdf scrolls the page in half-page increments before capturing the PDF. After each step it waits for the configured delay to allow network requests triggered by the scroll to complete. At the end it scrolls back to the top, waits a brief settle period, and then captures.

Scrolling is parameterised by the paper height for the current render (A4, Letter, etc.), so "5 pages" means 5 actual PDF-page-heights of scroll distance regardless of the paper format.

Basic Usage

// Scroll 5 viewport-heights before capturing
var pdf = await renderer
    .WithLazyLoadPages(5)
    .RenderUrlAsPdfAsync("https://example.com/news-feed");

Parameters

var pdf = await renderer
    .WithLazyLoadPages(
        pageCount: 10,                          // scroll 10 page-heights
        delay:     TimeSpan.FromMilliseconds(300), // pause between steps (default: 200 ms)
        timeout:   TimeSpan.FromSeconds(60)        // max total scroll time (default: 30 s)
    )
    .RenderUrlAsPdfAsync("https://example.com/long-report");

Parameter Reference

Parameter	Type	Default	Description
`pageCount`	`int`	required	Number of PDF page-heights to scroll
`delay`	`TimeSpan?`	200 ms	Pause between each scroll step — give the page time to load new content
`timeout`	`TimeSpan?`	30 s	Maximum total scroll time before stopping

Termination Conditions

Scrolling stops when any of these conditions is met:

The target scroll distance (pageCount × pageHeight) has been reached
The bottom of the page has been reached (no more content to scroll)
The page height has not changed after 10 consecutive steps (stall detection)
The total scroll time exceeds timeout

After any termination condition, the page scrolls back to the top before the PDF is captured.

Tuning

Too fast (content missing): Increase delay to give the page more time to load images after each scroll.

Too slow: Decrease delay or pageCount to reduce total scroll time.

Infinite scroll feeds: If the page generates content indefinitely, set pageCount to the number of pages you want in the PDF. Stall detection will stop scrolling if the page stops growing.

// A page that loads slowly — generous delay
var pdf = await renderer
    .WithLazyLoadPages(8, delay: TimeSpan.FromMilliseconds(500))
    .RenderUrlAsPdfAsync("https://example.com/image-heavy-gallery");

Combining with Wait Strategies

Lazy loading runs before the configured wait strategy. This means you can scroll to trigger content and then wait for a final signal:

var pdf = await renderer
    .WithLazyLoadPages(5)
    .WaitFor(WaitOptions.ForSelector("#all-content-loaded"))
    .RenderUrlAsPdfAsync("https://example.com/dashboard");

Debugging

Enable browser console logging to see scroll progress in your application output:

CobaltEngine.LoggingMode = BrowserLoggingMode.Console;

Lazy load progress is logged at each step:

[Cobalt] LazyLoad: target=5 pages (5615px), pageHeight=1123px, step=561px, delay=200ms
[Cobalt] LazyLoad: ~0.5 pages scrolled (561px / 12340px total)
[Cobalt] LazyLoad: ~1.0 pages scrolled (1122px / 12340px total)
...
[Cobalt] LazyLoad: ~5.0 pages scrolled (5615px / 12340px total)

Table of Contents