Using WordPress? Every integration here is also available as a plugin. Browse the plugin store →
Articles Embedding
Should an embedded third-party widget be an iframe, or a script that defines a custom element?
Choose an iframe when isolation matters more than integration — untrusted content, a separate origin, a hard security boundary. Choose a custom element when the widget has to behave like part of the page: inherit the layout, size to its content, participate in one focus order, and be readable by a screen reader as a single document.
A separate document with a separate origin, which is the strongest isolation the web platform offers. The host page's CSS cannot reach in, the widget's CSS cannot reach out, the JavaScript realms are distinct, and same-origin policy stops the frame reading the host's DOM or cookies. If the embedded content is untrusted, this is not a preference — it is the correct answer.
sandbox and a permissions policy the host constrains what the frame may do, and the frame cannot escalate.Everything that depends on the widget being part of the page — which, for an interactive widget, is more than people expect. The costs are individually small and collectively decisive.
postMessage resize channel and maintain it — and it will still be wrong for one frame after every content change.scroll-margin for a sticky header, and "scroll the page to this error" all stop working the way they do elsewhere.A real node in the page's own document. It takes part in normal layout, so it sizes to its content and reflows with the column it sits in. It shares one focus order with the rest of the page. Its headings join the page outline. A modal it opens can cover the viewport, because there is no rectangle to escape.
<script src="https://cdn.wpistatic.com/platform.js" async></script>
<wpi-bookings embed-key="YOUR_EMBED_KEY"></wpi-bookings>It also degrades in a more useful way. An element the browser does not recognise is an unknown element, not an error: it renders as an empty inline box until the script defines it, at which point it upgrades in place. There is no framework requirement on the host, and nothing to reconcile with the host's build tooling.
It does not, and the decision is a genuine trade rather than a formality. A shadow root gives style encapsulation that is nearly as strong as an iframe's while keeping the element in the page's layout and focus order. That is the textbook answer, and for most widgets it is the right one.
It stops being the right one when the widget's own UI library injects its styles into document.head. A CSS-in-JS engine that appends a <style> element to the head is emitting styles that do not cross a shadow boundary in either direction — so a component mounted in a shadow root renders unstyled. The WPIntegrate components hit exactly this: they are built on Fluent UI, whose Griffel engine inserts into document.head, so they render in the page's own DOM rather than in a shadow root.
The cost of that choice has to be stated rather than hidden: host-page CSS can reach the widget. What contains it is the library's own resets and generated class names, plus per-instance styling controls that let the widget be matched to the host deliberately instead of accidentally. If you are choosing a widget, this is a fair thing to ask a vendor — and a vendor who cannot tell you which one they use has not thought about your page.
| Iframe | Custom element | |
|---|---|---|
| Style isolation | Complete | Shadow root, or the library's own resets |
| Security boundary | Separate origin, sandboxable | Shares the page's origin and JS realm |
| Sizes to its content | No — fixed or postMessage | Yes, like any element |
| Popovers and modals | Clipped to the frame | Free of the page |
| Focus order | A separate document | One order with the page |
| Screen-reader outline | Announced separately | Part of the page outline |
| Inherits host theme | No, must be re-sent | Yes, and can be overridden |
One test cuts through most of the argument: would a reader be surprised to learn this section of the page came from somewhere else? If the honest answer is yes, it should not be an iframe.
Yes, for the host page — a frame is a separate origin, can be sandboxed, and cannot read the host's DOM or cookies. A custom element shares the page's origin and JavaScript realm, so embedding one is a statement of trust in the vendor, which is why the code should come from a host you have reason to trust.
Because an iframe does not size to its content — the parent sets its height, and the parent cannot see inside it. The frame has to measure itself and message the height out, which is a channel someone has to write, load and maintain on both sides.
Yes. A custom element is part of the HTML platform, so it works in plain HTML with no build step and inside every mainstream framework. That is the practical reason to prefer one for a widget distributed to sites you do not control.
No, and deliberately. They are built on Fluent UI, whose Griffel styling engine inserts its styles into document.head, and those styles do not cross a shadow boundary — so a shadow-mounted component would render unstyled. They render in the page's DOM instead, with Fluent's own resets and generated class names limiting what host CSS can disturb.
Embedding
Showing Microsoft 365 data to visitors who have no Microsoft account
Can a public website display SharePoint, Outlook or directory data to anonymous visitors?
Read the articleMicrosoft Graph
Managed or proxy: two ways to let a website read Microsoft 365
How does a public website read Microsoft 365 data without the vendor holding your Azure credentials?
Read the articleThese articles describe the general shape. Tenants differ, policies differ, and the interesting questions are the ones where the general shape does not fit.