@maxvankuik/flipbook-viewer

A high-performance React component for rendering PDFs (or pre-rendered images) as interactive flipbooks with realistic page-turning animations.

Features:

• PDF rendering via pdfjs-dist (client-side, optional dependency)
• Pre-rendered image support for server-side rendered / hosted flipbooks
• Zoom and pan — scroll wheel, pinch-to-zoom, double-click/tap
• Touch gestures — swipe to flip, tap page edges
• Keyboard navigation — arrow keys, space, escape, f for fullscreen
• Thumbnail strip and full-page grid view
• Fullscreen support
• Auto-hiding toolbar with page input
• Configurable theme, branding, and callbacks
• Responsive — adapts to mobile and desktop
• Tree-shakeable — ESM and CJS builds

Installation

npm install @maxvankuik/flipbook-viewer
# or
pnpm add @maxvankuik/flipbook-viewer
# or
yarn add @maxvankuik/flipbook-viewer

PDF support (optional)

If you want to render PDFs client-side, install pdfjs-dist as well:

npm install pdfjs-dist

If you only use pre-rendered images, you don't need pdfjs-dist — it's an optional dependency.

Quick Start

From a PDF

import { FlipbookViewer } from '@maxvankuik/flipbook-viewer';

function App() {
  return <FlipbookViewer pdfUrl="/my-catalogue.pdf" />;
}

From pre-rendered images

import { FlipbookViewer } from '@maxvankuik/flipbook-viewer';

const pages = [
  { imageUrl: '/pages/1.webp', thumbnailUrl: '/pages/1-thumb.webp', width: 1600, height: 2133 },
  { imageUrl: '/pages/2.webp', thumbnailUrl: '/pages/2-thumb.webp', width: 1600, height: 2133 },
  { imageUrl: '/pages/3.webp', width: 1600, height: 2133 },
];

function App() {
  return <FlipbookViewer pages={pages} />;
}

With full customization

import { FlipbookViewer } from '@maxvankuik/flipbook-viewer';

function App() {
  return (
    <FlipbookViewer
      pdfUrl="/catalogue.pdf"
      startPage={0}
      renderScale={1.5}
      theme={{
        accentColor: '#e11d48',
        backgroundColor: '#0a0a0a',
      }}
      branding={{
        logo: '/logo.svg',
        watermark: <span style={{ opacity: 0.3 }}>Preview</span>,
      }}
      showToolbar={true}
      showThumbnails={true}
      showHints={true}
      autoHideToolbar={true}
      toolbarTimeout={3500}
      enableZoom={true}
      enableKeyboard={true}
      enableFullscreen={true}
      onBack={() => window.history.back()}
      onPageChange={(page) => console.log('Page:', page)}
      onReady={() => console.log('Viewer ready')}
      onError={(err) => console.error('Viewer error:', err)}
    />
  );
}

Props

Source (provide one)

| Prop | Type | Description | |------|------|-------------| | pdfUrl | string | URL to a PDF file for client-side rendering. Requires pdfjs-dist. | | pages | FlipbookPageData[] | Pre-rendered page images. Use this for server-rendered or hosted flipbooks. |

Configuration

| Prop | Type | Default | Description | |------|------|---------|-------------| | pdfWorkerUrl | string | CDN (auto) | URL to the PDF.js worker script. Auto-detected from pdfjs-dist version if omitted. | | renderScale | number | 1.0 mobile, 1.5 desktop | Render resolution scale for PDF pages. Higher = sharper but more memory. |

Theming

| Prop | Type | Default | Description | |------|------|---------|-------------| | theme | FlipbookTheme | — | Visual theme. See FlipbookTheme. | | branding | FlipbookBranding | — | Branding options. See FlipbookBranding. |

Behavior

| Prop | Type | Default | Description | |------|------|---------|-------------| | startPage | number | 0 | Initial page index (zero-based). | | showToolbar | boolean | true | Show the bottom toolbar with navigation controls. | | showThumbnails | boolean | true | Show the thumbnail strip above the toolbar. | | showHints | boolean | true | Show usage hints overlay on first load (auto-dismisses after 4s). | | autoHideToolbar | boolean | true | Auto-hide toolbar after inactivity. | | toolbarTimeout | number | 3500 | Auto-hide timeout in milliseconds. | | enableFullscreen | boolean | true | Enable the fullscreen toggle button. | | enableZoom | boolean | true | Enable zoom and pan interactions. | | enableKeyboard | boolean | true | Enable keyboard navigation. |

Callbacks

| Prop | Type | Description | |------|------|-------------| | onBack | () => void | Called when the back button is clicked. If omitted, the back button is hidden. | | onPageChange | (page: number) => void | Called when the current page changes. | | onReady | () => void | Called when the viewer has loaded enough pages to display. | | onError | (error: string) => void | Called when an error occurs (PDF load failure, etc.). |

Layout

| Prop | Type | Description | |------|------|-------------| | className | string | Additional CSS class name on the root element. | | style | CSSProperties | Additional inline styles on the root element. |

Types

FlipbookPageData

interface FlipbookPageData {
  /** Full resolution image URL */
  imageUrl: string;
  /** Optional thumbnail URL (used in thumbnail strip/grid) */
  thumbnailUrl?: string;
  /** Page width in pixels */
  width: number;
  /** Page height in pixels */
  height: number;
}

FlipbookTheme

interface FlipbookTheme {
  /** Accent color for active states, spinners, highlights. Default: '#3b82f6' */
  accentColor?: string;
  /** Background color of the viewer. Default: '#030712' */
  backgroundColor?: string;
}

FlipbookBranding

interface FlipbookBranding {
  /** Logo shown during loading. URL string or React node. */
  logo?: string | ReactNode;
  /** Watermark overlay shown on the viewer (e.g. for free-tier branding) */
  watermark?: ReactNode;
}

Keyboard Shortcuts

| Key | Action | |-----|--------| | ← Arrow Left | Previous page | | → Arrow Right | Next page | | Space | Next page | | Escape | Reset zoom, or exit fullscreen | | F | Toggle fullscreen |

Touch Gestures

| Gesture | Action | |---------|--------| | Tap left edge | Previous page | | Tap right edge | Next page | | Swipe left/right | Flip page | | Pinch | Zoom in/out | | Double-tap | Toggle 2x zoom | | Drag (when zoomed) | Pan |

Mouse Controls

| Action | Effect | |--------|--------| | Click page edges | Flip page | | Scroll wheel | Zoom in/out | | Double-click | Toggle 2x zoom | | Drag (when zoomed) | Pan |

Styling

The viewer uses Tailwind CSS utility classes internally. If your project uses Tailwind CSS v4, add a @source directive so Tailwind can scan the viewer's classes:

@import "tailwindcss";
@source "node_modules/@maxvankuik/flipbook-viewer/src";

If you're using the package from a monorepo workspace:

@source "../../../packages/viewer/src";

The viewer also ships a small CSS file with CSS custom property defaults. Import it if you're not using Tailwind:

import '@maxvankuik/flipbook-viewer/styles.css';

Exports

The package exports the main component plus individual building blocks if you need them:

// Main component (most common)
import { FlipbookViewer } from '@maxvankuik/flipbook-viewer';

// Individual components
import {
  FlipbookPage,
  FlipbookToolbar,
  FlipbookThumbnails,
  FlipbookThumbnailStrip,
  FlipbookLoading,
} from '@maxvankuik/flipbook-viewer';

// Hooks
import { usePdfRenderer, useImagePages } from '@maxvankuik/flipbook-viewer';

// Types
import type {
  FlipbookViewerProps,
  FlipbookPageData,
  FlipbookTheme,
  FlipbookBranding,
  PageSource,
} from '@maxvankuik/flipbook-viewer';

Peer Dependencies

• react >= 18.0.0
• react-dom >= 18.0.0

Optional Dependencies

• pdfjs-dist >= 3.11.0 — only needed if you use the pdfUrl prop for client-side PDF rendering

License

MIT