Embed documentation

Which way in

Same widget and same terms in all four cases. Pick by what your publishing tool lets you paste.

The one-line script

One request, roughly 2 KB compressed, no dependencies and no build step. It writes the iframe, sizes it, and adds the credit line where the script tag stands. Several widgets can share a page: the loader installs one message listener however many tags it finds, and matches each height message to the window that sent it.

<script src="https://farbetteroff.com/embed.js" data-calculator="mortgage-calculator" data-title="Mortgage Calculator" data-height="2600"></script>

Its attributes

Any other data-* attribute is read as a starting value for the calculator field of that name — the reference below lists all 188 of them.

Those 8 names are the loader’s own settings, so they are the 8 names a calculator field can never have. None of the 188 fields does, and a build-time check keeps it that way.

The iframe

The widget lives at https://farbetteroff.com/embed/<slug>, and that URL is the whole API: ?theme= pins the theme, and any field name sets a starting value. It is a normal page, so you can open it in a tab to see exactly what your readers will get.

<iframe id="calcwise-mortgage-calculator" src="https://farbetteroff.com/embed/mortgage-calculator" title="Mortgage Calculator by Far Better Off" width="100%" height="2600" frameborder="0" style="border:0;max-width:600px;width:100%" loading="lazy"></iframe>
<script>window.addEventListener("message",function(e){if(e&&e.data&&e.data.type==="cw-embed-height"&&e.data.slug==="mortgage-calculator"){var f=document.getElementById("calcwise-mortgage-calculator");if(f){f.style.height=e.data.height+"px"}}});</script>
<p style="font:13px/1.4 system-ui,sans-serif;text-align:center;margin:6px 0">Powered by <a href="https://farbetteroff.com/calculators/mortgage-calculator" target="_blank" rel="noopener">Far Better Off</a></p>

The <p>with the credit link sits in your HTML rather than inside the frame, deliberately: a link inside an iframe is not a link to your readers’ search engines, and the credit is the whole price of the widget. The <script> is what resizes the frame; without it the widget works but stays at its starting height.

Sizing, and the height message

A calculator changes height as a reader uses it — open the amortization table and it grows by a thousand pixels. Rather than guess, the widget measures itself and tells the host page, which is the only way to avoid both an inner scrollbar and a page of empty space.

Wiring it up yourself

If you are building the host side — a React component, a Vue wrapper, a template partial — this is all of it.

<iframe id="calc" src="https://farbetteroff.com/embed/mortgage-calculator"
        title="Mortgage Calculator by Far Better Off" width="100%" height="2600"
        frameborder="0" style="border:0;max-width:600px;width:100%" loading="lazy"></iframe>
<script>
window.addEventListener("message", function (e) {
  // Check the origin first: any page can post a message to yours.
  if (e.origin !== "https://farbetteroff.com") return;
  var m = e.data;
  if (!m || m.type !== "cw-embed-height") return;
  var frame = document.getElementById("calc");
  // Matching on e.source rather than on m.slug lets two copies of the same
  // calculator share a page without resizing each other.
  if (frame && frame.contentWindow === e.source) {
    frame.style.height = Math.round(m.height) + "px";
  }
});
</script>

Theming

Left alone, the widget follows each reader’s own device setting, so it looks right on a dark site and a light one without you choosing. ?theme=light or ?theme=dark on the embed URL (data-theme on the loader) pins it instead, for a site whose design is one or the other regardless of the reader.

A pinned theme is applied before the first paint, so there is no flash of the other one. Anything other than light or dark — including a typo — leaves the reader in charge rather than failing.

oEmbed

Every calculator page, every embed URL and every /rates, /money-numbers page advertises an oEmbed endpoint, so a platform that runs discovery can resolve a pasted Far Better Off link with nothing copied. What it does with the answer is its own decision, and a platform that has never heard of us usually trims it — the three sections below say exactly what WordPress, Discourse and Ghost each render, read off their source. The endpoint is https://farbetteroff.com/api/oembed, it answers json and xml, and it returns a rich response whose html is the same markup as the iframe snippet above.

curl "https://farbetteroff.com/api/oembed?url=https://farbetteroff.com/calculators/mortgage-calculator"

It accepts the spec’s maxwidth and maxheightas ceilings, passes a pasted link’s theme and field values through into the widget, and drops anything else (so a tracking parameter on a shared link can’t ride along). For a calculator it also hands back a thumbnail that is a picture of the answer rather than a logo. Some platforms only allow providers on a public list; if yours asks, the provider name is Far Better Off and the endpoint is the URL above.

Live-data pages resolve too

The live-data pages below are the URL a reader would actually have in their clipboard, so they resolve the same way a calculator page does — paste it and a platform that runs discovery renders the widget instead of the link. The response carries a thumbnail_url too — the same card the page shares, served from https://farbetteroff.com/og/rates, a URL that stays put across deploys and refreshes on the widget’s own six-hour timer, so a consumer that shows a picture rather than the widget gets today’s figures instead of a logo.

curl "https://farbetteroff.com/api/oembed?url=https://farbetteroff.com/rates"

What WordPress does with it

Worth knowing before you paste, because WordPress rewrites what it gets back from any provider that isn’t on its own list. Its wp_filter_oembed_result() keeps the <iframe> and discards everything around it, allows eight attributes on it (src, width, height, frameborder, marginwidth, marginheight, scrolling, title) and adds sandbox="allow-scripts". So the resize listener and the credit line are gone and the widget stands at the measured height this endpoint returns — it still calculates, and its own links still work, but nothing on the host page says where it came from. The free WordPress plugin registers Far Better Off as a provider, and a registered provider’s markup is passed through untouched: auto-height and credit line intact.

What Discourse does with it

A forum renders a provider’s own oEmbed markup only when the iframe’s address matches its allowed_iframessetting, which ships with six entries (Google Maps, OpenStreetMap, Google Calendar, CodePen, Instagram, Spotify). So on a forum that hasn’t been told about us, a pasted link is a onebox link preview — the calculator’s title, description and result image, with a link back — not the widget. An admin turns it into the widget in one line: Settings → Posting → allowed_iframes, add https://farbetteroff.com/embed/. Discourse then keeps more of the snippet than WordPress does: the “Powered by Far Better Off” line survives its sanitizer, and its sandbox allows the widget’s own links to open. The resize script doesn’t survive, so the widget stands at the measured height this endpoint returns.

What Ghost does with it

Ghost 6.34 and later ignores the htmlfrom any provider not on its built-in list — “an arbitrary site’s self-declared oEmbed endpoint, which we must not trust” — and renders a bookmark cardinstead: the calculator’s title, description, share image and a link back. That is Ghost’s decision and nothing we publish changes it. On Ghost 6.33 and earlier the same paste becomes the widget. To put the calculator itself on a current Ghost site, use the iframe or the one-line script above in an HTML card — both work, and both keep the credit line and the auto-height.

What the widget does to your page

The short version: nothing you didn’t ask for. The longer version, because “no tracking” is a claim worth spelling out:

If your site runs a Content Security Policy, this is all it needs:

Content-Security-Policy:
  frame-src  https://farbetteroff.com;
  script-src https://farbetteroff.com;   /* only if you use the one-line loader */

When something looks wrong

Terms, in full

• • Free for any site, commercial or not. No account, no key, no application, no usage limit, and nothing to renew.
• • Keep the “Powered by Far Better Off” link that comes with the code. That link is what pays for all of this.
• • The calculators are educational tools, not financial advice, and some are deliberately narrower than they look: the paycheck calculator is federal-only, and house affordability and rent-vs-buy leave out PMI. Each calculator page states its own assumptions — worth a look before you put one in front of your readers.
• • The loader is MIT licensed, so you are welcome to host your own copy of /embed.js rather than load ours.