--pdf-page-placeholder-size

Works in all major browsers
Since July 2026

WebPDF works in Chrome and Edge 125, Firefox 153 and Safari 18, on desktop and mobile, and in every later version: the oldest versions its PDF.js build supports, which already have every platform feature WebPDF needs. Since July 2026, that is every major browser.

The --pdf-page-placeholder-size CSS custom property sets the box a <pdf-page> keeps while its PDF is on the way: a paper, a size or a ratio. It is typed: WebPDF registers it with CSS.registerProperty(), so it inherits and starts out as auto, the paper of the visitor's region.

Syntax

css
/* Keyword values */
--pdf-page-placeholder-size: auto;
--pdf-page-placeholder-size: none;

/* Paper names, turned or not */
--pdf-page-placeholder-size: A4;
--pdf-page-placeholder-size: letter landscape;
--pdf-page-placeholder-size: "4A0";

/* A width and a height, or one length for a square */
--pdf-page-placeholder-size: 210mm 297mm;
--pdf-page-placeholder-size: 30rem;

/* Ratios */
--pdf-page-placeholder-size: 1.5;
--pdf-page-placeholder-size: calc(16 / 9);
--pdf-page-placeholder-size: "16 / 9";

/* Global values */
--pdf-page-placeholder-size: inherit;
--pdf-page-placeholder-size: initial;
--pdf-page-placeholder-size: revert;
--pdf-page-placeholder-size: revert-layer;
--pdf-page-placeholder-size: unset;

Values

auto

The paper of the visitor's region: US Letter where it is the norm, A4 everywhere else. This is the initial value. With break=hint on the script, it reserves no box.

none

No box: the page has no size until its PDF arrives.

A paper name

Such as A4, letter, A5 or legal, in any case, from the names of paper.rt.ht: the box has that paper's size at the page's scale. Add portrait or landscape, in either order, to turn it; landscape alone turns the visitor's paper. Names that are not CSS identifiers, such as 4A0, C7/6 or 11×15, are written as strings: "4A0".

One or two lengths

A width and a height, such as 210mm 297mm, in any length unit; one length gives a square. They are used as given, not multiplied by scale.

A ratio

A width-to-height ratio, as a number such as 1.5 or calc(16 / 9), or as a string such as "16 / 9". The box keeps the area of the visitor's paper, so calc(297 / 210) is A4 in landscape.

Description

Before its PDF arrives, a page already has a box, so the layout does not move when the page draws. A size remembered from an earlier visit comes first; this property gives the box on a first visit, and the PDF's own page size replaces it as soon as the page knows it. See Lazy pages and placeholders.

The property is inherited, like the size of a printed page it is modelled on: set it on :root for every page, on any ancestor, or on a page. A <pdf-file> passes it on only to the pages inside it; pages that name their file with of sit elsewhere in the document, so select them, for example with pdf-page[of=slides].

Because it is registered, its value is checked when the page's style is computed, and lengths are converted to pixels. A value that fits none of the forms, such as an unquoted 16 / 9 or a paper name with a length, is invalid at computed-value time: it acts like unset, so the page takes its parent's value. Keywords and paper names work in any case, and a paper name WebPDF does not know gives the visitor's paper.

Registered properties have no ratio type, so write a ratio as a number, such as calc(16 / 9), or quote it. Unlike aspect-ratio or contain-intrinsic-size on the page, the property only shapes the waiting box and never outlasts it.

While a page waits, its box follows the value: a class, a media query or a container query changes it at once, and a page off screen takes the new value when it comes into view.

Formal definition

Initial valueauto
Applies to<pdf-page> elements
Inheritedyes
Computed valueas specified, with lengths made absolute
Animation typediscrete

Formal syntax

css
--pdf-page-placeholder-size =
  auto | none | <paper-size> | <length [0,∞]>{1,2} | <ratio>

<paper-size> = [ <custom-ident> | <string> ] || [ portrait | landscape ]
<ratio>      = <number [0,∞]> | <string>

Examples

A4 boxes for every page

When all your PDFs are A4, every page reserves an A4 box, wherever your readers are:

css
:root {
  --pdf-page-placeholder-size: A4;
}

Slides

Pages that name their file with of take the file's value through a selector:

html
<pdf-file id=slides src=slides.pdf></pdf-file>
<pdf-page of=slides no=1 loading=lazy></pdf-page>
<pdf-page of=slides no=2 loading=lazy></pdf-page>
css
pdf-page[of="slides"] {
  --pdf-page-placeholder-size: calc(16 / 9);
}

An exact box

css
pdf-page.handout {
  --pdf-page-placeholder-size: 210mm 297mm;
}

Turning with the screen

A media query can turn the paper:

css
:root {
  --pdf-page-placeholder-size: letter;
}
@media (orientation: landscape) {
  :root {
    --pdf-page-placeholder-size: letter landscape;
  }
}

Specifications

Not part of any specification. <pdf-file> and <pdf-page> are autonomous custom elements defined by WebPDF.pro. It implements:

Specification
CSS Properties and Values API Level 1
# the-registerproperty-function
CSS Paged Media Module Level 3
# page-size-prop
CSS Box Sizing Module Level 4
# aspect-ratio

Browser compatibility

desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
--pdf-page-placeholder-size
1251251531111812515383182712518
Quoted values
1251251531111812515383182712518
  • Quoted values · Chrome, Edge, Opera, Chrome Android, Opera Android, Samsung Internet, WebView Android: Quoted values need Chromium 131 or later; before, a quoted value is ignored and the page takes its parent's value.
  • Quoted values · Safari, Safari on iOS, WebView on iOS: Quoted values need Safari 18.2 or later; before, a quoted value is ignored and the page takes its parent's value.

Legend

Full support
Partial support
See implementation notes.

See also