<pdf-page> PDF page element

Try it

<pdf-file id=f src=//pdf.ist/web.pdf></pdf-file>

<pdf-page of=f controls scale=0.5></pdf-page>

pdf-page {
  --pdf-page-background-color: oklch(99% 0.01 90);
}

The above example shows the first page of a PDF with the viewer controls: hover it for the bar, or click it and press →, E or F.

Attributes

This element includes the global attributes. Attributes marked as multi-homed also work on the WebPDF <script> and (for pages) on the <pdf-file>: the nearest element that has one wins; see Multi-homed attributes.

-

Space-separated tokens for parts of the page to leave out: text (the text layer), anno (links and form fields, which are then drawn into the image), drop (dropping files and links on the page), controls (all controls, whatever controls says) and js (PDF.js, on a page that PDFium draws: PDFium reads it alone). A token prefixed with - keeps an inherited part on. See PDFPageElement.off. Multi-homed.

canvas

Which engine draws the page on its canvas:

.js

PDF.js. This is the default unless the file has ium, or the script ium=+.

ium

PDFium, compiled to WebAssembly. The default for a file with ium, and for every file under <script ium=+>; without ium on the file or the script, PDF.js draws.

controls

A Boolean attribute: the page gets viewer controls: keys once it has focus, a bar on hover or tap, and touch gestures. controls=- turns inherited controls off. See PDFPageElement.controls. Multi-homed.

controlslist

Space-separated tokens for controls to leave out, like <video controlslist>: nopaging, norotation, noscale, nofullscreen, norenderer, nolayers, nosignatures, nocopy, nodownload and noopen leave their buttons and menu items out, and their keys and gestures keep working; notoolbar leaves the whole bar out, and nogestures turns the gestures off. See PDFElement.controlsList. Multi-homed.

event:prefix

type renames the page's events to pdf-page-load, pdf-page-render and so on; - turns an inherited prefix off. See PDFElement.event. Multi-homed.

loading

When the page draws for the first time:

eager

As soon as the file has loaded. This is the default.

lazy

When it comes within one viewport of the visible area (in an <iframe>, of the frame's own), or is found, focused or printed. It is sized at once. See PDFPageElement.loading.

no

The page number: 1 (the default) is the first page, -1 the last, and +Infinity always the last. See PDFPageElement.no.

of

The id of the <pdf-file> whose page to show. Without it, the page shows the file of its closest <pdf-file> ancestor.

offset:x

A number of CSS pixels to move the content right inside the page box (negative: left). The default is 0.

offset:y

A number of CSS pixels to move the content down (negative: up). The default is 0.

placeholder:aspect-ratio

The box the page keeps while its PDF is on the way: a paper name such as A4 or letter, a ratio such as 16/9, or - for no box. See PDFElement.placeholder. Multi-homed.

rotation

The rotation in degrees clockwise, a multiple of 90. It replaces the rotation stored in the file.

scale

The zoom factor. At 1 (the default), the page box and its image are the page's own size in CSS pixels; sized by CSS, scale sets the image resolution.

signatures

A Boolean attribute: the page shows the cards of its digital signatures. signatures=- turns inherited cards off. Multi-homed.

svg

A Boolean attribute: the page is drawn as vector SVG, built in a background worker, instead of on a canvas.

toolbar

The edge the bar of a page with controls sits on: bottom (the default), top, left or right, or a logical edge, block-start, block-end, inline-start or inline-end, which follows the page's direction. On the left or the right, the bar stands upright. To turn it off, use controlslist=notoolbar. See PDFElement.toolbar. Multi-homed.

watermark

On a licensed domain, previews the evaluation watermark: empty for this domain's name, or a domain name. See PDFPageElement.watermark.

Events

Listen to these events with addEventListener(). They bubble and are composed.

error

The page cannot find its file, or its engine failed to draw it.

load

The page knows its size, before it draws.

render

The page has drawn.

signature

A signature on the page was clicked. Cancelable.

Usage notes

Linking a page to its file

A page shows the file its of attribute names, or the file of its closest <pdf-file> ancestor. One file serves any number of pages, and their form fields stay in sync.

<pdf-file id=f src=//pdf.ist/web.pdf></pdf-file>
<pdf-page of=f></pdf-page>
<pdf-page of=f no=2></pdf-page>

Sizing

A page is sized like an image: its box is the page size times scale, and CSS can size it instead (then scale only sets the resolution). Before its PDF arrives, a page keeps a box: one remembered from an earlier visit, --width and --height, placeholder:aspect-ratio, or the paper of the visitor's region. Off-screen pages skip layout and paint (content-visibility: auto). See Lazy pages and placeholders.

Keyboard

On a page with controls, keys work while the page has focus: click it, or press Tab. ⌘ works as Ctrl. Ctrl S and Ctrl O (with Alt for form data) work from anywhere inside every page, also without controls and in form fields, and never reach the browser's own save and open.

Mouse and touch

A page with controls shows a bar like a video's. toolbar moves it to another edge, and controlslist leaves controls out: notoolbar the whole bar, and nogestures the gestures.

Styling with CSS

The layers, links, fields, signature cards and controls of a page are parts you can style with ::part(); the page's state is exposed as custom states, and colors and sizes as custom properties. Pages are drawn transparent: the paper is the host's background-color.

pdf-page {
  --pdf-page-background-color: white;
}
pdf-page::part(link) {
  background: oklch(62% 0.24 27 / 0.1);
}
pdf-page:state(pending) {
  opacity: 0.5;
}

Accessibility

A page is not just an image: its text is real text, so it can be selected, found with the browser's find, and read by screen readers, and its links and form fields are real elements in the page's shadow root. A page drawn with -=text has no text for assistive technology.

A page with controls can be focused and shows a focus outline (--pdf-page-focus-outline). The bar is a toolbar of labelled buttons, and its menu a menu of items that list their keyboard shortcuts.

Examples

Embedding the first page

The smallest use: one file, one page.

HTML

<pdf-file id=f src=//pdf.ist/web.pdf></pdf-file>
<pdf-page of=f scale=0.5></pdf-page>

Result

Embedding the last and the first page

With controls on both, each page turns on its own.

HTML

<pdf-file id=f src=//pdf.ist/web.pdf></pdf-file>
<pdf-page of=f no=-1 controls scale=0.3></pdf-page>
<pdf-page of=f no=+1 controls scale=0.3></pdf-page>

Result

Responsive transparent pages

Pages are drawn transparent; sized by CSS, they follow their container.

HTML

<pdf-file id=f src=//pdf.ist/web.pdf></pdf-file>
<div class=checkerboard>
  <pdf-page of=f scale=2></pdf-page>
</div>

CSS

.checkerboard {
  background: repeating-conic-gradient(oklch(90% 0 0) 0 25%, white 0 50%) 0 0 / 20px 20px;
  resize: horizontal;
  overflow: hidden;
  width: 50%;
}
pdf-page {
  width: 100%;
  background-color: transparent;
}

Result

Lazy pages

Only the pages near the visible area are drawn.

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>

Result

Signature cards

A signed file and a trusted demo root: the cards show who signed, when, and whether the file changed.

HTML

<pdf-file id=s src=//new.webpdf.pro/signed.pdf trust:src=//new.webpdf.pro/demo-root.pem></pdf-file>
<pdf-page of=s signatures scale=0.6></pdf-page>

Result

Technical summary

Specifications

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

Browser compatibility

See also

• <pdf-file>
• PDFPageElement
• Using WebPDF
• Viewer controls
• <video>