Building an embeddable widget customers add to their websites
Short answer: For most SaaS widgets, such as a booking form, review feed or quote calculator, give customers a tiny script tag that creates an iframe pointing at your app. The iframe keeps your styles and code separate from theirs, so neither side breaks the other, and the small script handles resizing and options. Communicate between the page and the iframe with postMessage, always naming the exact origin you expect and checking the origin of what you receive. Load lazily, keep the script small, and version the embed code so you can update it without customers re-pasting anything.
The two basic approaches
Plain iframe
The customer pastes <iframe src="https://widgets.yourapp.com/book/abc123">. It's simple, works on nearly every website builder, and your page runs in its own isolated document: their CSS can't restyle your buttons, and your JavaScript can't conflict with their theme.
Downsides: iframes don't resize to their content on their own, so you get scrollbars or empty space, and it's harder to integrate with the host page, such as opening a full-screen dialog or reading a selected product.
Script that renders into the page
The customer pastes <script src="https://widgets.yourapp.com/embed.js" data-id="abc123"></script> and your script builds the widget directly in their page. It can blend in visually and size naturally.
Downsides: your code shares the page with theirs. Their CSS rules can reach your elements, global variables and library versions can clash, and a heavy or broken script slows or breaks their whole site, which they'll blame on you.
The common hybrid
A small loader script that inserts an iframe gives you both: easy installation, isolation, and a place to add resizing, lazy loading and options. Many established widgets work this way.
Talking between page and iframe safely
The loader and the iframe communicate with window.postMessage, for example the iframe reporting its height, or a "booking complete" event the host page can use for analytics.
MDN's documentation is direct about the security rules:
- When sending, provide a specific
targetOriginrather than*, if you know where the receiving document should be. With*, the message can be delivered to any origin, which could disclose data to a malicious site. - When receiving, always verify the sender using the message's
origin(and possiblysource), because any window can send messages. Then validate the message's content too.
In practice: the iframe sends height updates to the parent page's origin, which your loader passes in; the loader accepts messages only from your widget's origin and only in the shapes you expect.
Auto-resizing
The iframe measures its content (a ResizeObserver on its main container works well) and posts the height to the parent. The loader sets the iframe's height. Debounce updates so animations don't cause a flood of messages, and set a sensible minimum height so the widget never collapses to nothing.
Keep customers' pages fast
- Load the loader asynchronously and keep it very small.
- Lazy-load the iframe. MDN documents
loading="lazy"for iframes, which defers loading until the frame is near the viewport. Widgets below the fold shouldn't cost anything on page load. - Don't load large libraries in the loader. Do the heavy work inside the iframe.
- Cache aggressively with versioned file names for the iframe's assets.
Accessibility and appearance
Give the iframe a meaningful title (MDN's iframe examples include one), which screen readers announce. Make sure keyboard users can move into and out of the widget, and offer options such as colour, font and language through data attributes, so customers can match their site without touching code.
Things that trip widgets up
- Cookies inside iframes. Browsers increasingly block or partition third-party cookies, so a login inside your iframe may not persist on a customer's site. Design widgets to work without relying on them, or open a full window for sign-in.
- Content Security Policy. Some customer sites restrict which scripts and frames can load. Document the domains your widget uses so their developer can allow them.
- Website builders sometimes strip script tags in certain blocks. Offer the plain iframe as a fallback and step-by-step instructions for the common builders.
- Sandboxing. If customers add a
sandboxattribute, MDN notes it applies all restrictions unless specific permissions are listed; document which ones your widget needs, such as scripts, forms and pop-ups.
Give customers a test page
Publish a simple page showing the widget embedded with each option, plus copy-ready snippets for the common website builders. Support questions drop sharply when customers can see exactly what a working install looks like, and your own team can use the same page to check every release before it goes out.
Version and monitor
Keep the embed code stable and do updates behind it: the loader at a fixed URL fetches the current widget version. Log which customer domains load the widget and watch for errors per domain, so you notice when a site redesign breaks an embed before the customer does.
A worked example
An illustrative Adelaide booking SaaS first offered a script that rendered its form straight into customers' pages. Customers kept reporting oddly styled buttons and conflicts with their themes. The team switched to a small loader that inserts a lazy-loaded iframe, uses postMessage with fixed origins for height and "booking completed" events, and accepts colour and language via data attributes. Styling complaints stopped, and customers who wanted conversion tracking listened for the completed event.
FAQ
Is an iframe bad for SEO?
Content inside the iframe is generally associated with your domain, not the customer's page. For booking forms, that's rarely a concern.
Can the widget read data from the customer's page?
Only what the loader passes in. Keep it to what you need.
Should I offer a WordPress plugin too?
It helps non-technical customers, but keep the embed code as the standard method.
How do I handle customers on old embed versions?
Keep the loader URL stable and backwards compatible, and update behind it.
If you're planning a widget customers can embed, tell us what it needs to do and we'll help you choose an approach that won't break their sites.