Overview

The iframe viewer is the general-purpose embed: it places any external web page inside your post, framed and captioned consistently with the other StoryKit viewers.

Use it when none of the specialized viewers fits — digital exhibits, library viewers (like the Biodiversity Heritage Library), data dashboards, interactive timelines, or any web resource that offers an embeddable URL.

Use a specialized viewer instead when one exists for your content: the Image, Map, Image Compare, YouTube, and Network viewers all offer interactivity that a plain iframe can’t (zooming, action links, and so on).

Attributes

Required Attributes

src

The URL of the page to embed.

1

src="https://www.biodiversitylibrary.org/item/128371#page/12/mode/1up"

Not every site allows itself to be embedded — see Troubleshooting below.

Optional Attributes

caption

Text displayed below the embedded page.

1

caption="Curtis's Botanical Magazine, 1845"

aspect

The width-to-height ratio of the frame (e.g. 1.5 for landscape, 0.75 for portrait). If neither aspect nor height is set, the frame uses the browser’s default iframe height, which is usually too short — set one of them.

1

aspect="1.33"

height

An explicit frame height in pixels, as an alternative to aspect.

1

height="600"

width

An explicit frame width in pixels. Normally omitted — the frame fills the available width.

1

width="800"

class

Size and position words like medium right float — see Formatting Tips.

1

class="medium right"

id

An identifier for the frame. The iframe viewer doesn’t support action links, so an id is rarely needed, but it can be useful as a link target.

1

id="bhl1"

Example

1
2
3
4
5

{% include embed/iframe.html
    src="https://www.openstreetmap.org/export/embed.html?bbox=-110.3,36.9,-110.1,37.1&layer=mapnik"
    caption="An embedded external page"
    aspect="1.5"
%}
An embedded external page

Troubleshooting

The frame is blank or shows a refusal message. Many sites block embedding (with the X-Frame-Options or frame-ancestors security headers). There’s no way around this from StoryKit — check whether the site offers a dedicated “embed” URL (many viewers and exhibits do), or link to it normally instead.

The frame is tiny or cut off. Set aspect (or height) explicitly. Without one, browsers give iframes a small default height.

The page inside looks cramped. Try the site’s mobile or embed-specific URL if it has one; full desktop pages often don’t adapt well to a framed area.