FlipCatalog
// Tutorial · Beginner · embedding

How to embed a flipbook in your website (vanilla HTML)

A copy-pasteable walk-through using StPageFlip.

Why this tutorial

Embedding a flipbook in a real production page is mostly a question of three things: how the library is delivered (CDN, npm, framework component), how the page assets are loaded (eager vs lazy), and how the surrounding markup keeps the flipbook content indexable. Get those three right and the page-flip itself is essentially free.

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