User interface troubleshooting

Troubleshoot common issues you might encounter when setting up the user interface.

Common issues

This section covers the most frequently encountered problems when customizing the user interface, with diagnostic steps and solutions for each.

Viewer not displaying

If the viewer doesn’t appear, check the following.

  1. Container element exists — Ensure the container element is in the DOM before calling NutrientViewer.load():

    const container = document.getElementById("nutrient-container");
    if (!container) {
      console.error("Container element not found");
      return;
    }

  2. Container has dimensions — The container needs an explicit width and height:

    #nutrient-container {
      width: 100%;
      height: 100vh;
    }

  3. Check for errors — Always add error handling to catch loading issues:

    NutrientViewer.load({ container, document: "doc.pdf" })
      .catch((error) => console.error("Load failed:", error));

Custom theme not applying

  • You must provide a complete theme object — partial themes aren’t supported
  • Copy the full theme from the [custom theme][] guide and modify only what you need
  • Check the browser console for validation errors

Toolbar items not showing

  • Verify the item’s type is valid
  • Check mediaQueries — items may be hidden on certain screen sizes
  • Ensure setToolbarItems() is called after the viewer loads (in the .then() callback)

Icons not displaying

  • SVG icons must be valid XML — use an SVG validator if needed
  • External icon URLs must be accessible (check for CORS issues)
  • Base64-encoded images must include the proper data URI prefix