How to Embed an iframe in Confluence Cloud

Short answer: Confluence Cloud gives you two built-in ways to embed another web page: paste the link and switch it to the Embed view, or insert the iFrame macro and give it a URL. If you want a responsive frame, a caption or two embeds side by side, use an HTML macro app; HTML Macro+ can write the iframe code for you from a normal YouTube, Figma, Google Docs or Power BI link. None of these can show a site that refuses to be framed, which is the usual reason an embed comes up blank.

This guide walks through all three options, shows working examples for YouTube, Google Sheets and dashboards, and ends with a checklist for blank embeds.

Three ways to embed in Confluence Cloud

Start with the first one that works. Smart Links need no setup, the iFrame macro covers most other cases, and an HTML macro is for when you want control over how the embed looks.

Option 1: Smart Link embed

When you paste a URL into a Confluence page, it usually turns into a Smart Link. Smart Links have several views: Inline shows just the title, Card adds a preview with some context, and Embed shows the content itself in the page so readers can use it without leaving Confluence.

To switch a link to an embed:

1. Paste the URL into the page, or type /link.
2. Select the link.
3. In the toolbar that appears, choose the embed view.
4. Drag the edges to resize it, then publish.

This is the quickest option for YouTube videos, Figma files, Loom recordings, Google Docs and Sheets, and Jira work items. Content from apps that need a login, such as a Google Sheet, is shown according to each reader's own access, so a reader without permission sees a prompt instead of the data. If a link does not offer an embed view, Confluence does not recognise the source, and you need one of the next two options.

Option 2: the built-in iFrame macro

The iFrame macro embeds any web page by URL. To add it:

1. Edit the page and type /iframe, then select iFrame.
2. Enter the address of the page you want to show. Use https://.
3. Set the other parameters in the macro panel. Changes save as you make them.
4. Publish the page.

The parameters that still have an effect in Cloud, according to Atlassian's documentation:

Older parameters such as title, ID, class and margin are deprecated and do nothing. In practice you set the URL and a height that fits the content, for example 600 pixels for a form or 800 for a dashboard.

The iFrame macro is the right choice when the embed only needs to appear on the page. It has no way to add a caption, keep a 16:9 ratio on narrow screens, or place two frames next to each other.

Option 3: your own iframe in an HTML macro

Confluence Cloud has no HTML macro of its own, so this needs an app from the Atlassian Marketplace. The examples below use HTML Macro+ for Confluence, which is free and runs on Atlassian Forge. Edit a page, type /html and select HTML Macro+ for Confluence. The editor has separate HTML, CSS and JavaScript tabs and a live preview.

Two things to know before you start:

• Admins choose which domains can load. HTML Macro+ has three security modes: Block all, Whitelist only and Allow all. In Block all mode no iframes load. In Whitelist only mode, an iframe loads only if its domain is on the list; otherwise readers see a blocked content placeholder. An empty whitelist behaves like Block all. Admins set this under Confluence Administration > Manage apps > HTML Macro+ for Confluence > Configure, as described in the security settings guide.
• The macro sizes itself. The macro's height follows its content, so you control the frame size with CSS instead of a height field.

Adding youtube.com to the whitelist also covers www.youtube.com, because an entry matches the domain and its subdomains. Use *.example.com if you want subdomains only.

The quick way: embed templates

You don't have to write the iframe yourself. In the HTML Macro+ editor, click Embed templates, pick the service and paste the link you already have. The template converts it into the address the service expects inside a frame and writes responsive HTML and CSS into the editor, with a preview before you insert it.

Choose Add below to stack several embeds in one macro, or Replace content to start fresh. If your admin's settings block the service's domain, the dialog tells you before you insert it. The generated code stays editable, so you can still add a caption or change the size. See the embed templates guide for which link to paste for each service.

The examples below show the code by hand, for when you want a layout of your own.

Example: embed a YouTube video

On YouTube, open the video, select Share > Embed and copy the src address. It looks like https://www.youtube.com/embed/VIDEO_ID. A normal watch?v= link will not play in a frame. (The YouTube embed template in HTML Macro+ accepts the normal link and converts it for you.)

With the iFrame macro, paste that address and set the height to about 400 pixels. With HTML Macro+, you can make the frame keep its shape on any screen width:

HTML

<figure class="video">
  <iframe
    src="https://www.youtube.com/embed/VIDEO_ID"
    title="Onboarding walkthrough"
    allow="fullscreen; picture-in-picture"
    allowfullscreen
  ></iframe>
  <figcaption>Onboarding walkthrough, 8 minutes</figcaption>
</figure>

CSS

.video { margin: 0; font-family: -apple-system, "Segoe UI", sans-serif; }
.video iframe {
  width: 100%;
  aspect-ratio: 16 / 9;
  border: 0;
  border-radius: 10px;
}
.video figcaption { margin-top: 8px; font-size: 13px; color: #44546f; }

For HTML Macro+, youtube.com needs to be on the whitelist unless your admin allows all domains. If you prefer YouTube's privacy-enhanced mode, use youtube-nocookie.com in the address and whitelist that domain instead.

Example: embed a Google Sheet

There are two good ways to put a Google Sheet on a Confluence page.

For a sheet your team already shares in Google, paste the sheet's link and switch it to the embed view (Option 1). Readers see it with their own Google access, so permissions stay in Google.

For a read-only table anyone can see, publish it from Google Sheets:

1. In Google Sheets, open File > Share > Publish to web.
2. Choose the Embed tab, pick the whole document or one sheet, and select Publish.
3. Copy the iframe code. Its src starts with https://docs.google.com/spreadsheets/d/e/.

Paste that address into the iFrame macro, or use the full iframe code in HTML Macro+ with docs.google.com (or google.com) on the whitelist. Two cautions: a published sheet is visible to anyone who has the address, so never publish sheets with private data, and edits reach the embed only while the sheet's Automatically republish when changes are made option is on.

HTML Macro+ also lets you place a sheet next to something else, such as a chart and the table it comes from:

<div class="pair">
  <iframe src="https://docs.google.com/spreadsheets/d/e/SHEET_ID/pubhtml?widget=true&headers=false" title="Q3 budget"></iframe>
  <iframe src="https://docs.google.com/spreadsheets/d/e/SHEET_ID/pubchart?oid=CHART_ID&format=interactive" title="Q3 budget chart"></iframe>
</div>

.pair { display: grid; grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); gap: 16px; }
.pair iframe { width: 100%; height: 420px; border: 1px solid #dfe1e6; border-radius: 8px; }

If you would rather draw the chart in Confluence from your own data, see how to make a pie chart in Confluence.

Example: embed a dashboard or internal tool

Status pages, BI dashboards and internal web tools are common things to embed on a team's home page. Most BI tools have an embed or share option that gives you a frame address meant for this. Use it rather than the address in your browser bar, because the normal page often blocks framing.

A few notes:

• Some tools need embedding turned on first. Grafana, for example, refuses to be framed until allow_embedding is enabled in its server configuration.
• If the tool needs a login, readers sign in inside the frame, and some login pages refuse to load in a frame at all. Check with a colleague's account before you rely on it.
• If you only need a few numbers on the page, consider building the panel in Confluence instead. Our guide to building a status dashboard in Confluence shows how.

Why an iframe shows blank

When an embed shows an empty box, a grey page or a "refused to connect" message, check these in order:

1. The site blocks framing. Many sites send an X-Frame-Options or Content-Security-Policy: frame-ancestors header that tells browsers not to show them inside other pages. No Confluence setting or app can override this. Look for the site's own embed address, or use a link instead.
2. The address uses http://. Confluence is served over HTTPS, and browsers block insecure frames on secure pages. Change the address to https://.
3. You used the page address, not the embed address. YouTube, Google Sheets, maps and BI tools all have a separate embed URL. In HTML Macro+, an embed template does this conversion for you.
4. The domain is not whitelisted (HTML Macro+). You will see a blocked content placeholder instead of a blank frame. Ask your admin to add the domain shown in the iframe's src. The troubleshooting guide lists the common ones.
5. The height is too small. In the iFrame macro, set an explicit height. In an HTML macro, give the iframe a height or an aspect ratio in CSS.
6. The browser blocked it. Privacy extensions and strict browser settings can block third-party frames. Try another browser to rule this out.

If you are moving from Confluence Data Center and your old pages used the HTML or HTML Include macro for embeds, see keeping legacy macros working after a Cloud migration.

Frequently asked questions

Does Confluence Cloud support iframes?

Yes. Confluence Cloud includes an iFrame macro that embeds a web page by URL, and Smart Links can show supported apps in an embed view. What it does not have is a built-in HTML macro for writing your own iframe code. For that you need a Marketplace app.

Why is my iframe blank in Confluence?

Usually because the site you are embedding does not allow other sites to frame it. Other common causes are an http:// address, using the normal page address instead of the embed address, and a height that is too small. With an HTML macro app, the domain may also need to be allowed by your admin.

How do I embed a Google Sheet in Confluence?

Paste the sheet's link and switch it to the embed view, which keeps Google's sharing permissions. For a public, read-only table, use File > Share > Publish to web in Google Sheets and put the embed address in the iFrame macro or an HTML macro.

Can I make an iframe responsive in Confluence?

Not with the iFrame macro, which uses a fixed width and height. In an HTML macro, set width: 100% and an aspect-ratio on the iframe in CSS, as in the YouTube example above. HTML Macro+ embed templates produce responsive code like this automatically.

How do I embed Power BI, Figma or Miro in Confluence?

Try a Smart Link embed first, which works for many design tools. For Power BI, Tableau Public, Airtable and anything without an embed view, use an HTML macro. In HTML Macro+, open Embed templates, choose the service and paste a "Publish to web" or share link. The file must be shared so that your readers can open it.

Is it safe to embed other sites in Confluence?

The embedded site runs in its own frame and cannot read your Confluence page. The bigger risk is showing content you did not mean to share, such as a published sheet, or letting editors frame any site. HTML Macro+ lets admins limit framing to approved domains and limit who can edit the macro.

Can I still use the old HTML macro from Data Center?

Not natively. Confluence Cloud does not include it, and migrated pages that used it show an error. An HTML macro app such as HTML Macro+ renders those legacy macros again; see our overview of the HTML macro for Cloud.

Try it

Try the built-in options first: paste a link and choose embed, or type /iframe. When you need a responsive frame, a caption, several embeds in one layout or an embed built from a plain link, install HTML Macro+ for Confluence, free on the Atlassian Marketplace, and follow the installation guide. For more ideas, see 5 ways to use HTML in Confluence Cloud.