Embed API reference

Three ways to embed Zeitful

There are three integration paths, in decreasing order of how common they are. Pick the first one that fits your context; you do not need to mix them.

1. iframe embed — the standard path. One <iframe> tag pointing at /embed/[tool]. Works in almost every CMS and intranet that allows HTML. Free, with a single visible attribution link below the widget.
2. Direct link with brand attribution — for contexts where you cannot embed at all (email newsletters, printed material, slide decks). Link directly to the tool at zeitful.com/tools/[slug] with a short "Time tool by Zeitful" line. Common in newsletters that ship plain HTML.
3. Hosted PRO (white-label) — the embed without the attribution link, served from a custom subdomain. Coming soon. Join the waitlist from the embed gallery.

Quick start

Paste this snippet anywhere HTML is allowed. It renders a live world clock for London and New York that updates every second.

<iframe src="https://zeitful.com/embed/world-clock?cities=London,New%20York"
        style="width:100%;height:480px;border:0" loading="lazy"></iframe>
<p style="font:13px/1.4 system-ui,sans-serif;color:#6b7280;text-align:right;margin-top:6px">
  Powered by <a href="https://zeitful.com/tools/world-clock">Zeitful</a>
</p>

The attribution paragraph below the iframe is required (see Attribution). For an interactive snippet builder that lets you preview before copying, use the embed gallery — every tool page also exposes a builder via the "Embed this" button in the header.

URL parameters by tool

Each tool accepts a set of URL parameters that pre-configure its initial state. All parameters are optional; omitting them falls back to sensible defaults. Unknown or malformed values are dropped silently rather than throwing — the embed always renders.

Parameters marked planned are intended interfaces that ship in a later wave. The shape will not change once stable, so it is safe to write the snippet against them today and have it activate when the feature lands. Parameters marked beta may change before reaching stable.

Sizing and responsive layout

Every embed assumes width: 100% of its container. Set the height explicitly. The defaults below come from lib/embed/snippet.ts and are the heights the embed builder uses unless you override them.

If you go below the minimum, the widget keeps rendering but starts clipping. Above the recommended height the widget centres in the iframe and leaves dead space — no visual harm, but you are wasting screen real estate. The shared snippet generator in lib/embed/snippet.ts defaults to 520 px when nothing is specified.

Aspect ratio. None of the embeds have a fixed aspect ratio. They are content-first: pass any width, choose a height that suits the page, the internal layout adapts. If you need a 16:9 frame for slide-style decks, wrap the iframe in your own aspect-ratio container — do not try to fight the embed.

Mobile breakpoint. Most embeds switch to a single-column layout around 480 px. The world clock and converter add a horizontal scroll for overflow rather than truncating. The meeting scheduler keeps the heatmap visible but horizontally scrollable. If your page renders inside a phone-width column (under 400 px), drop the height by 60–80 px from the recommended values above.

Theming

Pass ?theme= to switch the colour palette. Three themes are supported:

• ?theme=light — default. Neutral surfaces, ink-grey text. Best on white or near-white parent pages.
• ?theme=dark — inverted. Near-black surfaces, off-white text. Best on dark parent pages or in apps with a system-driven dark mode.
• ?theme=sepia — warm paper. Cream surfaces, slate text. Pairs with editorial and reading-focused parent contexts.

Theming is implemented via CSS custom properties on the iframe's root element. Each theme remaps the same token set so component code is theme-agnostic. The mapping is fixed and not editable from outside the iframe — that is what the themes are for. If none of the three fits your site, link out instead of embedding, or wait for the white-label PRO tier.

Status: the ?theme= parameter is documented here as the planned interface. Light is the only theme shipping today. Dark and sepia ship in a follow-up wave. Snippets that include the param today will silently fall back to light until the themes activate, so it is safe to write against this interface now.

Attribution requirement

Every embed must include one visible dofollow link back to zeitful.com/tools/[slug]. This is the entire business model of the free embed tier. If the attribution disappears, the embed loses its only contribution path back to the source.

Acceptable forms.

• Small text link below the iframe, like the example in the Quick start section.
• A "Powered by Zeitful" badge in the host page's footer, provided the embed itself is on that page.
• The Zeitful wordmark, sized so the link is legible at body-text size.

Not acceptable.

• Hiding the link with CSS (display: none, zero opacity, off-screen positioning).
• Putting the attribution only in an HTML comment or in the page source.
• Wrapping the link in rel="nofollow" or rel="noreferrer". The link must be dofollow.
• Routing the link through a redirector that strips referer or attribution.

If you genuinely cannot ship a visible attribution link (white-label intranet, app store reviewer guidelines, contractual restriction), use the PRO tier when it ships. Until then, link out to the tool instead of embedding.

postMessage protocol (optional)

For embedders who want to react to events inside the widget — analytics, conversion tracking, parent-window state sync — Zeitful will emit window.postMessage events from the iframe. The protocol is small, additive, and tied to the URL params so you can rely on stable shapes.

Status: postMessage events are not shipped yet. The shapes below are the planned interface and will not change once they land. Write your listener now and it activates the moment the first event fires.

Planned events:

• timekit:loaded — fires once when the embed has hydrated and is interactive. Payload: { tool: string, version: string }.
• timekit:converted — for the converter and meeting scheduler. Fires when the user changes the pivot time or zone. Payload: { tool, pivot, zones, time }.
• timekit:countdown-complete — fires once when the countdown hits zero. Payload: { tool: "countdown-maker", target: string }.
• timekit:resize — debounced; fires when the embed's preferred height changes (e.g. user adds a city). Payload: { height: number }. Useful if you want to dynamically size the iframe.

Pattern for the listener:

window.addEventListener('message', (event) => {
  // Always check the origin to prevent spoofing.
  if (event.origin !== 'https://zeitful.com') return;
  const data = event.data;
  if (!data || typeof data !== 'object') return;

  switch (data.type) {
    case 'timekit:loaded':
      // The embed is ready. Hide your loading skeleton.
      break;
    case 'timekit:converted':
      // The user changed the pivot. Mirror into your analytics if you want.
      break;
    case 'timekit:countdown-complete':
      // Fire a confetti animation, redirect, whatever the moment calls for.
      break;
    case 'timekit:resize':
      // Resize the iframe if you opted into dynamic height.
      // const iframe = document.querySelector('iframe[data-Zeitful]');
      // if (iframe) iframe.style.height = data.height + 'px';
      break;
  }
});

The origin check is mandatory. Anyone can post a message to your window claiming to be Zeitful; only events from the Zeitful origin should be trusted.

Brand guidelines for embedders

Short and unambiguous because the attribution link is the only place embedders interact with the brand.

• Wordmark. The brand is Zeitful, capital Z and the rest lowercase. Not ZEITFUL, not zeitful. The attribution snippet ships with the correct casing, so leave it alone.
• Approved attribution text. "Powered by Zeitful", "Time tool by Zeitful", or "via Zeitful". All three are fine. "Powered by Zeitful" is the default.
• Disallowed wording. Do not invent variants like "sponsored by Zeitful" or "in partnership with Zeitful", neither is accurate. Do not omit the link, even in compact contexts.
• Logo. Wordmark and bug downloads are at /brand/assets (coming soon). Until then, use the text wordmark in the attribution snippet.
• Colour. The embed's internal palette is controlled via the ?theme= parameter. Do not override it with CSS injection or by wrapping the iframe in a stylesheet that targets its descendants — most browsers block this anyway because of cross-origin isolation, but trying to defeat that also violates these guidelines.

Common embedding platforms

Quick how-tos for the platforms we get the most embed traffic from. If your CMS is not listed and the iframe snippet does not just work, the most likely culprit is the platform stripping the <iframe> tag for security. Look for an "HTML", "embed", or "code" block type explicitly.

Changelog and stability

The promises behind the URL params, in plain language:

• Stable params do not break without notice. Any param documented on this page without a beta or planned tag is stable. Breaking changes ship with a 90-day deprecation notice in the Zeitful newsletter, in the changelog at the bottom of this page, and via a console warning in the iframe itself for the deprecation window.
• Beta params can change. Anything tagged beta is shipping but may change shape, get renamed, or be removed before stable. Use them if you want, but pin the snippet revision somewhere your team can find it.
• Planned params are tomorrow's stable params. Anything tagged planned describes an interface that has been designed but not yet shipped. The shape will not change once it lands. It is safe to write the snippet against it today; the param will be ignored until the feature activates, then take effect on the next iframe load.
• Breaking changes are announced. The Zeitful newsletter is the only channel where deprecations are guaranteed to land. The changelog below is the canonical history.

Changelog

• 2026-05-29. Embed API reference published. Documents every URL param across the six headline embeds, the sizing table, the planned theming and postMessage interfaces, and the brand and attribution rules.