---
title: "Embedded Demo Performance & Loading Optimization"
slug: "/help/demos/publish/embed-performance"
last_updated: "2026-02-12T14:36:35Z"
zendesk_id: 49030357978259
zendesk_url: "https://help.walnut.io/hc/en-us/articles/49030357978259-Embedded-Demo-Performance-Loading-Optimization"
locale: "en-us"
product: "demos"
topic: "publish"
displayed_sidebar: "demosSidebar"
---

## **Overview**

[Embedded demos](https://help.walnut.io/hc/en-us/articles/32071112651027) are powerful engagement drivers — but how and when they load directly impacts page speed, user experience, and conversion performance.

This guide explains how embedded demos load, the difference between **eager** and **lazy** loading, and the most effective techniques for optimizing performance across marketing pages, demo libraries, and learning hubs.

**In This Guide:**

-   [How Embedded Demos Load](#h_overview)
-   [Eager vs Lazy Loading](#h_eager_vs_lazy)
-   [When to Use Each Strategy](#h_when_to_use)
-   [Web Performance Optimization Techniques](#h_optimization_techniques)
-   [Performance Best Practices](#h_best_practices)

:::note[🎯 Looking for More Optimization Tips? Explore These Resources]

-   [Embedded Demo Performance: Benchmarks, Signals, and What to Optimize](https://help.walnut.io/hc/en-us/articles/48543853151763)
-   [Win With Embedded Demos: Drive Engagement, Accessibility, and Discoverability](https://help.walnut.io/hc/en-us/articles/48562570373395)
-   [Embedded Demos Resource Pack](https://help.walnut.io/hc/en-us/articles/48469268962579)

:::

---

## **How Embedded Demos & Playlists Load**

Embedded Walnut demos and playlists are implemented using an HTML `<iframe>` element. By default, iframes load as soon as the page loads. This is known as **eager loading**.

Standard Walnut embed code looks like this:

```
<iframe
  src="https://app.teamwalnut.com/player/?demoId=92fc28c0-ced2-402f-b4d2-0a3968d39370&showGuide=true&showGuidesToolbar=true&showHotspots=true&openGuidesToolbar=false"
 
  allow="fullscreen"
  allowfullscreen="true"
  loading="eager"
  name="walnut_iframe"
  sandbox="allow-scripts allow-same-origin allow-popups allow-forms allow-downloads allow-popups-to-escape-sandbox"
  title="Walnut embedded demo"
  width="100%"
  height="100%"
  frameborder="none">
`</iframe>`
```

Notice the `**loading="eager"**` attribute. This tells the browser to load the demo immediately when the page loads.

While eager loading provides instant interactivity, it can impact:

-   Page load speed
-   Core Web Vitals
-   Time to Interactive (TTI)
-   Mobile performance

Optimizing how and when demos load ensures a smooth experience without sacrificing engagement.

---

## **Eager vs Lazy Loading**

### **Eager Loading (Default)**

With **eager** **loading**, the demo loads immediately when the page loads, regardless of whether the iframe is currently visible on the screen. This is the default behavior for iframes and the default configuration used in Walnut embed codes.

```
<iframe
  src="https://app.teamwalnut.com/player/?demoId=92fc28c0-ced2-402f-b4d2-0a3968d39370&showGuide=true&showGuidesToolbar=true&showHotspots=true&openGuidesToolbar=false"
 
  allow="fullscreen"
  allowfullscreen="true"
  loading="eager" <---- * DEFAULT LOADING ATTRIBUTE *
  name="walnut_iframe"
  sandbox="allow-scripts allow-same-origin allow-popups allow-forms allow-downloads allow-popups-to-escape-sandbox"
  title="Walnut embedded demo"
  width="100%"
  height="100%"
  frameborder="none">
`</iframe>`
```

**Best for:**

-   Hero demos positioned within the initial viewport (visible screen area on page load).
-   Conversion-focused landing pages
-   Pages where the demo is the primary content

**Tradeoff:** Increased initial page load time, which can be more pronounced on slower connections, high-latency networks, or mobile devices.

---

### **Lazy Loading**

**Lazy** **loading** delays the iframe from loading until the viewer scrolls close to where it appears on the page.

```
<iframe
  src="https://app.teamwalnut.com/player/?demoId=92fc28c0-ced2-402f-b4d2-0a3968d39370&showGuide=true&showGuidesToolbar=true&showHotspots=true&openGuidesToolbar=false"
 
  allow="fullscreen"
  allowfullscreen="true"
  loading="lazy" <---- * LAZY LOADING ATTRIBUTE *
  name="walnut_iframe"
  sandbox="allow-scripts allow-same-origin allow-popups allow-forms allow-downloads allow-popups-to-escape-sandbox"
  title="Walnut embedded demo"
  width="100%"
  height="100%"
  frameborder="none">
`</iframe>`
```

The `**loading="lazy"**` attribute tells the browser to delay loading until necessary.

**Best for:**

-   Demos positioned below the initial viewport (visible screen area on page load).
-   Long-form marketing pages
-   Content hubs and documentation pages

**Tradeoff:** Viewers may notice a brief loading moment when they reach the demo. The delay depends on connection speed, but is usually minimal and often not noticeable.

---

## **When to Use Each Strategy**

| Use Case | Recommended Strategy |
| --- | --- |
| Hero demo above the initial landing viewport | [Eager (default)](#h_01KH6ZBDSSQR0F2XS8VNZHJ230) |
| Demo below the initial landing viewport | [Lazy loading](#h_01KH6ZBDSSSDYB0N3PWS3TQWGM) |
| Demo libraries | [Load on demand (Web Performance Optimization)](#h_optimization_techniques) |
| Modal-triggered demo | [Inject iframe after click](#h_01KH703R290FW5KPCDHPYV7GW0) |

:::note[Performance Takeaway]

Load immediately ([eager](#h_01KH6ZBDSSQR0F2XS8VNZHJ230)) when a single demo is the primary focus. Use on-demand loading when the page includes multiple demos ([lazy](#h_01KH6ZBDSSSDYB0N3PWS3TQWGM) or [on-demand](#h_optimization_techniques)).

:::

---

## **Web Performance Optimization Techniques**

These **web development performance techniques** can be used to control when and how iframes load. While Walnut provides the embed code, implementing these patterns _typically requires support from a developer_ or someone managing your website codebase.

The following approaches help reduce initial page load impact while preserving a strong demo experience:

-   [Overlay Technique](#h_01KH703R28BNWN9WMAHD570TBF)
-   [Load iframe After Button Click](#h_01KH703R29E37D82SSYHWY3FKJ)
-   [Modal Injection Pattern](#h_01KH703R290FW5KPCDHPYV7GW0)
-   [Demo Library & Grid Implementations](#h_01KH703R292V0NTZZRE11AYZ4A)

:::note[🔨 Important Note]

The techniques in this section are **not configured inside Walnut**. They must be implemented by your web development team or the team managing your website and/or portal infrastructure.

:::

---

### **Overlay Technique**

**What it is:** A progressive loading approach that displays a static preview image with a “Start Demo” button overlay.

**How it works:** The iframe is injected only after the user clicks the overlay. This prevents the demo from impacting initial page load and improves perceived performance.

![](pathname:///images/b24f433a54fe6394.gif)

:::note[🔨 Note]

Walnut generates the **iframe embed code only.** The preview image, overlay design, and button-trigger logic must be implemented by your web development team as part of your website’s front-end experience.

:::

---

### **Load iframe After Button Click**

**What it is:** A fully on-demand loading pattern using JavaScript.

**How it works:** The iframe does not exist in the DOM until a user clicks a trigger button.

```
document.getElementById("launchDemo").addEventListener("click", function() {
  document.getElementById("demoContainer").innerHTML =
    'IFRAME EMBED CODE HERE';
});
```

This ensures zero demo load impact until intentional interaction and is ideal for performance-sensitive pages.

---

### **Modal Injection Pattern**

**What it is:** A dynamic loading technique for pop-up or modal-based demos.

**How it works:** The iframe is inserted only when the modal opens and can optionally be removed when the modal closes to free resources. Ideal for “Watch Demo” buttons and conversion-focused landing pages.

```
function openDemo() {
  document.getElementById("modalBody").innerHTML =
    'IFRAME EMBED CODE HERE';
}
```

**Example:**

![](pathname:///images/edc7479e248b1e28.gif)

---

### **Demo Library & Grid Implementations**

**What it is:** A controlled loading strategy for pages that feature multiple demos.

**Why it matters:** Loading multiple iframes simultaneously can significantly impact page speed and Core Web Vitals.

**Recommended pattern:**

-   Display preview thumbnails
-   Load only one demo at a time
-   Replace the iframe when a new demo is selected
-   Use pagination or tabs instead of multiple live embeds

:::note[Library Implementation Takeaway]

One active iframe at a time. Always.

:::

---

## **Performance Best Practices**

-   Default to **lazy** **loading** for demos placed below the initial viewport.
-   Use [**on-demand/web optimized loading**](#h_optimization_techniques) for demo galleries.
-   Avoid loading multiple iframes simultaneously.
-   Use overlays for SEO-heavy pages.
-   Test impact using Lighthouse or PageSpeed Insights.

:::note[Final Takeaway]

Embedded demos drive engagement — but performance drives reach. Optimize your load strategy based on placement and intent.

:::

---

## **Related Resources**

-   [**Embedded Demo Resource Pack**](https://help.walnut.io/hc/en-us/articles/48469268962579)
-   [**Embedded Demo Performance: Benchmarks, Signals, and What to Optimize**](https://help.walnut.io/hc/en-us/articles/48543853151763)
-   [**Win With Embedded Demos: Drive Engagement, Accessibility, and Discoverability**](https://help.walnut.io/hc/en-us/articles/48562570373395)
-   [**Walnut ROI & Analytics Resource Pack**](https://help.walnut.io/hc/en-us/articles/46515078625683)

:::note[Want a Second Set of Eyes?]

[**Team Walnut**](https://help.walnut.io/hc/en-us/requests/new?ticket_form_id=4415537333523) can review your embed strategy, loading behavior, and performance setup to help you optimize with confidence. 💜

:::