Skip to content

reader.navigation

Every method and stream of the navigation API: readingPosition$, page turns, goToCfi() and the other go-to methods, navigate() targets, panning and locks.

The reference for reader.navigation. The navigation guide explains how to use it: which navigation to pick, what to save, and what happens around a pan or a relayout.

Observable<ReadingPosition>
type ReadingPosition = {
cfi: string
percentageEstimateOfBook: number
status: "pending" | "success" | "error"
}

Where the reader is in the book: the value to save, and whose cfi to pass back as createReader's target, { type: "cfi", value }, to reopen the book there. Replays the current one on subscription, and emits nothing until the first navigation has a position. The guide's Reading position says when it changes, and Saving it why a value that is not a success is saved all the same.

Field Meaning
cfi The place in the text: the place the target names once its spine item's document shows it, or the first character of the page landed on, or the element that page starts with when no text does. While no place is known, such as while the spine item the navigation goes to loads, it stands in: it is that item's start, a cfi naming only the item, which reader.cfi.isRootCfi(cfi) tells
percentageEstimateOfBook How far into the book cfi is, from 0 to 1: where the page holding it starts, estimated from the progressionWeight of each spine item in the manifest and the pages of its own. A position on the last page is short of 1. While the value is not a success, it is the start of its spine item. When a spine item has no progressionWeight, or the weights add up to nothing, every item counts as an even share
status Whether the reader has found the place the navigation goes to: pending while it is still finding it, success once the page holding the place the target names is laid out, or once the page landed on is when the target names no place, and error once the spine item the navigation goes to has failed to load, at its start or at the place the target names if the item showed it first. Every navigation ends in success or error, which stays until the next navigation

All three come from the same navigation, so a value never pairs a position with the progress of another.

() => void
Method Turns one page, or one spread
.turnLeft(), .turnTop(), .turnLeftOrTop() to the left, or up when pages turn vertically
.turnRight(), .turnBottom(), .turnRightOrBottom() to the right, or down when pages turn vertically

The three names in each row are the same method. They follow the screen, not the reading direction: in a right-to-left book .turnLeft() goes forward. At the edge of the book the page stays, and .outOfSpineBoundary$ emits.

animation, where a method takes it, is how the viewport gets there:

type Animation = boolean | "turn" | "snap"
(cfi: string, options?: { animate: boolean }) => void

Goes to the page holding cfi. Animates unless animate is false. Does nothing when the cfi names nothing in the book: when it can't be read, or names a spine item the book does not have. A cfi whose path leads to nothing in its spine item goes to the start of the item.

(url: string | URL) => void

Goes to the spine item an absolute url points to, and to the element its fragment names when it has one. Never animates. Does nothing when the url is outside the book. Links between the book's documents go through it when clicked.

(params: { indexOrId: number | string; animation?: Animation }) => void

Goes to the start of a spine item, by index or by id. Does nothing when the item does not exist.

(params: {
pageIndex: number
spineItemId: number | string
animation?: Animation
}) => void

Goes to a page of a spine item. A page index after the last page of the item goes to its last page. In spreads, the pages of an item can include a blank page.

(params: { absolutePageIndex: number; animation?: Animation }) => void

Goes to a page counted from the start of the book. Does nothing when no such page is laid out. The index counts the pages of the current layout, including the blank pages of spreads, so it can name another page once the layout changes.

() => void
Method Goes to
.goToNextSpineItem() the item after the last one visible
.goToPreviousSpineItem() the item before the first one visible
.goToLeftSpineItem() the item to the left: previous, or next in a right-to-left book. Horizontal only
.goToRightSpineItem() the item to the right: next, or previous in a right-to-left book. Horizontal only
.goToTopSpineItem() the previous item. Vertical only
.goToBottomSpineItem() the next item. Vertical only
.goToLeftOrTopSpineItem() the item to the left, or above when pages turn vertically
.goToRightOrBottomSpineItem() the item to the right, or below when pages turn vertically

A method called in the direction it does not support warns and does nothing.

(to: {
target: NavigationTarget
animation?: Animation
type?: "api" | "scroll"
}) => void
type NavigationTarget =
| { type: "position"; value: SpinePosition | UnboundSpinePosition }
| { type: "spineItem"; value: number | string }
| { type: "cfi"; value: string }
| {
type: "selector"
value: {
spineItem: number | string
find: (document: Document) => NodePosition | undefined
}
}
type NodePosition = { node: Node; offset?: number }

The navigation every method above is built on. Prefer them: this is for gestures and positions the others cannot express.

A navigation asks for exactly one target. One whose target names nothing in the book is ignored, with a warning: a cfi that can't be read, or a cfi, spineItem or selector naming a spine item the book does not have. A position is clamped to the book, so it always names a place.

type is "api" unless you give it. "scroll" is for a navigation that follows a scroll of the user's: the view is already at its position, and the reader does not move it. The reader makes those itself in a book that scrolls, see .navigation$.

Enhancers can add target types: the reader createReader returns also takes { type: "url"; value: string | URL }, from its navigation enhancer. NavigationTargetOf<typeof reader> is every target a reader takes. Enhancers explains how to add one.

A selector target is a place in a spine item's document that only find knows how to look for, such as an element by id. Until the item's document is loaded, the navigation goes to the item's start, and it looks again each time the book is laid out. Once found, the place is the navigation's reading position, like a cfi.

find runs synchronously inside the navigation, and may be called several times, or not at all when the reader navigates elsewhere first. Keep it quick and free of side effects, and do not modify the document. A find that throws finds nothing: the navigation stays at the item's start.

NavigationTarget is exported by core, with NavigationTargetType, the union of its types, and NavigationTargetValues, the value each type carries. NavigationTarget<Type> narrows it to some of its types.

createReader's target option takes the same targets, url included: it is the reader's first navigation, where the book opens. A target naming nothing in the book opens it at its start, as without one.

reader.navigation.navigate({
target: { type: "position", value: new SpinePosition({ x: 0, y: 400 }) },
animation: false,
})
Observable<{
id: symbol
position: SpinePosition | UnboundSpinePosition
requestedPosition: SpinePosition | UnboundSpinePosition | undefined
requestedVisibleArea: { width: number; height: number } | undefined
triggeredBy: "user" | "restoration"
}>

Every navigation as it happens: a "user" one that you or a gesture asked for, the one to where the reader opens included, or a "restoration" of the current one onto a new layout or when a pan ends. The user's scroll of a book that scrolls gives a "user" one at each move, one as a layout starts during it, and one when the scrolling has stopped for half a second: where the scroll has taken the user by then. A restoration is emitted even when it lands where the navigation already was.

A navigation asked for while a lock() is held is emitted as a "user" one when it is made. The last one asked for is emitted again, as a "restoration", when the lock is released and it lands. The same holds during a scroll of the user's, which that navigation ends, see .navigationRequest$.

Observable<{
target: NavigationTarget
animation?: Animation
type?: "api" | "scroll"
}>

Each request for a navigation whose target names a place in the book, as core was given it: a target that an enhancer adds, such as a url, is emitted as the core target it was translated to. A request whose target names nothing in the book is ignored, and is not emitted. It completes when the reader is destroyed.

It emits once the reader has handled the request. The reader has made the navigation by then, so .navigation$ emits it first. While the reader's container is hidden, the order is the reverse: the request is emitted at once, and the reader makes the navigation once the container is shown.

A request that a listener of this stream, or of .navigation$, makes in answer to another one is emitted before the one it answers.

Use it to end something of your own when something else navigates. The reader does so for a scroll of the user's: a request that the scroll did not make ends the scroll at once, its lock is released, and the scroll makes no more navigations of its own. The requests that the scroll makes have the type "scroll": one at each move, one as a layout starts during it, and one when the scrolling has stopped for half a second.

Observable<{
navigation: Navigation
holdsOnCurrentLayout: boolean
}>

The latest navigation, the value .navigation$ emitted for it, and whether it holds on the current layout: whether it was made, or restored, over the pages the reader shows now, with no layout requested since that can change what it shows. Only while it holds do its position and the pages agree. Replays the current one on subscription.

It is given with every navigation, and again, with the same navigation and holdsOnCurrentLayout: false, when a layout that can change what it shows is requested: once, as it then stays void until the next navigation. It does not hold:

  • before the book is first laid out;
  • from the moment a layout that can change what it shows is requested: one by reader.layout(), or by a spine item loading or unloading when that item is shown or comes before the ones shown;
  • through the "restoration" that puts the viewport back as soon as the spine items are laid out, when the layout moved what the navigation shows: the new pages are not in yet. In a book that scrolls, this one does not wait for a lock() to be released;
  • once the new pages are in, until the navigation is restored onto them, by a "restoration" that holds.

A spine item's place depends only on the items before it, so a layout started by an item after the ones shown leaves the navigation holding, and is not reported. A navigation made while a layout is pending holds only if that layout cannot change what it shows either. Read it rather than .navigation$ when what you do depends on the layout, such as which spine items or pages a navigation shows. It completes when the reader is destroyed.

Observable<SpinePosition | UnboundSpinePosition>

The position of the latest navigation, only when it changes.

Observable<"busy" | "free">

"busy" while the viewport is moving, while a lock() is held, and while the reader restores the navigation after one is released; "free" otherwise.

Observable<{
canGoLeftSpineItem: boolean
canGoRightSpineItem: boolean
canGoTopSpineItem: boolean
canGoBottomSpineItem: boolean
}>

Whether there is a spine item in each direction to go to. Emits as soon as you subscribe to it.

Emits when a navigation request targets a position outside the spine's bounding box: "start" before the first screen, "end" past the last, in reading order. Until a layout has laid out a spine item, the spine has no bounding box, and it emits nothing. Pure geometric primitive, with no content-lifecycle semantics. For "end of book reached" with lazy-load awareness, compose with readiness signals (see observeBookBoundaryReached).

reader.navigation.outOfSpineBoundary$
{
start: (delta: { x: number; y: number }) => void
panMoveTo: (delta: { x: number; y: number } | undefined) => void
stop: (delta: { x: number; y: number }) => void
}

Drives a pan from the deltas of a gesture: start() when it begins, then panMoveTo() for each move, and stop() when the user lets go. It holds a lock() from start() to stop(). Controlled page turn mode only: in scrollable mode it warns and does nothing.

() => () => void

Holds the navigation, and returns the function that releases it. Locks add up: the navigation is held until every one is released, and calling a release twice releases it once. A navigation made while it is held lands once it is released: it snaps to a page then, and only then moves the reading position.

Observable<boolean>

true while a lock() is held.

<T>(params: { duration: number; trigger: Observable<T> }) => Observable<T>

Create and hold a lock on the navigation that will release periodically only when the duration is reached. This is useful when letting users navigate with a scrubber for example. This will make sure the reader will not re-layout too often even if the user play with the scrubber too fast.

This does not prevent navigation, only the heavy recalculation that can occurs after (layout, pagination calculation, etc). The reading position moves at each release, to where the latest navigation lands.