QUICK START
Add the Picture in Picture Controller element to the page where PiP workflows will run.
The controller does not need to form part of your visible interface.
Trigger Picture-in-Picture actions from a direct user interaction such as a button click.
Document Picture-in-Picture requires browser user activation and may fail if opened automatically from page load, a delayed workflow or another non-interactive context.
Demo app editor:
https://bubble.io/page?id=demopictureinpicture&tab=Design&name=index&type=page&elements=bTKCHRun mode:
https://demopictureinpicture.bubbleapps.io/version-test───────────────────────────
OPEN HTML IN PICTURE-IN-PICTURE
Use Open HTML in Picture-in-Picture when you want complete control over the content shown inside the floating window.
Provide:
✦ HTML Content
✦ optional CSS
✦ optional Window Title
✦ requested Width
✦ requested Height
Dynamic Bubble expressions can be included in the HTML.
The browser controls the final PiP window dimensions and may adjust the requested size.
This action is useful for timers, live counters, status displays, lightweight controls and other compact interfaces.
───────────────────────────
OPEN URL IN PICTURE-IN-PICTURE
Use Open URL in Picture-in-Picture to display a web page inside the PiP window.
Provide:
✦ URL
✦ requested Width
✦ requested Height
The destination must allow iframe embedding.
Some websites prevent themselves from being embedded through browser security headers. The plugin cannot override those restrictions.
Bubble pages under your control are ideal for this use case.
For Bubble pages, check Settings > General > Allow to render the app in a frame/iframe.
For pages inside the same Bubble app, “Allow when same origin” is usually the right setting.
───────────────────────────
CONTINUE VIDEO IN PICTURE-IN-PICTURE
Use Continue Video in Picture-in-Picture for:
✦ native HTML video
✦ Vimeo
First give the existing video element an Element ID in Bubble.
Pass that value into Target Element ID.
For Vimeo, the player may need to have been started once before the plugin can continue the existing session through native PiP.
An untouched Vimeo player can also use Vimeo's own built-in Picture-in-Picture control to enter PiP from the beginning.
YouTube should use the dedicated Continue YouTube action instead.
───────────────────────────
CONTINUE YOUTUBE IN PICTURE-IN-PICTURE
YouTube requires one additional helper page.
1. Create a separate Bubble page for YouTube PiP.
2. Place the YouTube PiP Player element on that page.
3. Stretch the element to fill the available page.
4. Keep the page responsive.
5. Keep page padding and unnecessary gaps at 0 where possible.
6. Ensure the page minimum width and height are smaller than the PiP window dimensions you intend to request.
7. Copy the run-mode URL of that page.
On the page containing the original Bubble YouTube video:
1. Give the Bubble Video element an Element ID.
2. Trigger Continue YouTube in Picture-in-Picture.
3. Pass the Video element ID into Target Element ID.
4. Pass the dedicated helper-page URL into PiP Page URL.
5. Choose the requested PiP Width and Height.
The default YouTube PiP size is 480 × 270.
The plugin will:
✦ identify the current YouTube video
✦ preserve the current timestamp
✦ preserve whether playback was active or paused
✦ continue active playback muted where browser autoplay rules require it
✦ optionally show a Turn sound on button
✦ pass the final playback position back to the original Bubble player when PiP closes
The YouTube PiP Player element does not require a Video ID field. The controller passes the relevant video information automatically.
───────────────────────────
YOUTUBE SOUND
Browsers commonly restrict autoplay with sound.
When an actively playing YouTube video is continued into PiP, the helper player may initially continue muted.
The YouTube PiP Player includes:
✦ Show Sound Button
✦ Sound Button Text
Use these fields to control the optional sound-enabling overlay.
───────────────────────────
CLOSING PICTURE-IN-PICTURE
Use Close Picture-in-Picture when your Bubble workflow needs to close the PiP window programmatically.
Users can also close the window through the browser's own PiP controls.
The controller's Picture-in-Picture closes event can be used to react when a managed PiP session ends.
───────────────────────────
SUPPORT STATES
The Picture in Picture Controller exposes:
Document PiP supported
Whether the browser supports arbitrary HTML/document Picture-in-Picture.
Video PiP supported
Whether the browser supports standard video Picture-in-Picture.
PiP is open
Whether a Picture-in-Picture window managed by this controller is currently open.
Last error
The most recent error reported by a PiP action.
Use the support states to build your own browser fallback experience.
───────────────────────────
WORKFLOW EVENTS
The controller provides:
✦ Picture-in-Picture opens
✦ Picture-in-Picture closes
✦ Picture-in-Picture fails to open
When an action fails, check Last error for additional detail.
The YouTube PiP Player also exposes:
✦ YouTube player is ready
✦ YouTube player fails
Its Player Error state contains the most recent YouTube helper error.
───────────────────────────
BROWSER SUPPORT
Document Picture-in-Picture is a newer browser API and is not available in every browser.
The feature requires HTTPS in supporting browsers and opening the window requires a user interaction.
Always use the controller's support states when PiP is an important part of your app's UX.
Standard video Picture-in-Picture has separate browser support, which is why the plugin exposes Document PiP supported and Video PiP supported independently.
───────────────────────────
A GOOD DEFAULT BUILD
For most apps:
✦ place one Picture in Picture Controller on the relevant page
✦ trigger PiP from a user click
✦ use Open HTML for lightweight custom interfaces
✦ use Open URL for Bubble pages or embeddable content
✦ use Continue Video for native video and Vimeo
✦ use Continue YouTube plus the helper element for Bubble YouTube playback
✦ check support states before showing PiP controls
✦ use the failure event and Last error when you need custom fallback messaging
The plugin handles the browser PiP plumbing. Your Bubble app keeps control of the interface and workflows.
Built on Bubble
