Embedding

Two ways to add the widget to your site: script tag or direct iframe.

Option 1: Script tag (recommended)

The simplest approach. One script tag handles iframe creation, theming, event relay, and auto-resizing.

<div id="bh-insurance-widget"></div>
<script
  src="https://cdn.benefithub.com/widget/v1/widget.js"
  data-bh-key="YOUR_KEY"
  data-bh-type="auto"
  data-bh-container="#bh-insurance-widget"
  data-bh-base-url="https://widget.benefithub.insure"
></script>

Available data attributes

Modal mode

Display the widget in a centered overlay instead of inline. With the script tag, set data-bh-mode="modal" — the modal opens automatically on page load:

<!-- Auto-open modal on page load -->
<script
  src="https://cdn.benefithub.com/widget/v1/widget.js"
  data-bh-key="YOUR_KEY"
  data-bh-type="auto"
  data-bh-mode="modal"
  data-bh-base-url="https://widget.benefithub.insure"
></script>

For a "click to open" pattern, use the SDK programmatically:

<button id="get-quote-btn">Get Insurance Quote</button>
<div id="bh-insurance-widget"></div>

<script src="https://cdn.benefithub.com/widget/v1/widget.js"></script>
<script>
  const widget = BHWidget.init({
    key: 'YOUR_KEY',
    type: 'auto',
    mode: 'modal',
    baseUrl: 'https://widget.benefithub.insure',
  });

  document.getElementById('get-quote-btn')
    .addEventListener('click', () => widget.open());
</script>

Modal features: close via ESC key, backdrop click, or the built-in X button. Body scroll is locked while the modal is open. See the SDK Reference for .open(), .close(), and .isOpen() methods.

Option 2: Direct iframe

If you prefer full control, embed the widget iframe directly. You handle sizing and event listening yourself.

<iframe
  src="https://widget.benefithub.insure/embed/auto?key=YOUR_KEY"
  style="width: 100%; min-height: 600px; border: none;"
  allow="geolocation"
  title="Insurance Quote"
></iframe>

iframe URL parameters

Security note: PII (name, email, phone) should not be passed as URL parameters — URLs appear in browser history, server logs, and referrer headers. The SDK sends prefill data securely via postMessage after the iframe loads. If you embed via direct iframe and need prefill, use the bh:prefill postMessage protocol (see Events).

Auto-resizing the iframe

The widget sends bh:resize postMessage events with the content height. Listen for them to prevent scrollbars:

window.addEventListener('message', (event) => {
  if (event.data?.type === 'bh:resize') {
    const iframe = document.querySelector('iframe');
    iframe.style.height = event.data.height + 'px';
  }
});

Server-managed settings

Some settings are managed by BenefitHub in the backend and cannot be set via embed attributes or URL parameters. These are configured during onboarding or by contacting your account manager.

Configuration priority

When both embed-level and server-managed values exist for the same setting (e.g., logo), the embed-level value wins:

1. Embed attributes / URL params (highest priority)
2. Server-managed client overrides (from database)
3. BenefitHub defaults (fallback)

Next steps

• Theming — customize every color and font
• Webhooks & Events — event reference