🎨 LiveDab Realtime Gallery Widget

Development Demo & Integration Guide - A self-contained, embeddable JavaScript component for displaying real-time image galleries

📖 About This Page

This page serves two purposes:

  1. Development Demo: Below you'll see live examples of the widget running in development mode
  2. Integration Guide: Complete documentation on how to embed the widget into your own website
🔒 Shadow DOM Isolation The widget uses Shadow DOM encapsulation, meaning its styles are completely isolated from your page's CSS. This prevents any conflicts with your existing styles. The visual boundaries shown in the demo are for demonstration purposes only.

🚀 Quick Start: Embed in 2 Steps

To add the LiveDab Gallery Widget to your website, simply add these two elements:

  1. Add the container element where you want the gallery to appear: 
    <div livedab-stream-id="YOUR_STREAM_ID"></div>
  2. Load the widget script at the end of your <body>: 
    <script type="module" crossorigin src="https://stream.livedab.com/assets/index.js"></script>
✅ That's it! The widget will automatically initialize and display your gallery. No JavaScript configuration needed!

📝 Understanding the Script Tag Attributes

The widget script tag includes two important attributes:

Attribute Required? Why It's Needed
type="module" Yes The widget is built as an ES module using modern JavaScript. This attribute tells the browser to load it as a module, enabling:
  • Proper scope isolation
  • Support for modern JavaScript features
  • Deferred execution (loads without blocking page render)
Without this, the widget will not function correctly.
crossorigin Recommended Enables proper CORS (Cross-Origin Resource Sharing) handling when loading from a CDN:
  • Allows detailed error messages in console (for debugging)
  • Enables error tracking and monitoring
  • Required for some security features
Technically optional, but strongly recommended for production use.
💡 Browser Compatibility ES modules (type="module") are supported in all modern browsers: Chrome 61+, Firefox 60+, Safari 11+, Edge 16+. This covers 98%+ of users. Internet Explorer is not supported.

⚙️ Configuration Options

The widget is configured using HTML attributes on the container element:

Required Attributes

Attribute Description Example
livedab-stream-id Your unique gallery stream ID (required) livedab-stream-id="6908e52a36ff006e1cb46633"

Optional Attributes

Attribute Description Default Example
data-api-url Custom API base URL for fetching gallery data Environment default data-api-url="https://api.mysite.com"
data-polling-interval Auto-refresh interval in milliseconds 5000 (5 seconds) data-polling-interval="3000"
data-max-items Maximum number of items to display Unlimited data-max-items="20"
⏸️ Disable Auto-Refresh: Set data-polling-interval="0" to disable automatic polling. The gallery will only fetch data once on load.

💡 Integration Examples

Example 1: Basic Integration

The simplest possible integration with a single gallery:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My Gallery</title>
  </head>
  <body>
    <h1>Welcome to My Gallery</h1>

    <!-- Gallery Widget -->
    <div livedab-stream-id="6908e52a36ff006e1cb46633"></div>

    <!-- Widget Script -->
    <script type="module" crossorigin src="https://stream.livedab.com/assets/index.js"></script>
  </body>
</html>

Example 2: Multiple Galleries on One Page

You can embed multiple galleries by adding multiple container elements: 

<body>
  <h1>Event Photo Galleries</h1>

  <h2>Conference 2024</h2>
  <div livedab-stream-id="6908e52a36ff006e1cb46633"></div>

  <h2>Workshop Sessions</h2>
  <div livedab-stream-id="691249af13b49484f969228c"></div>

  <script type="module" crossorigin src="https://stream.livedab.com/assets/index.js"></script>
</body>

Example 3: Custom API URL

Point the widget to your custom API endpoint:

<div
  livedab-stream-id="6908e52a36ff006e1cb46633"
  data-api-url="https://api.mycompany.com"
></div>

<script type="module" crossorigin src="https://stream.livedab.com/assets/index.js"></script>

Example 4: Custom Polling Interval

Refresh every 3 seconds instead of the default 5 seconds:

<div
  livedab-stream-id="6908e52a36ff006e1cb46633"
  data-polling-interval="3000"
></div>

<script type="module" crossorigin src="https://stream.livedab.com/assets/index.js"></script>

Example 5: With Custom Container Styling

The widget doesn't interfere with your page styles, so you can style the container: 

<style>
  .gallery-wrapper {
    max-width: 1200px;
    margin: 40px auto;
    padding: 20px;
    background: #f5f5f5;
    border-radius: 8px;
    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1);
  }
</style>

<div class="gallery-wrapper">
  <h2>Latest Photos</h2>
  <div livedab-stream-id="6908e52a36ff006e1cb46633"></div>
</div>

<script type="module" crossorigin src="https://stream.livedab.com/assets/index.js"></script>

Example 6: Static Gallery (No Auto-Refresh)

Load the gallery once without automatic updates:

<div
  livedab-stream-id="6908e52a36ff006e1cb46633"
  data-polling-interval="0"
></div>

<script type="module" crossorigin src="https://stream.livedab.com/assets/index.js"></script>

🔧 How It Works

  1. Automatic Discovery: The widget script scans the page for all elements with the livedab-stream-id attribute
  2. Shadow DOM Creation: For each found element, it creates an isolated Shadow DOM to prevent style conflicts
  3. Data Fetching: Connects to the API to fetch gallery items for each stream ID
  4. Real-time Updates: Automatically polls for new items at the configured interval
  5. Responsive Display: Renders items in a responsive masonry grid (1-4 columns based on screen size)
  6. Smooth Animations: Applies entrance animations to new items as they appear

🌐 Browser Support

The widget requires two modern browser features:

Supported Browsers

Browser Minimum Version Release Date
Chrome 63+ December 2017
Firefox 63+ October 2018
Safari 11.1+ March 2018
Edge 79+ January 2020
Opera 50+ January 2018

Coverage: This covers >98% of all web users worldwide. Internet Explorer is not supported.

🔍 Troubleshooting

Widget Not Appearing?

  1. Check that you've added the livedab-stream-id attribute to your container element
  2. Verify the stream ID is correct and the gallery has content
  3. Open the browser console (F12) and look for error messages
  4. Ensure the widget script loads successfully (check Network tab in DevTools)

Script Loading Issues?

⚠️ Important: The container element must exist in the HTML before the script loads. Always place the <script> tag after your container elements, ideally at the end of the <body>.

No Images Showing?

  1. Verify your stream ID is correct
  2. Check that the stream has published items
  3. If using a custom API URL, verify it's accessible
  4. Check the browser console for API errors

📚 Additional Resources

For more detailed information, see:

View Full Integration Guide

🎬 Live Demo

Below are two live instances of the widget running in development mode. Notice how each widget is completely isolated with its own Shadow DOM:

👇 Development Mode Notice These examples use src/main.tsx for hot-reloading during development. In production, you'll use the compiled widget.js bundle instead.

Gallery Stream 1

Stream ID: 694925aade854feb27ffa8f7

LiveDab Realtime Gallery Widget v0.0.0
Built with React, TypeScript, TailwindCSS, and Framer Motion