Troubleshooting

Solutions to common issues when embedding and configuring widgets.

Widget not appearing

The embed code is on the page but nothing renders.

  • Confirm the script tag is inside the <body>, not the <head>
  • Check the browser console (F12) for JavaScript errors
  • Verify the widget ID is correct — copy it fresh from the dashboard
  • Some platforms (Notion, certain WordPress plugins) block external scripts. Try the iframe embed instead
  • Ensure your page isn’t blocking third-party scripts via Content Security Policy (CSP)

Widget appears but looks broken

The widget renders but styling is off or elements are misaligned.

  • If using inline embed, check for CSS conflicts from your site’s stylesheets. Common culprits: global * selectors, aggressive CSS resets, or !important rules on common properties
  • Switch to iframe embed for full style isolation
  • Clear your browser cache and hard-refresh (Ctrl+Shift+R / Cmd+Shift+R)
  • If using custom CSS, temporarily remove it to see if the issue is in your overrides

Changes not reflecting

You updated the widget in the editor but the live version hasn’t changed.

  • Changes propagate within seconds. Hard-refresh the page with the embed
  • Check if your site uses aggressive caching (CDN, service workers, or browser cache)
  • Verify you’re editing the correct widget instance in the dashboard

Widget loads slowly

The widget takes noticeably long to appear.

  • Inline embeds are the fastest option — switch from iframe if possible
  • Add loading="lazy" to iframe embeds so they load when scrolled into view
  • Check your own site’s load time — widget performance depends on the host page loading the script
  • Our CDN serves from 180+ locations globally. If you’re seeing slow loads, check your network connection

Iframe sizing issues

The iframe is too small, too large, or has scrollbars.

  • Set explicit width and height attributes on the iframe
  • For responsive behavior, wrap in a container:
<div style="width: 100%; max-width: 500px;">
  <iframe
    src="https://embed.widget.best/your-widget-id"
    width="100%"
    height="400"
    frameborder="0">
  </iframe>
</div>
  • Remove frameborder if you see an unwanted border around the iframe

Dark mode not working

The widget doesn’t switch themes with your site.

  • Widgets detect dark mode via the prefers-color-scheme CSS media query (system preference)
  • If your site uses a manual theme toggle, the widget may not detect it
  • You can lock the widget to a specific theme (light or dark) in the editor settings

The popup launcher button doesn’t appear or doesn’t open.

  • Popup mode is only available on Form and Document Chat widgets
  • Ensure data-mode="popup" is set on the script tag
  • Check for z-index conflicts — another element on your page may be covering the launcher
  • Try removing other floating elements temporarily to isolate the issue

Form submissions not saving

Users submit the form but no data appears in the dashboard.

  • Check that required fields are properly configured — submissions with missing required fields are rejected
  • Verify file upload size limits haven’t been exceeded
  • Check the browser console for network errors during submission

Still stuck?

  • Check the browser console for error messages — they often contain the specific issue
  • Try the embed on a plain HTML page to isolate whether the issue is with your site or the widget
  • Reach out via the community support channel (Free) or priority support (Pro)