---
title: "Troubleshooting web UI customization | Nutrient SDK"
canonical_url: "https://www.nutrient.io/guides/web/user-interface/troubleshooting/"
md_url: "https://www.nutrient.io/guides/web/user-interface/troubleshooting.md"
last_updated: "2026-05-25T14:09:00.406Z"
description: "Troubleshoot UI customization issues in your JavaScript PDF viewer. Fix toolbar, sidebar, and theme problems in Nutrient Web SDK."
---

# 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()`:

   ```js

   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:

   ```css

   #nutrient-container {

     width: 100%;
     height: 100vh;
   }
   ```

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

   ```js

   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

## Related resources

- [Optimizing for mobile](https://www.nutrient.io/guides/web/customizing-the-interface/optimizing-for-mobile.md) — Responsive design tips

- [Toolbar customization](https://www.nutrient.io/guides/web/user-interface.md) — Detailed toolbar API reference

- [Custom theme guide](https://www.nutrient.io/guides/web/user-interface/theming/custom-theme.md) — Complete theming documentation

- [General troubleshooting](https://www.nutrient.io/guides/web/troubleshooting/) — Broader SDK troubleshooting
---

## Related pages

- [Create a custom toolbar in our JavaScript PDF viewer](/guides/web/user-interface/create-a-toolbar.md)
- [PDF form field date and time picker](/guides/web/user-interface/date-and-time-picker.md)
- [Form Designer: Create and edit PDF form fields using JavaScript](/guides/web/user-interface/form-designer.md)
- [User interface customization in our JavaScript PDF viewer](/guides/web/user-interface.md)
- [Custom overlays in our viewer](/guides/web/customizing-the-interface/creating-custom-overlay-items.md)
- [Localization: Updating languages in our JavaScript PDF viewer](/guides/web/features/localization.md)
- [Create and customize redactions in our PDF viewer](/guides/web/user-interface/redaction.md)
- [Customizing the search UI in our PDF viewer toolbar](/guides/web/user-interface/search.md)
- [Right-to-left](/guides/web/user-interface/rtl-languages.md)
- [View state in our JavaScript PDF viewer](/guides/web/customizing-the-interface/viewstate.md)

## Pages in this section

- [Internet Explorer [IE11] support for our JavaScript PDF viewer](/guides/web/customizing-the-interface/ie11.md)
- [Optimizing for mobile for our JavaScript PDF viewer](/guides/web/customizing-the-interface/optimizing-for-mobile.md)