Advanced Embed Options

Use the programmatic JavaScript API for dynamic embedding, integrate with React/Vue/Angular SPAs, handle events, customize styling, and configure auto-flip behavior.

On this page

Advanced Embed Options

Beyond the basic script tag and div approaches, the ZenFlip embed widget provides a programmatic JavaScript API for dynamic embedding scenarios. This guide covers the API, single-page application (SPA) integration, event handling, and advanced configuration.

Programmatic API

The embed script exposes a global ZenFlip object with methods for creating and managing embeds.

ZenFlip.embed(target, options)

Create an embed instance programmatically.

Parameters:

Parameter

Type

Required

Description

target

string or HTMLElement

Yes

CSS selector or DOM element

options.pub

string

Yes

Publication slug

options.width

string or number

No

Width (default: "100%")

options.height

string or number

No

Height in pixels (default: 600)

options.autoFlip

boolean

No

Enable auto-page-flip (default: false)

options.startPage

number

No

Starting page number (default: 1)

options.baseUrl

string

No

Override viewer base URL

Returns: An embed instance object with iframe, wrapper, and destroy() properties, or null if the target was not found.

ZenFlip.scan()

Re-scan the page for new .zenflip-embed containers that were added to the DOM after the initial page load. This is essential for single-page applications where content is rendered dynamically.

Destroying an Embed

Call destroy() on the instance to remove the embed from the DOM and clean up resources:

SPA Integration

React

Create a reusable React component that manages the embed lifecycle:

Vue 3

Angular

Event Handling

The embed widget communicates with the parent page through the postMessage API. Listen for messages from the ZenFlip iframe to respond to viewer events:

Available Events

Event Type

Description

Data

zenflip:ready

Flipbook has finished loading

{ pageCount, slug }

zenflip:page_change

Viewer navigated to a new page

{ pageNumber, slug }

zenflip:lead_captured

A lead form was submitted

{ email, slug }

Custom Styling

The embed widget wraps the iframe in a container with the class zenflip-wrapper. You can target this class to customize the outer appearance:

The iframe itself handles all viewer styling internally. You cannot inject CSS into the iframe due to cross-origin restrictions, but the viewer respects the branding settings configured on the publication (logo, colors, fonts) via the dashboard or the Publications API.

Auto-Flip Configuration

When autoFlip is enabled (either via data-auto-flip="true" or autoFlip: true in the programmatic API), the viewer automatically advances pages at a timed interval. This is useful for digital signage, lobby displays, or unattended presentations.

The auto-flip interval and behavior (loop vs. stop at last page) can be configured through the publication viewer settings in the dashboard or via the PATCH /publications/:id/settings endpoint.

Custom Base URL

If you host the ZenFlip viewer on a custom domain or a self-hosted deployment, override the base URL:

Or programmatically:

The viewer URL is constructed as {baseUrl}/view/{slug}, so ensure your custom domain serves the ZenFlip viewer at that path.

Version Information

Check the current embed widget version:

Double-Initialization Prevention

The embed script includes built-in protection against double initialization. If the script is included multiple times on the same page (common in CMS environments), only the first instance runs. Subsequent script loads are silently ignored.

← Previous
Embed Widget Quick Start