Embeddable pedigree viewer: iframe, SVG, and JavaScript snippet

Short version. Evagene's embeddable pedigree viewer ships in three modes. The iframe mode embeds a self-contained HTML viewer with interactivity (zoom, pan, individual focus). The raw SVG mode exposes the pedigree as a static SVG file usable in any img, object, or inline context. The JavaScript snippet mode discovers data-evagene-pedigree attributes on your page and renders SVG inline so the pedigree is part of your DOM. Authentication is via API key held by your server, or by marking a specific pedigree as public. CSP, frame-ancestors, and Referrer-Policy are under your control. Use the iframe for interactive views in patient portals and EHR embeds, raw SVG for lightweight display and print, and the JavaScript snippet for research dashboards where the pedigree participates in page-level styling.

This page walks through each mode, the trade-offs, and the security considerations — with honest notes about when to reach for each.

Why three modes?

Clinical pedigree diagrams get embedded into very different contexts. A patient portal wants an interactive view with hover labels and zoom; a publishing pipeline wants a static SVG it can drop into a PDF; a research dashboard wants inline SVG it can style with its own CSS and annotate alongside charts. One embed shape does not fit all of these. Evagene therefore ships three:

• iframe — an isolated viewer loaded from Evagene's domain with its own JavaScript, rendering logic, and interactive controls.
• raw SVG — a plain SVG file served from an Evagene endpoint, usable anywhere SVG is usable.
• JavaScript snippet — a small script you include once per page; it scans for data-evagene-pedigree attributes and inlines the corresponding SVG.

All three render the same clinical notation (NSGC-style symbols, affected status, deceased markers, proband arrow, consanguinity loops) so the visual output is consistent regardless of the mode your integration uses.

Mode 1: iframe embed

The iframe is the most common choice for user-facing embeds. It isolates the viewer's script context from the hosting page, which is desirable both for stability and for defence-in-depth.

<iframe
  src="https://evagene.com/embed/pedigree/ped_9f2b...?api_key=evg_xxx&theme=light"
  width="100%"
  height="560"
  frameborder="0"
  loading="lazy"
  sandbox="allow-scripts allow-same-origin">
</iframe>

Design notes:

• In production, do not put the API key in the browser. Your server generates a short-lived signed URL or holds the key and proxies the request, so the browser sees only an opaque viewer URL.
• Set sandbox attributes deliberately. For a read-only viewer in a patient portal, allow-scripts allow-same-origin is typical; omit allow-top-navigation and allow-popups unless you need them.
• Use loading="lazy" for below-the-fold embeds to reduce initial page weight.

Mode 2: raw SVG

For pipelines that need a static image — PDFs, print reports, research figures, email summaries — the raw SVG endpoint returns the pedigree as an SVG file you can embed directly.

<!-- Inline SVG from a server-rendered HTML page: -->
<img src="https://evagene.com/embed/pedigree/ped_9f2b.../svg?theme=light"
     alt="Family pedigree" />

<!-- Or as an object that preserves SVG scalability: -->
<object type="image/svg+xml"
        data="https://evagene.com/embed/pedigree/ped_9f2b.../svg"></object>

Design notes:

• The SVG endpoint authenticates via API key too. For public research figures, mark the pedigree as public and drop the authentication entirely.
• SVG is vector: it prints cleanly and scales to any size without degradation, which matters for clinical reports.
• Use object or iframe if you want the SVG's internal CSS to apply fully; use img if you want CSS isolation and a simpler element.

Mode 3: JavaScript snippet

The snippet mode is for pages that want the pedigree to live inside the page's DOM — for example, a research dashboard that overlays annotations, or a page that wants the pedigree to participate in the page's own theme and CSS variables.

<!-- Once per page: -->
<script src="https://evagene.com/embed.js" async></script>

<!-- Anywhere on the page: -->
<div data-evagene-pedigree="ped_9f2b..."
     data-evagene-api-key="evg_xxx"
     data-evagene-theme="light"></div>

Design notes:

• In production the data-evagene-api-key is server-injected after the host page has verified the current user's access to that pedigree — do not hard-code it in static HTML.
• The snippet inlines SVG, so the pedigree is part of your page's DOM and your CSS can reach it (with the obvious caveat that deep styling changes to clinical notation are rarely a good idea).
• Initial paint is slightly later than the iframe mode because of the additional script parse step.

Worked patterns

Patient portal family-history tab

A patient portal adds a "Family History" tab showing the pedigree the genetics service has constructed. The portal's backend holds the Evagene API key, generates a signed short-lived iframe URL when the patient opens the tab, and renders it. The patient sees the pedigree but never sees the key or an Evagene login. When the clinician updates the pedigree, Evagene fires pedigree.updated; the portal invalidates the tab's cache so the next load shows the updated state.

Research dashboard

A research group builds a Streamlit-style dashboard showing pedigree plots next to variant tables. The dashboard uses the JavaScript snippet mode so each pedigree is inline SVG, styled to match the dashboard's dark theme, and can be annotated with the dashboard's own overlays. Pedigrees are batch-loaded via the REST API; the embed is purely for display.

EHR-lite web-content embed

A clinical service without a full EHR integration budget embeds the iframe viewer inside an Epic hyperspace web-content frame or Oracle Health equivalent. See EHR pedigree integration for the end-to-end pattern and governance considerations.

Print and PDF reports

A reporting pipeline generates clinical letters in PDF. At generation time, the pipeline fetches the raw SVG for each pedigree and drops it into the PDF using an SVG-aware renderer. The result is a crisp, vector pedigree on the letter rather than a rasterised screenshot.

Security considerations

Embedding a clinical diagram on a third-party page is a classic cross-origin problem. Evagene gives you the primitives; your integration owns the policy.

• Content Security Policy. Configure frame-src to allow Evagene's embed host only; configure frame-ancestors on Evagene's response headers (via deployment config) to allow only your host domains.
• Referrer-Policy. Use strict-origin-when-cross-origin or no-referrer when embedding into patient-facing contexts so pedigree IDs do not leak via referrer headers.
• API key handling. Never expose a write- or analyse-scope key to the browser. Use a read-scope key for embed, and hold it server-side. Consider rotating keys regularly and using IP allow-lists on the Evagene side.
• Sandboxing. For the iframe mode, use the sandbox attribute with the minimum capabilities needed.
• Audit. Evagene logs API-key usage; your integration should log embed serve events on its side so you can correlate and investigate.

How this works in Evagene

The viewer is an API client: it calls the pedigree REST API with a read-scope key to fetch the pedigree's individuals and relationships, then renders standard clinical notation. Authentication and scope-checking are handled on the API side, so the viewer's behaviour is consistent across modes. Public pedigrees skip auth entirely — useful for demos and published research figures.

Pedigree data flowing into Evagene (via GEDCOM import, 23andMe, or image OCR), analysis output (BRCAPRO, MMRpro, PancPRO, Mendelian, AI interpretation), and annotation changes all flow back out through the same viewer automatically. If an MCP-driven AI agent modifies the pedigree, the next viewer load reflects the change.

Frequently asked questions

Related reading

• Evagene platform overview
• Pedigree REST API reference
• EHR pedigree integration patterns
• HL7 FHIR and pedigree data
• Pedigree MCP server for AI agents
• Phenotips vs Evagene