Skip to content

reader.viewport

The reader.viewport reference: its size and page size at each layout, whether it shows a spread, its scale while zoomed, and whether it is moving.

The reference for reader.viewport, the element that frames what the reader shows. The viewport guide explains how to use it: what it is for, how to resize it, spread mode, and the absolute and relative viewports.

The viewport is measured at the start of each layout of the reader:

  • when the reader is mounted;
  • when you call reader.layout();
  • when the container the reader is mounted into changes size, unless layoutAutoResize is false, see My book does not resize with my screen;
  • when a setting that moves the pages changes, such as spreadMode, the page turn mode or direction, or the page margins.

Its size, its page size and whether it shows a spread change only then. A spine item that finishes loading lays the items out again, but does not measure the viewport.

A layout runs only while the viewport has a size, see .isSized$. While the container is hidden, under display: none for example, it measures 0 by 0: the book keeps its last layout, and a layout asked for meanwhile runs once the container is shown again, see My reader is hidden in a tab or an Activity.

{
element: HTMLElement
isSpread: boolean
pageSize: { width: number; height: number }
width: number
height: number
}

The state of the latest layout, read synchronously.

Field Meaning
element The viewport's element: a div with the data-prose-reader-viewport attribute, inside the container the reader is mounted into. It holds the pages, and a zoom transforms it
width, height The size of the element in CSS pixels at the last layout, from its clientWidth and clientHeight, which leave out a scrollbar and ignore a transform. This is the absolute viewport
isSpread Whether two pages share the viewport: the spreadMode setting, resolved against the viewport's size and the book. See Spread mode
pageSize The size of one page: the viewport's size, or half its width in a spread

Before the reader is first laid out, the state is a placeholder: width, height and both sides of pageSize are 1, and isSpread is false.

Observable<typeof reader.viewport.value>

The state as soon as you subscribe, then the state of every layout, changed or not. See Reactive state.

type ViewportState = typeof reader.viewport.value
watch<K extends keyof ViewportState>(key: K): Observable<ViewportState[K]>
watch<K extends keyof ViewportState>(keys: K[]): Observable<Pick<ViewportState, K>>

See Reactive state.

Observable<void>

Emits each time the viewport is measured for a layout, right after the state of that layout. The book is not laid out yet: reader.layout$ emits once its pages are. Both complete when the reader is destroyed.

{ width: number; height: number }

The size of one page at the last layout, the same as .value.pageSize. Renderers size their pages from it, as the PDF and audio enhancers do.

{ width: number; height: number }

The size the book is laid out for: the width and height of the last layout. Navigation and pagination compute with it, see Absolute vs Relative viewport.

{ width: number; height: number }

The area the viewport shows once transformed, such as by a zoom: the absolute viewport divided by .scaleFactor. Zoomed out to half the size, it is twice as large as the absolute viewport. Which part of the book it shows: .getVisibleSlice().

number

The scale the viewport is rendered at: its rendered width over its layout width, both measured when you read it. 2 when zoomed in to twice the size, 0.5 when zoomed out to half, and 1 when the viewport is not transformed or has no rendered size.

These measure the viewport's element as it is now, not as it was at the last layout. Each reads its clientWidth and clientHeight, which can make the browser compute styles and layout. The element has a size when both are above 0. Hidden, as under display: none, or out of the document, it measures 0 by 0, and has none. So has an element with a width but no height, such as in a container that is not given one.

Observable<boolean>

Whether the element has a size: measured as soon as you subscribe, then each time a resize changes it, as when its container is hidden or shown. It completes when the reader is destroyed.

Each subscription observes the element with its own resize observer. A browser reports a resize at its next rendering update, so a hide just made reads false from .hasSize() before it does here.

The reader works only while the element has a size:

  • every layout of the spine waits for one. A layout running when the element loses its size stops, and starts again once it has one;
  • the reader starts no load or unload of the documents of spine items. A document loaded with no size has no layout either, and the browser does not request its fonts: an HTML document already loading waits for a size before it counts as loaded;
  • a navigation waits for one, since a target such as a cfi names a place in a document that has no layout. If several wait, only the last one runs.
reader.viewport.isSized$.subscribe((isSized) => {
// false while the container is hidden
})
() => boolean

Whether the element has a size now.

() => boolean

Whether the element has a size, and not the one of the last layout, so that laying out again would change anything. With layoutAutoResize: "container", the reader lays out for a resize of its container only when this is true: a container hidden, then shown again at the size it had, needs no layout.

(position: SpinePosition | UnboundSpinePosition) => DOMRect

The part of the book the viewport shows while the book is at position, in the same coordinates, its transform included: what the screen shows. The reader loads the spine items it shows, with the ones it preloads around them.

position is the spine position at the viewport's top-left corner, where a navigation puts it, such as the one reader.navigation.position$ gives. Untransformed, the slice is the absolute viewport at the position. Transformed, it is the relative viewport, from wherever the transform takes the viewport's corner, measured on the page:

  • a paginated zoom scales the viewport around its center, so zoomed out the slice reaches past the absolute viewport on every side, and the slice follows the viewport where reader.zoom.move() moves it;
  • a scrolled zoom scales the viewport from its top and scrolls to keep its center, which moves the navigation: the slice starts at the position's height.
reader.navigation.position$.subscribe((position) => {
// the part of the book on screen, zoom included
const { x, y, width, height } = reader.viewport.getVisibleSlice(position)
})

The spine items it shows are the ones whose places overlap it. While a layout is pending, those places can still move: reader.spine.isLayoutCurrent() says when they won't.

(size: { width: number; height: number }) => boolean

Whether a viewport of this size would show two pages side by side, for the current book and spreadMode setting. It is the rule every layout applies to the viewport's own size, so it tells what a rotation or a resize would show before it happens. .value.isSpread is what is shown now. The guide's Spread mode uses it to anticipate a rotation.

Two streams on the reader itself, rather than on reader.viewport, say whether the viewport is moving.

Observable<"free" | "busy">

The same state as reader.navigation.navigationState$: "busy" while the viewport moves, while a navigation lock is held, and while the reader restores the navigation after one is released, "free" otherwise. It replays the current state when you subscribe.

reader.viewportState$.subscribe((state) => {
// "busy" while a page turns, "free" once it has landed
})
Observable<"free">

Emits each time the viewport becomes free, and at once if it is free when you subscribe. The reader waits for it before it loads or unloads the document of a spine item. Do the same with work that should not run while a page turns:

import { first } from "rxjs"
reader.viewportFree$.pipe(first()).subscribe(() => {
// the viewport is not moving
})

A layout that only the loads of spine items ask for waits longer: until the viewport has stayed free for 50 ms, see Layout.