Lazy pages and placeholders

A document with many pages should not draw them all at once, and a page should not jump into place when its PDF arrives. This article shows how <pdf-page> waits: lazy pages draw only when they come near, and placeholders keep each page's box in the layout before the PDF is there.

Lazy pages

With loading=lazy, like on an <img>, a page gets its size as soon as the file has loaded, and draws when it comes within one viewport of the visible area, or when the browser finds text in it, focuses it or prints it. Inside a scrolling element, such as a viewer's pane or a grid of thumbnails, it draws when it comes within one scrollport of the element's visible part (in Safari before 26, when it shows). In an <iframe>, the viewport is the frame's own, as long as the frame itself is near the visible area:

Lazy pages

Scroll the frame: each page draws as it comes near.

html
<pdf-file id=f src=//pdf.ist/web.pdf></pdf-file>
<pdf-page of=f no=1 loading=lazy scale=0.4></pdf-page>
<pdf-page of=f no=2 loading=lazy scale=0.4></pdf-page>
<pdf-page of=f no=3 loading=lazy scale=0.4></pdf-page>
<pdf-page of=f no=4 loading=lazy scale=0.4></pdf-page>

A lazy page fires load once it has its size and render once it has drawn, and matches :state(pending) until then. A lazy PDFium page also waits to load PDFium, and a file whose pages are all lazy waits to verify its signatures.

The pages on screen draw first. A page that comes near while one on screen is still drawing waits until the screen has drawn, so drawing ahead never slows down what readers see.

Pages have content-visibility: auto built in, too: off-screen pages skip layout and paint, and keep their size.

Placeholders

Before its PDF arrives, a page already has a box, so the layout does not move when the page draws. The box is the first of these that applies:

  1. The page's own size, remembered from an earlier visit.
  2. The --pdf-page-placeholder-size custom property: a paper name, a size or a ratio.
  3. The paper of the visitor's region: US Letter where it is the norm, A4 everywhere else.

Remembered sizes

Every page remembers its size in localStorage, per file and page number. On the next visit, the box is right before the PDF has loaded.

Paper names, sizes and ratios

On a first visit, --pdf-page-placeholder-size gives the box. It takes a paper name, such as A4, letter, A5 or legal, in any case, from the names of paper.rt.ht, with portrait or landscape if you like; a width and a height in any unit, used as given and not multiplied by scale; or a ratio, such as 1.5 or calc(16 / 9), which keeps the area of the visitor's paper. It is inherited, so set it on :root for every page and on a file's pages for their own:

css
:root {
  --pdf-page-placeholder-size: A4;
}
pdf-page[of="slides"] {
  --pdf-page-placeholder-size: calc(16 / 9);
}
pdf-page.handout {
  --pdf-page-placeholder-size: 210mm 297mm;
}

none reserves no box: the page has no size until its PDF arrives. While a page waits, its box follows the property, so a media query can change it too.

The visitor's paper

Without any of these, the box is the paper of the visitor's region, from the browser's language: US Letter in the United States, Canada, Mexico, the Philippines and the other countries where it is the norm, A4 everywhere else.

Turning it off

Token on the scriptTurns off
break=content-visibilityThe built-in content-visibility: auto of pages.
break=lazyloading=lazy: every page draws at once.
break=hintRemembered page sizes and the regional paper that reserve boxes before a PDF loads (an explicit --pdf-page-placeholder-size still does).

You can also opt one page out of content-visibility with CSS: pdf-page { content-visibility: visible; }.

Printing every page

A lazy page draws when it is printed, but a print starts at once. To print a long document completely, make its lazy pages eager first:

js
await Promise.all([...document.querySelectorAll("pdf-page[loading=lazy]")].map((page) => {
  page.loading = "eager";
  return page.update();
}));
print();

See also