Troubleshoot widget embed issues

Diagnose and fix common problems with KudosWall widget embeds — missing widgets, empty states, broken styles, CSP errors, and more.

If your KudosWall widget isn’t displaying correctly, work through the issues below in order. Most problems fall into one of a handful of common categories.

If you’re still stuck after checking these steps, contact KudosWall support from the dashboard and include your Widget ID. You can find the Widget ID on the Widgets page next to your widget’s name.

The widget isn't showing on my page at all

Run through this checklist:

1. Confirm the script tag is in the page HTML. View the page source (right-click → View Page Source) and search for kudoswall. If you don’t see it, re-copy the embed code from Dashboard → Widgets → [your widget] → Embed and paste it into your site.
2. Check the data-id attribute. The data-id value in your script tag must match your Widget ID exactly — it is case-sensitive. Copy it fresh from the dashboard to be sure.
3. Open the browser console. Press F12, go to the Console tab, and look for any red error messages related to KudosWall. The error text will usually tell you what went wrong.
4. Verify the script URL. The src attribute on the script tag should be https://kudoswall.org/widget.js. If it points anywhere else, replace the embed code with the current version from your dashboard.

The widget shows but has no testimonials

The widget only displays approved testimonials. Here’s how to fix it:

1. Go to Dashboard → Testimonials.
2. Look for any testimonials in the Pending state and click Approve on at least one.
3. If you already have approved testimonials but the widget is still empty, check whether your widget has tag filters set. Go to Dashboard → Widgets → [your widget] → Edit → Filtering and confirm that some of your approved testimonials have the tags you’ve specified. If no testimonials match the filter, the widget appears blank.

The widget styles look broken or misaligned

The widget uses Shadow DOM isolation to prevent your site’s CSS from leaking in. In rare cases, a site’s global CSS can still interfere. Try these steps:

1. Set an explicit background color. Go to Dashboard → Widgets → [your widget] → Edit → Branding and set backgroundColor to a solid hex color instead of transparent. This resolves most visual glitches.
2. Check for CSS resets. Some aggressive CSS reset libraries (normalize.css, sanitize.css with certain configurations) can affect Shadow DOM boundaries. If you suspect this, test the widget on a plain HTML page to isolate the issue.
3. Try a different theme setting. Switch between light, dark, and auto to see if the issue is theme-specific.

The widget works locally but not in production

There are two common causes for this:

1. The script tag was stripped by your build tool. Some static site generators (Next.js, Gatsby, Hugo) strip or transform <script> tags with unknown data-* attributes. Check your deployed HTML source to confirm the tag survived the build. You may need to use a raw HTML embed block or a no-script-processing option in your platform.
2. A Content Security Policy (CSP) is blocking the script. If your site sends a Content-Security-Policy HTTP header, add kudoswall.org to both the script-src and connect-src directives:

script-src 'self' https://kudoswall.org;
connect-src 'self' https://kudoswall.org;

You can confirm a CSP block by checking the browser console for an error message that includes “Content Security Policy”.

I updated widget settings but the old version still shows

Widget settings are cached briefly after you save them. To see your changes immediately:

• Hard refresh the page with Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac). This bypasses the browser cache and forces the page to reload the latest widget configuration.

If the old version still appears after a hard refresh, wait a few minutes and try again. The cache clears automatically and your changes will be live shortly.

The widget shows behind other elements on my page

The widget container is rendered as a standard inline element. If it appears underneath a sticky header, floating chat button, or modal overlay, the issue is a z-index conflict. Add CSS to the widget’s parent container (the element wrapping your embed code) to raise its stacking order:

.your-testimonials-section {
  position: relative;
  z-index: 10;
}

Adjust the z-index value as needed based on what other elements are on your page.