---
title: "How to embed an iframe in a custom popup"
description: "Place an external web page in a custom popup with the Insert iframe button. Use one embed for every feature or a different embed for each one."
seo:
  title: "Embed an iframe in a popup"
sidebar:
  label: "Embed an iframe"
---

An iframe places an external web page inside a custom popup, such as a map, a dashboard, or a report viewer. Click `Insert iframe` in the popup editor and paste the page's embed URL or its full embed code. The address must be an `https://` page on another site, so you cannot embed a MangoMap map in a popup.

**[See it on an example map](https://mangomap-staging.com/examples-staging/maps/y4h0ctdr/popup-media-logic-lab)**

Open the Popup Media & Logic Lab. In the legend, turn on `Sites — Embeds`, then click a site. Its popup shows the site's Wikipedia article in an iframe.

## Common uses

- **A chart or a report from another service, one for each feature.** For example, a soundings report for each survey point, or a timeline chart for each site. The other service hosts the page, and the layer stores the page's ID. See [Use a different embed per feature](#use-a-different-embed-per-feature).
- **One dashboard or page for the whole layer.** See [Use the same embed for every feature](#use-the-same-embed-for-every-feature).

### Photos and PDFs

To show a photo or open a PDF for each feature, you don't need an iframe:

- **A photo for each feature** — use `Insert image` with a variable, such as `{photo_url}`. See [How to add an image to a custom popup](/docs/configuring-popups/add-images-to-popup).
- **A PDF for each feature**, such as a permit, a report, or a data sheet — add a link or a button whose address holds a variable. Each feature's link opens its own PDF in a new tab:

  ```text
  https://example.com/reports/{report_id}.pdf
  ```

  If an attribute already holds the full address of the PDF, use only that variable, such as `{report_url}`. See [Add a hyperlink](/docs/configuring-popups/write-custom-popup-template#add-a-hyperlink) and [How to add an interactive button to a custom popup](/docs/configuring-popups/add-interactive-buttons-to-popup).

Don't embed a PDF in an iframe. Chrome does not show a PDF inside a popup's iframe.

## Before you start

- The popup type must be `Custom`. See [How to write a custom popup template](/docs/configuring-popups/write-custom-popup-template).
- You need the embed URL for the content. For most services, this is different from the page URL. Google Maps, Tableau, OpenStreetMap, and similar tools give an embed URL or embed code in their share dialog.
- The other site must allow embedding. Some sites (banks, social media, login-walled apps) block it. Those pages do not load in a popup.

## Insert an iframe

In the Custom popup editor, place the cursor where you want the embed. Click `Insert iframe` in the toolbar.

<img src="/_assets/configuring-popups/embed-iframe-in-popup--dialog.png" alt="Embed URL dialog below the popup editor toolbar, with the placeholder https://example.com/embed, the helper text Paste an embed URL or iframe code, an Insert simple variable button, Height (pixels) set to 300, and the Embed button" width="1600" height="960" />

Paste the embed URL or the full `<iframe>` code into `Embed URL`. From embed code, MangoMap keeps only the address and the height.

Set `Height (pixels)` if you want the embed taller or shorter. The width always fills the popup.

Press `Enter` or click `Embed`. The editor shows the embedded page at the cursor. An address that ends in `.mp4` or `.webm` becomes a video player instead. See [How to embed a video file in a custom popup](/docs/configuring-popups/embed-a-video-file-in-popup).

## If the dialog refuses the address

The dialog accepts only an `https://` address on another site. It refuses an `http://` address, a MangoMap page, and a page on the map's own site:

<img src="/_assets/configuring-popups/embed-iframe-in-popup--error.png" alt="Embed URL dialog with http://example.com in the field and the error Use an HTTPS embed URL from an external site" width="1600" height="960" />

Copy the `https://` embed URL from the other site's share dialog and paste that.

## Use the same embed for every feature

Paste a fixed URL into the field. The same page shows in every feature's popup. Use it for a dashboard or a resource that applies to the whole layer.

## Use a different embed per feature

To show a different page for each feature, put `{field_name}` variables in the address. Click `Insert simple variable` in the dialog to add one at the cursor, or type it.

For example, each site in this layer has its own Wikipedia article. The `wikipedia_slug` attribute holds the end of the article's address, such as `National_Museum_of_Singapore`. This embed shows each site's article:

```text
https://en.wikipedia.org/wiki/{wikipedia_slug}
```

A common use is a chart or a report that another service makes for each feature, such as a soundings report for each survey point, or a timeline chart for each site. The other service hosts the page. The layer stores only the page's ID, and the address puts it in:

```text
https://charts.example.com/soundings/{survey_id}
```

For a photo or a PDF, see [Photos and PDFs](#photos-and-pdfs).

The editor cannot load an address that still has variables in it. It shows a dashed box with `Embed:` and the address instead:

<img src="/_assets/configuring-popups/embed-iframe-in-popup--variable.png" alt="Popup editor for Sites — Embeds with a dashed box that reads Embed: https://en.wikipedia.org/wiki/{wikipedia_slug}, below the Article: line" width="1600" height="960" />

When the popup opens, each variable takes the feature's raw value, not the value as formatted on the `Format` tab.

{/* TODO: product - Insert iframe refuses an address that is only a variable, such as {dashboard_url}, with the browser's error "Failed to construct 'URL': Invalid URL" (../mangomap packages/mangomap-ui/src/components/text-editor/shared/embed-input.ts:21). The popup renderer supports it. When the dialog accepts it, add a "{chart_url}" example here and remove the next paragraph. See v4-sample-data/DOCS-CAPTURE-COVERAGE.md, "Product issues". */}

The address must start with the fixed part, such as `https://charts.example.com/soundings/{survey_id}`. If an attribute holds the page's full address, such as `chart_url`, you cannot insert `{chart_url}` on its own today. The dialog shows `Failed to construct 'URL': Invalid URL`.

## Check the embed

Save the popup, then click a feature on the map. The page loads in the popup:

<img src="/_assets/configuring-popups/embed-iframe-in-popup--popup.png" alt="Popup for National Museum of Singapore with the Article: line and the Wikipedia article National Museum of Singapore below it, in a frame" width="1600" height="960" />

## When an embed doesn't show

- **A variable is empty.** If any variable in the address has no value for a feature, that feature's popup leaves the embed out. The rest of the popup still shows.
- **The address is blocked.** An `http://` address, a MangoMap page, or a page on the map's own site is removed from the popup with no message. This also happens to older popups that embedded a MangoMap map.
- **The other site refuses to be embedded.** The frame stays empty or shows that site's error page. Test the embed URL with a real feature after you save.

{/* TODO: product - A blocked embed is removed from the popup with no message for the map owner (../mangomap packages/mangomap-ui/src/lib/sanitization.ts:335, config/popup-embeds.ts). When the product shows a message, describe it in "When an embed doesn't show". See v4-sample-data/DOCS-CAPTURE-COVERAGE.md, "Product issues". */}

## Save the popup

After inserting the embed, click `Save Changes` at the bottom right of the editor.

## Related

- [How to write a custom popup template](/docs/configuring-popups/write-custom-popup-template)
- [How to insert attribute values into a custom popup](/docs/configuring-popups/insert-attribute-values-into-popup)
- [How to embed a YouTube video in a custom popup](/docs/configuring-popups/embed-youtube-in-popup)
- [How to embed a video file in a custom popup](/docs/configuring-popups/embed-a-video-file-in-popup)
- [Popup tab controls](/docs/configuring-popups/popup-reference) — every message the `Embed URL` dialog shows