Introduction
Timepath products are designed to be embedded anywhere — on your newsroom website, in your CMS, inside a WordPress post, or on any page that accepts HTML. Every published product gets a unique embed URL on embed.timepath.co that you can drop straight into an <iframe> element.
There are two embedding methods. The iFrame embed works on all Timepath plans and sandboxes the product in its own browsing context — safe, simple, and universally supported. The Script embed renders the product natively inside your page for deeper layout control and is available on Enterprise plans.
The embed code for any product is always available in the Share dialog inside the Timepath editor — copy it from there and paste it wherever you need it.
Method Comparison
| iFrame Embed | Script Embed | |
|---|---|---|
| Plan required | All plans | Enterprise only |
| Supported products | All 9 embeddable products | Collection, Quiz, Poll, Survey, GeoStory |
| Renders inside | Sandboxed iframe | Natively in your page DOM |
| Layout control | Height set manually or via auto-resize script | Full — product flows with your page layout |
| Style isolation | Complete (styles cannot leak out or in) | Partial — global CSS may interact |
| Dark mode | ?colorMode=dark URL param | data-timepath-darkmode attribute |
| When to use | Default choice for most integrations | When you need native rendering or CLS-free layout |
Quick Start Guide
Get a Timepath product live on your website in under five minutes using the iFrame method.
- 1
Publish your product
Open the Timepath editor and click Publish. Unpublished products will not load in an embed — the page will appear blank until you publish.
- 2
Open the Share dialog
In the editor toolbar, click the Share button (or the ··· overflow menu). Select the Embed tab to reveal the iFrame snippet.
- 3
Copy the embed code
Click Copy code. The snippet already contains the correct product URL, a sensible default height, and all required attributes.
- 4
Paste into your CMS or HTML
In WordPress, add an HTML block and paste. In Webflow, use an Embed element. In Squarespace, use a Code block. On a custom site, paste directly into your HTML file.
- 5
(Optional) Add the auto-resize script
Paste the auto-resize script immediately after the <iframe> tag to let the embed adjust its height as content changes. See the Auto-Resize section below.
Per-Product Reference
Each section below includes the iFrame code, recommended heights, and — where available — the Enterprise script embed.
Timeline
Timeline lets you tell any story chronologically — from breaking news to historical retrospectives — with rich media at every step.
Recommended height: 700 px
<iframe
id="timeline-abc123"
width="100%"
height="700px"
title="Breaking News Timeline"
src="https://embed.timepath.co/timeline/abc123"
frameborder="0"
scrolling="no"
allow="encrypted-media; clipboard-read; clipboard-write; fullscreen"
referrerpolicy="no-referrer-when-downgrade"
loading="lazy"
></iframe>Liveblog
Liveblog delivers real-time event coverage with automatic updates — ideal for elections, sports events, and breaking news.
Recommended heights:
- Vertical layout — 1000 px
- Horizontal layout — 800 px
<iframe
id="liveblog-def456"
width="100%"
height="1000px"
title="Election Night Liveblog"
src="https://embed.timepath.co/liveblog/def456"
frameborder="0"
scrolling="no"
allow="encrypted-media; clipboard-read; clipboard-write; fullscreen"
referrerpolicy="no-referrer-when-downgrade"
loading="lazy"
></iframe>Collection
Collection groups your Timepath content into a curated, browsable widget — great for topic hubs or editorial series.
Recommended height: 650 px
iFrame embed
<iframe
id="collection-ghi789"
width="100%"
height="650px"
title="Top Stories Collection"
src="https://embed.timepath.co/widget/ghi789"
frameborder="0"
scrolling="no"
allow="encrypted-media; clipboard-read; clipboard-write; fullscreen"
referrerpolicy="no-referrer-when-downgrade"
loading="lazy"
></iframe>Script embed Enterprise only
Step 1 — Place the container div where you want the collection to appear:
<div class="tp-collection" data-timepath-collection-id="{id}"></div>Step 2 — Add the loader script once per page (anywhere after the container, or in <head>):
<script>
(function () {
var SRC = "https://collection-script.timepath.co/timepath-collection.umd.js";
function mount() {
if (window.TimepathCollection && typeof window.TimepathCollection.mountAll === "function") {
window.TimepathCollection.mountAll({ apiBase: "https://embed.timepath.co" });
}
}
if (window.TimepathCollection) { mount(); return; }
if (document.querySelector('script[src="' + SRC + '"]')) {
var tries = 0, t = setInterval(function () {
tries++; if (window.TimepathCollection) { clearInterval(t); mount(); }
if (tries > 50) clearInterval(t);
}, 50); return;
}
var s = document.createElement("script"); s.src = SRC; s.onload = mount;
document.head.appendChild(s);
})();
</script>Quiz
Quiz engages readers with interactive knowledge tests and delivers detailed per-question analytics.
Recommended height: 700 px
Add approximately 100 px per answer option beyond the first two.
iFrame embed
<iframe
id="quiz-jkl012"
width="100%"
height="700px"
title="Weekly News Quiz"
src="https://embed.timepath.co/quiz/jkl012"
frameborder="0"
scrolling="no"
allow="encrypted-media; clipboard-read; clipboard-write; fullscreen"
referrerpolicy="no-referrer-when-downgrade"
loading="lazy"
></iframe>Script embed Enterprise only
Step 1 — Container div:
<div class="tp-quiz" data-timepath-quiz-id="{id}"></div>Step 2 — Loader script:
<script>
(function () {
var SRC = "https://quiz-script.timepath.co/timepath-quiz.umd.js";
function mount() {
if (window.TimepathQuiz && typeof window.TimepathQuiz.mountAll === "function") {
window.TimepathQuiz.mountAll({ apiBase: "https://embed.timepath.co" });
}
}
if (window.TimepathQuiz) { mount(); return; }
if (document.querySelector('script[src="' + SRC + '"]')) {
var tries = 0, t = setInterval(function () {
tries++; if (window.TimepathQuiz) { clearInterval(t); mount(); }
if (tries > 50) clearInterval(t);
}, 50); return;
}
var s = document.createElement("script"); s.src = SRC; s.onload = mount;
document.head.appendChild(s);
})();
</script>Poll
Poll collects audience votes on a single question with live results displayed to participants after voting.
Recommended height: 700 px
Add approximately 100 px per choice beyond the first two.
iFrame embed
<iframe
id="poll-mno345"
width="100%"
height="700px"
title="Readers Poll"
src="https://embed.timepath.co/poll/mno345"
frameborder="0"
scrolling="no"
allow="encrypted-media; clipboard-read; clipboard-write; fullscreen"
referrerpolicy="no-referrer-when-downgrade"
loading="lazy"
></iframe>Script embed Enterprise only
Step 1 — Container div:
<div class="tp-poll" data-timepath-poll-id="{id}"></div>Step 2 — Loader script:
<script>
(function () {
var SRC = "https://poll-script.timepath.co/timepath-poll.umd.js";
function mount() {
if (window.TimepathPoll && typeof window.TimepathPoll.mountAll === "function") {
window.TimepathPoll.mountAll({ apiBase: "https://embed.timepath.co" });
}
}
if (window.TimepathPoll) { mount(); return; }
if (document.querySelector('script[src="' + SRC + '"]')) {
var tries = 0, t = setInterval(function () {
tries++; if (window.TimepathPoll) { clearInterval(t); mount(); }
if (tries > 50) clearInterval(t);
}, 50); return;
}
var s = document.createElement("script"); s.src = SRC; s.onload = mount;
document.head.appendChild(s);
})();
</script>Survey
Survey collects structured reader responses across multiple questions — from open text to multiple choice — and aggregates results in real time.
Recommended height: 700 px
Add approximately 100 px per question beyond the first two.
iFrame embed
<iframe
id="survey-pqr678"
width="100%"
height="700px"
title="Reader Survey"
src="https://embed.timepath.co/survey/pqr678"
frameborder="0"
scrolling="no"
allow="encrypted-media; clipboard-read; clipboard-write; fullscreen"
referrerpolicy="no-referrer-when-downgrade"
loading="lazy"
></iframe>Script embed Enterprise only
Step 1 — Container div:
<div class="tp-survey" data-timepath-survey-id="{id}"></div>Step 2 — Loader script:
<script>
(function () {
var SRC = "https://survey-script.timepath.co/timepath-survey.umd.js";
function mount() {
if (window.TimepathSurvey && typeof window.TimepathSurvey.mountAll === "function") {
window.TimepathSurvey.mountAll({ apiBase: "https://embed.timepath.co" });
}
}
if (window.TimepathSurvey) { mount(); return; }
if (document.querySelector('script[src="' + SRC + '"]')) {
var tries = 0, t = setInterval(function () {
tries++; if (window.TimepathSurvey) { clearInterval(t); mount(); }
if (tries > 50) clearInterval(t);
}, 50); return;
}
var s = document.createElement("script"); s.src = SRC; s.onload = mount;
document.head.appendChild(s);
})();
</script>GeoStory
GeoStory places your narrative on an interactive map — readers explore locations, photos, and story beats spatially.
Recommended height: 600 px
iFrame embed
<iframe
id="geostory-stu901"
width="100%"
height="600px"
title="City Council Districts"
src="https://embed.timepath.co/geostory/stu901"
frameborder="0"
scrolling="no"
allow="encrypted-media; clipboard-read; clipboard-write; fullscreen"
referrerpolicy="no-referrer-when-downgrade"
loading="lazy"
></iframe>Script embed Enterprise only
Step 1 — Container div:
<div class="tp-geostory" data-timepath-geostory-id="{id}"></div>Step 2 — Loader script:
<script>
(function () {
var SRC = "https://geostory-script.timepath.co/timepath-geostory.umd.js";
function mount() {
if (window.TimepathGeoStory && typeof window.TimepathGeoStory.mountAll === "function") {
window.TimepathGeoStory.mountAll({ apiBase: "https://embed.timepath.co" });
}
}
if (window.TimepathGeoStory) { mount(); return; }
if (document.querySelector('script[src="' + SRC + '"]')) {
var tries = 0, t = setInterval(function () {
tries++; if (window.TimepathGeoStory) { clearInterval(t); mount(); }
if (tries > 50) clearInterval(t);
}, 50); return;
}
var s = document.createElement("script"); s.src = SRC; s.onload = mount;
document.head.appendChild(s);
})();
</script>DataStory
DataStory turns datasets into polished, interactive infographics that readers can explore at their own pace.
Recommended height: 600 px (minimum 300 px)
<iframe
id="datastory-vwx234"
width="100%"
height="600px"
title="Election Results Infographic"
src="https://embed.timepath.co/datastory/vwx234"
frameborder="0"
scrolling="no"
allow="encrypted-media; clipboard-read; clipboard-write; fullscreen"
referrerpolicy="no-referrer-when-downgrade"
loading="lazy"
></iframe>AI Modules
Not embeddable
AI Modules built inside the Timepath AI workspace are internal editorial tools — they are not designed to be embedded on external websites and have no public embed URL. If you are looking to add interactive content to your site, use one of the nine embeddable products listed above.
Dark Mode
All Timepath embeds support dark mode. How you enable it depends on the embed method you are using.
iFrame embeds — URL parameter
Append ?colorMode=dark to any embed src URL to force dark mode regardless of the visitor's OS setting:
src="https://embed.timepath.co/timeline/abc123?colorMode=dark"Script embeds — data attribute
Add the data-timepath-darkmode attribute to your container div. Accepted values:
"auto"— detect from the visitor's OS / browser preference (default)"true"— always render in dark mode"false"— always render in light mode
<div class="tp-quiz"
data-timepath-quiz-id="{id}"
data-timepath-darkmode="auto"
></div>Auto-Resize
By default, iFrame embeds have a fixed height. If your product content changes length (a growing liveblog, a quiz with many answer options), you can add the optional auto-resize script to let the embed adjust its height automatically.
The script listens for a postMessage event from the embed that carries the content height, then updates the iFrame's inline style. It uses requestAnimationFrame to batch updates and origin-checks every message for security.
Paste this script immediately after the </iframe> closing tag. Replace {product_id} with the same value you used for the iFrame's id attribute:
<script type="text/javascript">
(function () {
var FRAME_ORIGIN = "https://embed.timepath.co";
var FRAME_ID = "{product_id}";
var el = document.getElementById(FRAME_ID);
if (!el) return;
var raf = null;
function setHeight(px) {
if (raf) return;
raf = requestAnimationFrame(function () {
el.style.height = String(px) + "px";
raf = null;
});
}
function onMessage(e) {
if (!e || e.origin !== FRAME_ORIGIN) return;
var d = e.data && typeof e.data === "object" ? e.data : null;
if (!d) return;
var h = d.frameHeight;
if (typeof h === "number" && h > 0 && h < 100000) setHeight(h);
}
window.addEventListener("message", onMessage);
el.addEventListener("load", function () {
try {
el.contentWindow && el.contentWindow.postMessage(
{ parentUrl: window.location.href, widgetId: FRAME_ID, v: "2.0" },
FRAME_ORIGIN
);
} catch (err) {}
}, { once: true });
})();
</script>Multiple Embeds on One Page
You can embed as many Timepath products as you like on a single page. Each iFrame is independent — give each one a unique id attribute, and if you are using the auto-resize script, include one copy of the script per iFrame (with the matching FRAME_ID).
For script embeds, each product type uses its own global namespace (TimepathQuiz, TimepathPoll, etc.) and its own loader script. The loader scripts are safe to include more than once — each one checks whether the script is already loaded and skips the network request if it is. You can also mix iFrame and script embeds on the same page without any conflict.
There is no enforced limit on the number of embeds per page, but keep performance in mind — each embed loads its own resources. If you are embedding many products, consider placing them below the fold so they load lazily (the loading="lazy" attribute on iFrames enables this automatically in modern browsers).
FAQ
Need help? Visit the support centre or contact us.
SocialStory
SocialStory lets newsrooms design and publish social-media-style posts directly on their website — branded cards that match your editorial voice.
Recommended height: 800 px (minimum 400 px)