Migrating from StPageFlip

The names changed and there’s no compatibility layer for the old ones, so this is a small migration rather than a version bump. The tables below list every option, method, event and React prop the old packages had and where each one went. They’re typed against both APIs, so if a row is here, it’s current.

Swap the dependency first. page-flip becomes the core package and react-pageflip becomes the React one (which needs the core package beside it, and React 19):

npm i @openpageflip/core

pnpm add @openpageflip/core

yarn add @openpageflip/core

npm i @openpageflip/core @openpageflip/react

pnpm add @openpageflip/core @openpageflip/react

yarn add @openpageflip/core @openpageflip/react

Then the shape of things, which the tables don’t quite say on their own:

new PageFlip(el, opts) followed by loadFromHTML(pages) is one call now, createBook(el, opts). The container’s children are the pages, and the stylesheet is a separate import. The quick start is the full version.
The animated turns return a promise that resolves when the page lands, and the getters became plain properties. Everything the old class exposed for its own internals is gone.
Event names are the same. The handler gets a typed event with the fields named (e.page, e.orientation, e.state) instead of e.data, and on hands back the unsubscribe function.
In React, the ref is the book itself, so ref.current.pageFlip().flipNext() is just ref.current.flipNext(). Pages don’t need refs any more.

Options

page-flip	OpenPageFlip	Notes
`width`	`width`
`height`	`height`
`size`	`size`
`minWidth`	`minWidth`
`maxWidth`	`maxWidth`
`minHeight`	removed	Height follows width by the width:height ratio, so the width bounds are enough.
`maxHeight`	removed	Same as minHeight.
`startPage`	`startPage`
`flippingTime`	`flipDuration`
`drawShadow`	`shadows`
`maxShadowOpacity`	`shadowOpacity`	The default is 0.35, not 1, and the turning page has a hairline edge (the --opf-page-edge CSS variable). shadowOpacity: 1 with --opf-page-edge: transparent is the original's look.
`showCover`	`cover`
`usePortrait`	`layout`	usePortrait: false is layout: "spread". The default "auto" picks by container width, and "single" is new.
`autoSize`	`autoSize`
`startZIndex`	removed	Pages are stacked inside the container, so the book no longer needs a z-index base.
`mobileScrollSupport`	removed	The book sets touch-action on itself, so the page scrolls and the book flips without a flag.
`clickEventForward`	`ignoreDragOn`	Clicks on links, buttons and form fields always reach them. ignoreDragOn is the selector that decides which elements never start a flip.
`useMouseEvents`	`drag`	Split three ways: drag, swipe and click each have their own option.
`swipeDistance`	`swipeDistance`
`showPageCorners`	`hover`	Hovering an edge furls the whole edge now, rather than lifting a corner that follows the pointer.
`disableFlipByClick`	`click`	The default is now click: "edges": a strip along each page's outer edge, wider than the old corner boxes, where the edge also furls and a drag starts. disableFlipByClick: false (the old default) is click: "anywhere"; "off" turns clicks off entirely.

Methods

PageFlip	OpenPageFlip	Notes
`on()`	`book.on()`	Returns the unsubscribe function, and takes an AbortSignal in its options.
`off()`	`book.off()`	Takes the listener as well as the event name; the old off() dropped every listener of that event.
`destroy()`	`book.destroy()`
`update()`	`book.update()`	Resizes are watched for you; call this after other layout changes.
`loadFromHTML()`	removed	The container's children are the pages when createBook runs, or pass the pages option.
`updateFromHtml()`	`book.setPages()`
`loadFromImages()`	removed	There is no image mode. Put an img element on each page and it renders like any other content.
`updateFromImages()`	removed	Same as loadFromImages; use setPages with img pages.
`clear()`	removed	destroy() restores the DOM; a new book starts from the pages you give it.
`turnToPrevPage()`	`book.turnPrev()`
`turnToNextPage()`	`book.turnNext()`
`turnToPage()`	`book.turnTo()`
`flipNext()`	`book.flipNext()`	Resolves when the turn lands, with false when there was nothing to turn to.
`flipPrev()`	`book.flipPrev()`	Same promise as flipNext.
`flip()`	`book.flipTo()`	Same promise as flipNext. Further than the next spread it turns as a clump of pages.
`getPageCount()`	`book.pageCount`
`getCurrentPageIndex()`	`book.page`
`getOrientation()`	`book.orientation`
`getState()`	`book.state`
`getBoundsRect()`	`book.rect`
`getSettings()`	removed	Keep your own options object; the book does not hand it back.
`getPage()`	removed	Internal in the old library. The page elements are the ones you passed in.
`getRender()`	removed	Internal in the old library.
`getFlipController()`	removed	Internal in the old library.
`getUI()`	removed	Internal in the old library.
`getPageCollection()`	removed	Internal in the old library.
`updateState()`	removed	Internal in the old library; state is read-only from outside.
`updatePageIndex()`	removed	Internal in the old library; use turnTo or flipTo.
`updateOrientation()`	removed	Internal in the old library; the layout option decides orientation.
`startUserTouch()`	removed	Internal in the old library; pointer input is handled by the book.
`userMove()`	removed	Same as startUserTouch.
`userStop()`	removed	Same as startUserTouch.

Events

page-flip	OpenPageFlip	Notes
`init`	`init`	e.data.page and e.data.mode are now e.page and e.orientation.
`update`	`update`	Same shape as init.
`flip`	`flip`	e.data is now e.page.
`changeState`	`changeState`	e.data is now e.state.
`changeOrientation`	`changeOrientation`	e.data is now e.orientation.

React props

HTMLFlipBook	OpenPageFlip	Notes
`onInit`	`onInit`	Handlers get the core event, see the events table.
`onUpdate`	`onUpdate`
`onFlip`	`onFlip`
`onChangeState`	`onChangeState`
`onChangeOrientation`	`onChangeOrientation`
`className`	`className`
`style`	`style`
`children`	`children`	Children are the pages, as before, but they no longer need a ref or forwardRef. Wrap one in Page to make it hard.
`ref`	`ref`	The ref is the Book itself, so ref.current.flipNext() replaces ref.current.pageFlip().flipNext().
`renderOnlyPageLengthChange`	removed	Pages added or removed by React are picked up after every render, and a changed option rebuilds the book on its own.