Add USE_SHADOW_DOM setting to opt-out to shadow DOM toolbar rendering

Author: federicobond

debug_toolbar/settings.py

@@ -32,6 +32,7 @@ def _is_running_tests():
     "ROOT_TAG_EXTRA_ATTRS": "",
     "SHOW_COLLAPSED": False,
     "SHOW_TOOLBAR_CALLBACK": "debug_toolbar.middleware.show_toolbar",
+    "USE_SHADOW_DOM": True,
     "TOOLBAR_LANGUAGE": None,
     "TOOLBAR_STORE_CLASS": "debug_toolbar.store.MemoryStore",
     "UPDATE_ON_FETCH": False,

debug_toolbar/static/debug_toolbar/css/toolbar.css

@@ -1,5 +1,5 @@
 /* Variable definitions */
-:host {
+#djDebug {
     /* Font families are the same as in Django admin/css/base.css */
     --djdt-font-family-primary:
         "Segoe UI", system-ui, Roboto, "Helvetica Neue", Arial, sans-serif,
@@ -13,7 +13,7 @@
         "Noto Color Emoji";
 }
 
-:host,
+#djDebug,
 #djDebug[data-theme="light"] {
     --djdt-font-color: black;
     --djdt-background-color: white;

debug_toolbar/static/debug_toolbar/js/utils.js

@@ -76,9 +76,10 @@ function getDebugElement() {
     // everywhere the element is being selected. A fixed reference
     // to the element should be avoided because the entire DOM could
     // be reloaded such as via HTMX boosting.
-    const root = document.getElementById(
-        "djDebugShadowRootContainer"
-    ).shadowRoot;
+    let root = document.getElementById("djDebugRoot");
+    if (root.shadowRoot) {
+        root = root.shadowRoot;
+    }
     return root.querySelector("#djDebug");
 }
 

debug_toolbar/templates/debug_toolbar/base.html

@@ -1,6 +1,6 @@
 {% load i18n static %}
-<div id="djDebugShadowRootContainer" {{ toolbar.config.ROOT_TAG_EXTRA_ATTRS|safe }}>
-  <template shadowrootmode="open">
+<div id="djDebugRoot" {{ toolbar.config.ROOT_TAG_EXTRA_ATTRS|safe }}>
+  {% if use_shadow_dom %}<template shadowrootmode="open">{% endif %}
     {% block css %}
     <link{% if toolbar.csp_nonce %} nonce="{{ toolbar.csp_nonce }}"{% endif %} rel="stylesheet" href="{% static 'debug_toolbar/css/print.css' %}" media="print">
     <link{% if toolbar.csp_nonce %} nonce="{{ toolbar.csp_nonce }}"{% endif %} rel="stylesheet" href="{% static 'debug_toolbar/css/toolbar.css' %}">
@@ -42,5 +42,5 @@
       {% endfor %}
       <div id="djDebugWindow" class="djdt-panelContent djdt-hidden"></div>
     </div>
-  </template>
+  {% if use_shadow_dom %}</template>{% endif %}
 </div>

debug_toolbar/toolbar.py

@@ -97,7 +97,10 @@ def render_toolbar(self) -> str:
         if not self.should_render_panels():
             self.init_store()
         try:
-            context = {"toolbar": self}
+            context = {
+                "toolbar": self,
+                "use_shadow_dom": self.config["USE_SHADOW_DOM"],
+            }
             lang = self.config["TOOLBAR_LANGUAGE"] or get_language()
             with lang_override(lang):
                 return render_to_string("debug_toolbar/base.html", context)

docs/changes.rst

@@ -8,6 +8,9 @@ Pending
   fetch requests.
 * Added a note to the prerequisites section of the installation docs
   about requiring an up-to-date browser.
+* Updated to render the toolbar in a shadow DOM for better isolation
+  from the rest of the page. This can be disabled with the setting
+  ``USE_SHADOW_DOM``.
 
 6.3.0 (2026-04-01)
 ------------------