turn-ts

The page-flip engine, with no framework attached. A port of turn.js (3rd release) to typed, dependency-free DOM code that is safe to import on the server.

[!IMPORTANT] This package is not open source. Non-commercial use only.

It is a derivative work of turn.js (3rd release), whose licence permits redistribution, use and modification "solely for personal benefit and not for any commercial purpose or for monetary gain." That restriction is inherited and cannot be removed by this project. If you intend to use turn-ts in anything commercial, do not install it — read LICENSE.md first and take your own legal advice.

This package is the base the framework packages build on:

| Package | Wraps this with | | --- | --- | | turn-ts-react | a ref callback with a cleanup return (works in Next.js App Router — the wrapper is the only client code) | | turn-ts-next | nothing yet; turn-ts-react ships "use client" and works in the App Router directly | | turn-ts-svelte | onMount + $effect | | turn-ts-vue | onMounted + watch |

Install

npm i turn-ts

Use it directly

import { createTurnBook } from 'turn-ts';
import 'turn-ts/turn-ts.css';

const book = createTurnBook(
  document.querySelector('.turn-book')!,
  { width: 840, height: 560, page: 1, display: 'double' },
  { turned: (event) => console.log('now on', event.page) }
);

book.next();
book.destroy();

createTurnBook is synchronous — the DOM work is finished before it returns, so there is never a window in which a half-built book exists. It touches the DOM immediately, so only call it after mount, never during render or on the server. Nothing in this package reads window or document at module scope, so importing it in a server bundle is safe.

One book per element. A second createTurnBook on a live element throws; call destroy() first. This is what makes React 19 StrictMode's mount/unmount/mount safe.

Pages

The container's element children are the pages, in order. Two shapes are supported:

<!-- Bare pages. The engine wraps them, and removes its wrappers again on destroy. -->
<div class="turn-book">
  <div>page one</div>
  <div>page two</div>
</div>

<!-- Host-owned wrappers. The engine borrows them and hands them back untouched. -->
<div class="turn-book">
  <div class="turn-page-wrapper"><div class="turn-page">page one</div></div>
  <div class="turn-page-wrapper"><div class="turn-page">page two</div></div>
</div>

The second shape is what a framework wrapper should render. The engine styles those wrappers while the book is alive but never removes them, never reorders them, and puts their inline styles back on destroy — so the framework's own insertion anchors keep pointing at nodes it still owns. A .turn-page-wrapper with no .turn-page inside is treated as an unfilled slot, not a page.

Either way the engine never deletes a page element: pages outside the current view are hidden, not evicted. Add or remove children at runtime and the engine rebuilds its page list from the DOM, keeping DOM order — a page inserted in the middle becomes the middle page.

The wrapper contract

Everything a framework wrapper needs is these three moves:

1. Mount. Render a container with class="turn-book" and style="--turn-book-width: {w}px; --turn-book-height: {h}px", render the pages as its children, then createTurnBook(el, options, callbacks) after the children exist.
2. Sync. When props change, call api.configure({ ... }). For page/pages/disabled, compare first (if (api.page() !== page) api.page(page)) so a turned callback echoing back into state does not loop.
3. Unmount. api.destroy(). It restores every page element to how it found it — only the classes and the individual inline style properties the engine actually wrote are undone, so a class or style the consumer set survives untouched.

API

createTurnBook(element, options, callbacks?) => TurnBookApi

Options — page, pages, width, height, display ('single' | 'double'), gradients, duration, cornerSize, corners ('backward' | 'forward' | 'all' or ('tl'|'tr'|'bl'|'br')[]).

Callbacks — ready, start, turning, turn, turned, first, last. All but start get a TurnBookPageEvent of { type, api, page, view }. start gets a TurnBookStartEvent, which additionally carries the corner that was grabbed and a preventDefault() that refuses the fold — those two are only meaningful on start, so they only exist there.

Api — next, previous, page, pages, view, range, size, display, configure, resize, update, disable, stop, animating, hasPage, addPage, removePage, destroy.

Two rules worth knowing:

• pages() is the number of page elements the engine has adopted. It cannot be inflated: pages(n) with n above the current count throws, below it removes the trailing pages, and the pages option is clamped the same way. A book with nothing in it reports 0 pages and a range() of [0, 0] rather than throwing.
• removePage(n) throws for a page in a host-owned wrapper. The engine never deletes DOM it did not create; remove the wrapper from your own markup and the engine will re-sync.

Full signatures are in dist/index.d.ts.

Sizing

The engine re-measures on pointerdown and, where the browser has it, through a ResizeObserver on the container — so a fold stays aligned when something above the book changes height. Call api.resize() by hand if you defeat both (an animated transform on an ancestor, say).

Styles

turn-ts/turn-ts.css carries the handful of rules the fold needs (.turn-book, .turn-page, .turn-page-content). Import it once, or copy the rules into your own sheet. What matters is what it does not set on .turn-book: no overflow, no contain, no perspective — each of those breaks the fold. The engine sets touch-action: none on the container itself, so a drag still folds rather than scrolls even if you skip the stylesheet.

Develop

npm run lint    # typecheck + tests + build + publint

Tests run on node --test with happy-dom. happy-dom has no layout engine, so the suite covers the engine's state — page numbering, view/range, wrapper ownership, DOM ordering, destroy restoration — and not fold geometry, which needs a real browser.

License

Non-commercial. See LICENSE.md — turn.js 3rd release terms, inherited.