> ## Documentation Index
> Fetch the complete documentation index at: https://kudoswall.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  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.
</Note>

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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:

    ```text theme={null}
    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".
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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:

    ```css theme={null}
    .your-testimonials-section {
      position: relative;
      z-index: 10;
    }
    ```

    Adjust the `z-index` value as needed based on what other elements are on your page.
  </Accordion>
</AccordionGroup>