Merge pull request #290 from DomoApps/users/jon.tiritilli/embed-component

feat: add DomoEmbed snippet component

Author: JaredPeterson-Domo

Domo-KB-Style-Guide.mdx

@@ -357,6 +357,38 @@ Wrap a YouTube (or other host) embed `<iframe>` in a `<Frame>`. Use the host's s
 
 Always include a descriptive `title` attribute — screen readers announce it, and it's what appears if the embed fails to load.
 
+## Embedded Domo Content
+
+Use the `DomoEmbed` snippet to embed live Domo content—dashboards, pages, or cards—directly inside a documentation article. Unlike a screenshot or video, an embedded view reflects current data and lets readers interact with it in context.
+
+The component handles sizing automatically: Domo's embed runtime sends a `postMessage` with the rendered page height, and `DomoEmbed` updates the iframe height accordingly, preventing scroll traps and double scrollbars.
+
+**When to use:** Reserve `DomoEmbed` for situations where live, interactive Domo content adds genuine value—a product overview, a walkthrough that references a live dashboard, or a reference page that benefits from real data context. For static illustration, a screenshot is simpler and more reliable.
+
+### Import and Use
+
+Add the import directly below the frontmatter (alongside any other imports):
+
+```mdx
+import { DomoEmbed } from '/snippets/DomoEmbed.mdx';
+```
+
+Then place the component wherever the embed should appear:
+
+```mdx
+<DomoEmbed src="https://embed.domo.com/embed/pages/XXXXX" />
+```
+
+Three props are available:
+
+| Prop            | Required | Default  | Description                                         |
+| --------------- | -------- | -------- | --------------------------------------------------- |
+| `src`           | Yes      | —        | The Domo embed URL (cards or pages endpoint).       |
+| `width`         | No       | `"100%"` | CSS width of the iframe.                            |
+| `initialHeight` | No       | `"600"`  | Starting height in pixels before auto-resize fires. |
+
+<Note>**Note:** The Domo instance that hosts the embed must allow your documentation domain in its embed allowlist. If the iframe appears blank, check the source instance's CSP / embed allowlist settings.</Note>
+
 ## Callouts
 
 Use React callout elements for notes, warnings, and tips — not plain text or HTML. Always bold the label and its colon, for example `**Note:**`.

New-Article-Template.mdx

@@ -29,6 +29,30 @@ article). Do not repeat it under additional beta sections.
 
 Do not append `(Beta)` or `(BETA)` to titles or headings — the tag and Badge
 carry that signal. See Domo-KB-Style-Guide.mdx › Beta Features for details.
+
+---
+
+EMBEDDED DOMO CONTENT
+
+---
+
+To embed live Domo content (a dashboard or card) in an article, add this import
+on its own line directly below the frontmatter above:
+
+  import { DomoEmbed } from '/snippets/DomoEmbed.mdx';
+
+Then place the component wherever the embed should appear:
+
+  <DomoEmbed
+    src="https://embed.domo.com/embed/pages/XXXXX"
+    width="100%"
+    initialHeight="600"
+  />
+
+The src prop (required) is the Domo embed URL. width and initialHeight are
+optional and default to "100%" and "600" respectively. See
+Domo-KB-Style-Guide.mdx › Embedded Domo Content for the full prop reference
+and usage guidelines.
 */}
 
 ## Intro

snippets/DomoEmbed.mdx

@@ -0,0 +1,69 @@
+{/*
+  DomoEmbed — reusable component for embedding Domo-hosted content in MDX pages.
+
+  USAGE
+  -----
+  Import and drop into any MDX page:
+
+    import { DomoEmbed } from "/snippets/DomoEmbed.mdx";
+
+    <DomoEmbed
+      src="https://embed.domo.com/embed/pages/XXXXX"
+      width="100%"
+      initialHeight="600"
+    />
+
+  PROPS
+  -----
+  src            (required) — The Domo embed URL (cards or pages endpoint).
+  width          (optional) — CSS width of the iframe. Defaults to "100%".
+  initialHeight  (optional) — Starting height in pixels before auto-resize fires. Defaults to "600".
+
+  AUTO-RESIZE
+  -----------
+  Domo's embed runtime sends a postMessage event containing the rendered page height.
+  This component listens for that message and updates the iframe height automatically,
+  eliminating scroll traps and double scrollbars. A 15px buffer is added to account
+  for sub-pixel rounding and scrollbar gutter width.
+
+  For the underlying mechanism and plain-HTML equivalents, see:
+  /portal/embed/embed-in-sites-and-apps/dynamic-iframe-height
+
+  NOTE: The embed URL must come from a Domo instance that allows embedding on this domain.
+  If the iframe appears blank, check the source instance's CSP / embed allowlist settings.
+*/}
+
+import { useEffect, useRef } from "react";
+
+export const DomoEmbed = ({ src, width = "100%", initialHeight = "600" }) => {
+  const iframeRef = useRef(null);
+
+  useEffect(() => {
+    function handleMessage(event) {
+      if (
+        iframeRef.current &&
+        iframeRef.current.contentWindow === event.source &&
+        event.data &&
+        event.data.params &&
+        event.data.params.height
+      ) {
+        iframeRef.current.style.height = event.data.params.height + 15 + "px";
+      }
+    }
+    window.addEventListener("message", handleMessage);
+    return () => window.removeEventListener("message", handleMessage);
+  }, []);
+
+  return (
+    <iframe
+      ref={iframeRef}
+      src={src}
+      width={width}
+      height={initialHeight}
+      marginHeight="0"
+      marginWidth="0"
+      frameBorder="0"
+      style={{ display: "block" }}
+    />
+  );
+};