FlipCatalog
// Tutorial · Beginner · images

Building a flipbook from a folder of JPG/PNG images

A copy-pasteable walk-through using StPageFlip.

Why this tutorial

Building a flipbook from a folder of JPGs or PNGs is the simplest thing you can do, and it is also surprisingly performant if you get the loading strategy right. The trick is to ship low-resolution placeholders first, then upgrade to full-resolution as each page comes into view.

The example below is the smallest working version we could write while still being honest about the production concerns, SEO, accessibility, performance, that you will need to handle before shipping. It assumes a recent version of StPageFlip and standard modern-browser support; if your audience requires legacy browsers, double-check the StPageFlip deep-dive for the specific support matrix. the related performance considerations are worth skimming before committing to a particular rendering strategy.

Step 1: install the library

Add the package or script tag for StPageFlip. If you are starting from scratch in a Vite, Webpack, or Next.js project, npm is the right choice; for a one-page static demo, the CDN script tag is faster.

npm install page-flip
# or via CDN:
<script src="https://unpkg.com/page-flip/dist/js/page-flip.browser.js"></script>

Step 2: render the markup

Every flipbook library expects a container element and a sequence of page elements (or page assets) inside it. The naming differs but the shape is consistent: an outer wrapper that owns the dimensions, and inner elements (or images) that the library treats as individual pages. Aim for sensible page sizes; somewhere between 4:3 and 3:4 aspect ratio works well across desktop and mobile.

Step 3: initialise the viewer

Below is the minimal initialisation. Run it after the page-content elements (or page assets) are in the DOM. Use a DOMContentLoaded listener for vanilla, or inside useEffect / onMounted / onMount for React, Vue, and Svelte respectively.

import { PageFlip } from 'page-flip';

const pageFlip = new PageFlip(
  document.getElementById('book'),
  {
    width: 550,
    height: 733,
    size: 'stretch',
    minWidth: 315,
    maxWidth: 1000,
    minHeight: 420,
    maxHeight: 1350,
    drawShadow: true,
    flippingTime: 1000,
    usePortrait: true,
    showCover: true,
    mobileScrollSupport: true,
  }
);

pageFlip.loadFromHTML(document.querySelectorAll('.page'));
pageFlip.on('flip', e => console.log('Page', e.data));

Step 4: ship a working version, then harden it

Once you can see the page-flip in your browser, resist the urge to immediately customise. The hardening checklist is:

  • Lazy-load the page images. only fetch the next/previous spread eagerly; defer the rest until the user is within a page or two.
  • Wire the page-change callback to analytics. either Google Tag Manager, Plausible, or a custom server endpoint. This is how you get reading-depth metrics for free.
  • Add a deep-link to the URL hash. #/page/12 or similar. Readers will share specific pages and you want those shares to land on the right spread.
  • Render the underlying text as real HTML. if your flipbook is the only place readers can find the content, the content has to be indexable. Most libraries are happy to take real text elements as page content.
  • Test on a low-end Android device. a flipbook that feels great on a Macbook can stutter painfully on a budget Android phone. Run the real device test before launch.

Step 5: troubleshoot the common issues

The three problems we see most often: page transitions that look fine on desktop but stutter on mobile (almost always an image-size problem); page content that disappears after the first flip (almost always a CSS backface-visibility issue); and zoom that fights the page-turn gesture (almost always missing pointer-event capture). Each of those is fixable in a few lines once you know what to look for. a deeper troubleshooting guide covers the full list with diagnostic snippets.

Where to go from here