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.
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 |
| string or HTMLElement | Yes | CSS selector or DOM element |
| string | Yes | Publication slug |
| string or number | No | Width (default: |
| string or number | No | Height in pixels (default: |
| boolean | No | Enable auto-page-flip (default: |
| number | No | Starting page number (default: |
| 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 |
| Flipbook has finished loading |
|
| Viewer navigated to a new page |
|
| A lead form was submitted |
|
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.