pageforge-flip

A lightweight, zero-dependency flipping book component for modern browsers. pageforge-flip mirrors the ergonomics of the popular page-flip package while embracing ES modules, smooth requestAnimationFrame animations, and comprehensive input support (mouse, touch, and keyboard).

Features

• Smooth GPU-accelerated page turning with configurable duration and page shadows
• True two-page spreads with hinge-based flips triggered from either side
• Works with HTML templates or image URLs
• Supports mobile swipes, mouse dragging, and arrow-key navigation
• Orientation-aware spreads (portrait or landscape two-up mode)
• Small API surface with lifecycle events
• Ships with ESM, CJS, and TypeScript definitions

Installation

npm install pageforge-flip
# or
pnpm add pageforge-flip
# or
yarn add pageforge-flip

Quick Start

<div id="book">
  <section class="page">Cover</section>
  <section class="page">Page 1</section>
  <section class="page">Page 2</section>
</div>

import PageFlip from 'pageforge-flip';

const book = document.querySelector('#book');
const flip = new PageFlip(book, {
  animationDuration: 700,
  shadowOpacity: 0.2
});

flip.loadFromHtml(book.querySelectorAll('.page'));
flip.on('change', ({ currentPage }) => console.log('Now on page', currentPage));

Click/tap the right half to advance or the left half to go backward. Each page flips around the center hinge, giving a clear open-book effect.

Loading from Images

flip.loadFromImages([
  '/images/page-1.jpg',
  '/images/page-2.jpg',
  '/images/page-3.jpg'
]);

API

Constructor

new PageFlip(parent: HTMLElement, options?: PageFlipOptions)

| Option | Type | Default | Description | | --- | --- | --- | --- | | width | number | 600 | Base width used when auto sizing fails | | height | number | 800 | Base height used when auto sizing fails | | animationDuration | number | 600 | Flip time in ms | | shadowOpacity | number | 0.15 | Max drop shadow intensity | | useShadow | boolean | true | Toggle page shadow rendering | | swipeThreshold | number | 30 | Minimum horizontal drag (px) to trigger a flip | | autoSize | boolean | true | Resize to fit parent container | | orientation | 'auto'\|'portrait'\|'landscape' | 'auto' | Force orientation or auto-detect |

Methods

• flipNext(): Promise<number> – Flip forward one spread
• flipPrev(): Promise<number> – Flip backward
• flipTo(page: number): Promise<number> – Jump to a given page index
• loadFromHtml(elements: HTMLElement[] | NodeList) – Hydrate from HTML nodes
• loadFromImages(images: string[]) – Hydrate from image URLs
• getCurrentPage(): number
• getTotalPages(): number
• destroy(): void

Events

| Event | Payload | | --- | --- | | init | { currentPage, totalPages, orientation } | | flipStart | { currentPage, targetPage, direction } | | flipEnd | { currentPage, previousPage, direction } | | change | { currentPage, totalPages, orientation } |

Use flip.on(event, callback) / flip.off(event, callback) to manage listeners.

Building & Testing

npm run build   # rollup builds dist/*.js
npm test        # runs the Jest suite (jsdom)

License

MIT