Paginator — foliate-paginator element reference

paginator.js registers the <foliate-paginator> custom element, the reflowable renderer for flowing-text e-books. It paginates content using CSS multi-column, supports both paginated and scrolled flows, handles vertical writing modes, and exposes header and footer regions for running heads. Under normal use the <foliate-view> element creates and manages a paginator automatically, but you can also instantiate it directly for standalone use.

Import

import './foliate-js/paginator.js'

const paginator = document.createElement('foliate-paginator')
document.body.append(paginator)

Core methods

open(book)

Opens a book object. Sets paginator.bookDir and paginator.sections from the book, and registers a CSS transform hook if book.transformTarget is present (it strips -epub- vendor prefixes and converts vw/vh units so they do not interfere with column layout).

book

object

required

A book object that satisfies the foliate-js book interface. At minimum, book.sections must be present and each section must expose a .load() method.

const book = await makeBook(file)
paginator.open(book)

goTo(target)

Navigates to a resolved destination.

target

object | Promise<object>

required

An object (or a Promise that resolves to an object) with the following shape:

index (number, required) — the section index to navigate to.
anchor (function | number, optional) — either a function (doc) => Range | Element that locates the target within the section document, or a fraction from 0 to 1.
select (boolean, optional) — if true, selects the text at the anchor after navigation.

// Navigate to section 3, anchored to a DOM range
await paginator.goTo({ index: 3, anchor: doc => doc.getElementById('ch3') })

// Navigate to the end of section 1
await paginator.goTo({ index: 1, anchor: () => 1 })

prev([distance]) / next([distance])

Turns the page backward or forward. In paginated mode, scrolls by one page. In scrolled mode, scrolls by distance pixels (defaulting to the full scroll container height or width).

distance

number

Scroll distance in pixels. Only used in scrolled flow mode.

Navigation is locked while a page turn is in progress, preventing double-turns.

getContents()

Returns an array describing the currently loaded section. The paginator renders one section at a time, so the array has at most one element. Returns Array<{ index: number, doc: Document, overlayer: Overlayer | undefined }>.

const [{ index, doc }] = paginator.getContents()

scrollToAnchor(anchor, select?)

Scrolls the view so that anchor is visible. Used by view.js for TTS highlighting.

anchor

Range | Element | number

required

A DOM Range, an Element, or a fraction (0–1).

select

boolean

If true, the scroll reason is recorded as 'selection' rather than 'navigation', which affects how the text selection is set after scrolling.

setStyles(styles)

Injects custom CSS into the current section document. Use this to apply user-defined font, size, or colour preferences.

styles

string | [string, string]

required

Either a single CSS string (appended after the section’s own styles) or a two-element array [beforeStyle, afterStyle] where beforeStyle is prepended before the section’s styles and afterStyle is appended after.

paginator.setStyles('body { font-size: 1.2rem; line-height: 1.8; }')

destroy()

Disconnects the resize observer, destroys the inner view, and unloads the current section. Call this when removing the element from the DOM.

Layout attributes

Layout is configured exclusively through HTML attributes — there is no JavaScript property API. Set attributes with setAttribute() and remove them with removeAttribute(). The paginator re-renders automatically when observed attributes change. static observedAttributes = ['flow', 'gap', 'margin', 'max-inline-size', 'max-block-size', 'max-column-count']

animated

boolean attribute

When present, page turns use a sliding animation. Remove the attribute to disable animation. This is a boolean attribute: its presence enables it, its absence disables it.

flow

string

default:"paginated"

Either "paginated" (CSS multi-column, page-at-a-time) or "scrolled" (continuous scroll). Switching between modes does not reload the section.

margin

string

Height of the header and footer regions in pixels (unit must be px). Example: "48px". Defaults to 48px.

gap

string

Column gap as a CSS percentage relative to the container width. Example: "7%". Defaults to 7%. The outer edge padding is adjusted to visually match the inner column gap.

max-inline-size

string

Maximum column width in pixels (unit must be px). Controls how wide each text column can be before a second column is added. Example: "720px". Defaults to 720px.

max-block-size

string

Maximum block-axis size in pixels (unit must be px). For horizontal writing, this is the maximum height of the reading area. Example: "1440px". Defaults to 1440px.

max-column-count

string

Maximum number of columns as an integer. Has no effect in scrolled mode or when the container is in portrait orientation. Example: "2". Defaults to 2.

paginator.setAttribute('flow', 'scrolled')
paginator.setAttribute('gap', '5%')
paginator.setAttribute('max-inline-size', '640px')
paginator.setAttribute('max-column-count', '1')
paginator.setAttribute('animated', '')        // enable animation
paginator.removeAttribute('animated')         // disable animation

Running heads and footers

In paginated mode the paginator creates header and footer elements, one per visible column, which you can use to display the current chapter title, page number, or any other marginal content. These elements are not available in scrolled mode.

paginator.addEventListener('relocate', e => {
    const { tocItem } = e.detail
    if (paginator.heads) {
        for (const head of paginator.heads) {
            head.textContent = tocItem?.label ?? ''
        }
    }
})

Property	Description
`paginator.heads`	An array of `Element`s, one per column. Each element is a child of the shadow DOM header region. `null` in scrolled mode.
`paginator.feet`	An array of `Element`s, one per column, for the footer region. `null` in scrolled mode.

Style the head and foot regions from outside the shadow DOM using the ::part() pseudo-element:

foliate-view::part(head) {
    padding-bottom: 4px;
    border-bottom: 1px solid graytext;
}

foliate-view::part(foot) {
    padding-top: 4px;
    border-top: 1px solid graytext;
}

CSS filter part

Both renderer elements expose a filter part that applies CSS filters to the book content only, leaving annotation overlays unaffected.

foliate-view::part(filter) {
    filter: invert(1) hue-rotate(180deg);
}

Events

All events are CustomEvents dispatched on the <foliate-paginator> element. The <foliate-view> element listens to these internally and re-dispatches them (or handles them) at the view level.

load

Fired after a section document finishes loading.

doc

Document

The loaded section’s Document object.

index

number

The section index.

relocate

Fired whenever the visible location changes.

reason

string

Why the relocation happened. One of 'page', 'snap', 'scroll', 'navigation', 'selection', or 'anchor'.

range

Range

A DOM Range covering the currently visible text.

index

number

The current section index.

fraction

number

Reading progress within the section (0–1). In paginated mode this is (page - 1) / (pages - 2); in scrolled mode it is scrollTop / scrollHeight.

size

number

The fraction of the section that a single page represents (paginated mode only). Useful for estimating section page count.

create-overlayer

Fired when the renderer creates a new overlay surface for a section. The handler must call event.detail.attach(overlayer) with an Overlayer instance.

doc

Document

The section document.

index

number

The section index.

attach

function

Call with an Overlayer instance to attach it to the page: e.detail.attach(new Overlayer()).

Book Parsers

Renderers & View

Utilities

Paginator — foliate-paginator element reference

Import

Core methods

open(book)

goTo(target)

prev([distance]) / next([distance])

getContents()

scrollToAnchor(anchor, select?)

setStyles(styles)

destroy()

Layout attributes

Running heads and footers

CSS filter part

Events

load

relocate

create-overlayer

Build docs developers (and LLMs) love

Book Parsers

Renderers & View

Utilities

Documentation Index

​Import

​Core methods

​open(book)

​goTo(target)

​prev([distance]) / next([distance])

​getContents()

​scrollToAnchor(anchor, select?)

​setStyles(styles)

​destroy()

​Layout attributes

​Running heads and footers

​CSS filter part

​Events

​load

​relocate

​create-overlayer

Build docs developers (and LLMs) love

Import

Core methods

open(book)

goTo(target)

prev([distance]) / next([distance])

getContents()

scrollToAnchor(anchor, select?)

setStyles(styles)

destroy()

Layout attributes

Running heads and footers

CSS filter part

Events

load

relocate

create-overlayer