Use shadow dom to render the toolbar

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 */
-:root {
+#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";
 }
 
-:root,
+#djDebug,
 #djDebug[data-theme="light"] {
     --djdt-font-color: black;
     --djdt-background-color: white;

debug_toolbar/static/debug_toolbar/js/history.js

@@ -1,6 +1,6 @@
-import { $$, ajaxForm, replaceToolbarState } from "./utils.js";
+import { $$, ajaxForm, getDebugElement, replaceToolbarState } from "./utils.js";
 
-const djDebug = document.getElementById("djDebug");
+const djDebug = getDebugElement();
 
 function difference(setA, setB) {
     const _difference = new Set(setA);
@@ -19,7 +19,7 @@ function pluckData(nodes, key) {
 
 function refreshHistory() {
     const formTarget = djDebug.querySelector(".refreshHistory");
-    const container = document.getElementById("djdtHistoryRequests");
+    const container = djDebug.querySelector("#djdtHistoryRequests");
     const oldIds = new Set(
         pluckData(
             container.querySelectorAll("tr[data-request-id]"),
@@ -85,7 +85,7 @@ function switchHistory(newRequestId) {
 
     ajaxForm(formTarget).then((data) => {
         if (Object.keys(data).length === 0) {
-            const container = document.getElementById("djdtHistoryRequests");
+            const container = djDebug.querySelector("#djdtHistoryRequests");
             container.querySelector(
                 `button[data-request-id="${newRequestId}"]`
             ).innerHTML = "Switch [EXPIRED]";

debug_toolbar/static/debug_toolbar/js/timer.js

@@ -1,4 +1,6 @@
-import { $$ } from "./utils.js";
+import { $$, getDebugElement } from "./utils.js";
+
+const djDebug = getDebugElement();
 
 function insertBrowserTiming() {
     const timingOffset = performance.timing.navigationStart;
@@ -58,10 +60,10 @@ function insertBrowserTiming() {
         tbody.appendChild(row);
     }
 
-    const browserTiming = document.getElementById("djDebugBrowserTiming");
+    const browserTiming = djDebug.querySelector("#djDebugBrowserTiming");
     // Determine if the browser timing section has already been rendered.
     if (browserTiming.classList.contains("djdt-hidden")) {
-        const tbody = document.getElementById("djDebugBrowserTimingTableBody");
+        const tbody = djDebug.querySelector("#djDebugBrowserTimingTableBody");
         // This is a reasonably complete and ordered set of timing periods (2 params) and events (1 param)
         addRow(tbody, "domainLookupStart", "domainLookupEnd");
         addRow(tbody, "connectStart", "connectEnd");
@@ -75,7 +77,6 @@ function insertBrowserTiming() {
     }
 }
 
-const djDebug = document.getElementById("djDebug");
 // Insert the browser timing now since it's possible for this
 // script to miss the initial panel load event.
 insertBrowserTiming();

debug_toolbar/static/debug_toolbar/js/toolbar.js

@@ -1,20 +1,17 @@
-import { $$, ajax, debounce, replaceToolbarState } from "./utils.js";
+import {
+    $$,
+    ajax,
+    debounce,
+    getDebugElement,
+    replaceToolbarState,
+} from "./utils.js";
 
 function onKeyDown(event) {
     if (event.keyCode === 27) {
         djdt.hideOneLevel();
     }
 }
 
-function getDebugElement() {
-    // Fetch the debug element from the DOM.
-    // This is used to avoid writing the element's id
-    // 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.
-    return document.getElementById("djDebug");
-}
-
 const djdt = {
     handleDragged: false,
     needUpdateOnFetch: false,
@@ -27,7 +24,7 @@ const djdt = {
                 return;
             }
             const panelId = this.className;
-            const current = document.getElementById(panelId);
+            const current = djDebug.querySelector(`#${panelId}`);
             if ($$.visible(current)) {
                 djdt.hidePanels();
             } else {
@@ -103,7 +100,7 @@ const djdt = {
             }
 
             ajax(url, ajaxData).then((data) => {
-                const win = document.getElementById("djDebugWindow");
+                const win = djDebug.querySelector("#djDebugWindow");
                 win.innerHTML = data.content;
                 $$.show(win);
             });
@@ -116,7 +113,7 @@ const djdt = {
             const toggleClose = "-";
             const openMe = this.textContent === toggleOpen;
             const name = this.dataset.toggleName;
-            const container = document.getElementById(`${name}_${id}`);
+            const container = djDebug.querySelector(`#${name}_${id}`);
             for (const el of container.querySelectorAll(".djDebugCollapsed")) {
                 $$.toggle(el, openMe);
             }
@@ -156,7 +153,7 @@ const djdt = {
         });
         let startPageY;
         let baseY;
-        const handle = document.getElementById("djDebugToolbarHandle");
+        const handle = djDebug.querySelector("#djDebugToolbarHandle");
         function onHandleMove(event) {
             // Chrome can send spurious mousemove events, so don't do anything unless the
             // cursor really moved.  Otherwise, it will be impossible to expand the toolbar
@@ -240,16 +237,17 @@ const djdt = {
     },
     hidePanels() {
         const djDebug = getDebugElement();
-        $$.hide(document.getElementById("djDebugWindow"));
+        $$.hide(djDebug.querySelector("#djDebugWindow"));
         for (const el of djDebug.querySelectorAll(".djdt-panelContent")) {
             $$.hide(el);
         }
-        for (const el of document.querySelectorAll("#djDebugToolbar li")) {
+        for (const el of djDebug.querySelectorAll("#djDebugToolbar li")) {
             el.classList.remove("djdt-active");
         }
     },
     ensureHandleVisibility() {
-        const handle = document.getElementById("djDebugToolbarHandle");
+        const djDebug = getDebugElement();
+        const handle = djDebug.querySelector("#djDebugToolbarHandle");
         // set handle position
         const handleTop = Math.min(
             localStorage.getItem("djdt.top") || 265,
@@ -258,11 +256,12 @@ const djdt = {
         handle.style.top = `${handleTop}px`;
     },
     hideToolbar() {
+        const djDebug = getDebugElement();
         djdt.hidePanels();
 
-        $$.hide(document.getElementById("djDebugToolbar"));
+        $$.hide(djDebug.querySelector("#djDebugToolbar"));
 
-        const handle = document.getElementById("djDebugToolbarHandle");
+        const handle = djDebug.querySelector("#djDebugToolbarHandle");
         $$.show(handle);
         djdt.ensureHandleVisibility();
         window.addEventListener("resize", djdt.ensureHandleVisibility);
@@ -271,11 +270,12 @@ const djdt = {
         localStorage.setItem("djdt.show", "false");
     },
     hideOneLevel() {
-        const win = document.getElementById("djDebugWindow");
+        const djDebug = getDebugElement();
+        const win = djDebug.querySelector("#djDebugWindow");
         if ($$.visible(win)) {
             $$.hide(win);
         } else {
-            const toolbar = document.getElementById("djDebugToolbar");
+            const toolbar = djDebug.querySelector("#djDebugToolbar");
             if (toolbar.querySelector("li.djdt-active")) {
                 djdt.hidePanels();
             } else {
@@ -284,17 +284,17 @@ const djdt = {
         }
     },
     showToolbar() {
+        const djDebug = getDebugElement();
         document.addEventListener("keydown", onKeyDown);
-        $$.show(document.getElementById("djDebug"));
-        $$.hide(document.getElementById("djDebugToolbarHandle"));
-        $$.show(document.getElementById("djDebugToolbar"));
+        $$.show(djDebug);
+        $$.hide(djDebug.querySelector("#djDebugToolbarHandle"));
+        $$.show(djDebug.querySelector("#djDebugToolbar"));
         localStorage.setItem("djdt.show", "true");
         window.removeEventListener("resize", djdt.ensureHandleVisibility);
     },
     updateOnAjax() {
         const handleAjaxResponse = debounce(async (requestId) => {
-            const sidebarUrl =
-                document.getElementById("djDebug").dataset.sidebarUrl;
+            const sidebarUrl = getDebugElement().dataset.sidebarUrl;
 
             const encodedRequestId = encodeURIComponent(requestId);
             const dest = `${sidebarUrl}?request_id=${encodedRequestId}`;

debug_toolbar/static/debug_toolbar/js/utils.js

@@ -70,6 +70,21 @@ const $$ = {
     },
 };
 
+/**
+ * Fetch the debug element from the DOM.
+ *
+ * This is used to avoid writing the element's id 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.
+ */
+function getDebugElement() {
+    let root = document.getElementById("djDebugRoot");
+    if (root.shadowRoot) {
+        root = root.shadowRoot;
+    }
+    return root.querySelector("#djDebug");
+}
+
 function ajax(url, init) {
     return fetch(url, Object.assign({ credentials: "same-origin" }, init))
         .then((response) => {
@@ -89,7 +104,8 @@ function ajax(url, init) {
             );
         })
         .catch((error) => {
-            const win = document.getElementById("djDebugWindow");
+            const djDebug = getDebugElement();
+            const win = djDebug.querySelector("#djDebugWindow");
             win.innerHTML = `<div class="djDebugPanelTitle"><h3>${error.message}</h3><button type="button" class="djDebugClose">»</button></div>`;
             $$.show(win);
             throw error;
@@ -110,14 +126,14 @@ function ajaxForm(element) {
 }
 
 function replaceToolbarState(newRequestId, data) {
-    const djDebug = document.getElementById("djDebug");
+    const djDebug = getDebugElement();
     djDebug.setAttribute("data-request-id", newRequestId);
     // Check if response is empty, it could be due to an expired requestId.
     for (const panelId of Object.keys(data)) {
-        const panel = document.getElementById(panelId);
+        const panel = djDebug.querySelector(`#${panelId}`);
         if (panel) {
             panel.outerHTML = data[panelId].content;
-            document.getElementById(`djdt-${panelId}`).outerHTML =
+            djDebug.querySelector(`#djdt-${panelId}`).outerHTML =
                 data[panelId].button;
         }
     }
@@ -140,4 +156,4 @@ export function debounce(func, timeout) {
     };
 }
 
-export { $$, ajax, ajaxForm, replaceToolbarState };
+export { $$, ajax, ajaxForm, getDebugElement, replaceToolbarState };

debug_toolbar/templates/debug_toolbar/base.html

@@ -1,43 +1,46 @@
 {% load i18n static %}
-{% 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' %}">
-{% endblock css %}
-{% block js %}
-<script{% if toolbar.csp_nonce %} nonce="{{ toolbar.csp_nonce }}"{% endif %} type="module" src="{% static 'debug_toolbar/js/toolbar.js' %}" async></script>
-{% endblock js %}
-<div id="djDebug" class="djdt-hidden" dir="ltr"
-     {% if not toolbar.should_render_panels %}
-     data-request-id="{{ toolbar.request_id }}"
-     data-render-panel-url="{% url 'djdt:render_panel' %}"
-     {% endif %}
-     {% url 'djdt:history_sidebar' as history_url %}
-     {% if history_url %}
-     data-sidebar-url="{{ history_url }}"
-     {% endif %}
-     data-default-show="{% if toolbar.config.SHOW_COLLAPSED %}false{% else %}true{% endif %}"
-     {{ toolbar.config.ROOT_TAG_EXTRA_ATTRS|safe }}  data-update-on-fetch="{{ toolbar.config.UPDATE_ON_FETCH }}">
-  <div class="djdt-hidden" id="djDebugToolbar">
-    <ul id="djDebugPanelList">
-      <li><a id="djHideToolBarButton" href="#" title="{% translate 'Hide toolbar' %}">{% translate "Hide" %} »</a></li>
-      <li>
-        <a id="djToggleThemeButton" href="#" title="{% translate 'Toggle Theme' %}">
-          {% translate "Toggle Theme" %} {% include "debug_toolbar/includes/theme_selector.html" %}
-        </a>
-      </li>
+<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' %}">
+    {% endblock css %}
+    {% block js %}
+    <script{% if toolbar.csp_nonce %} nonce="{{ toolbar.csp_nonce }}"{% endif %} type="module" src="{% static 'debug_toolbar/js/toolbar.js' %}" async></script>
+    {% endblock js %}
+    <div id="djDebug" class="djdt-hidden" dir="ltr"
+        {% if not toolbar.should_render_panels %}
+        data-request-id="{{ toolbar.request_id }}"
+        data-render-panel-url="{% url 'djdt:render_panel' %}"
+        {% endif %}
+        {% url 'djdt:history_sidebar' as history_url %}
+        {% if history_url %}
+        data-sidebar-url="{{ history_url }}"
+        {% endif %}
+        data-default-show="{% if toolbar.config.SHOW_COLLAPSED %}false{% else %}true{% endif %}"
+        data-update-on-fetch="{{ toolbar.config.UPDATE_ON_FETCH }}">
+      <div class="djdt-hidden" id="djDebugToolbarHandle">
+        <div title="{% translate 'Show toolbar' %}" id="djShowToolBarButton">
+          <span id="djShowToolBarD">D</span><span id="djShowToolBarJ">J</span>DT
+        </div>
+      </div>
+      <div class="djdt-hidden" id="djDebugToolbar">
+        <ul id="djDebugPanelList">
+          <li><a id="djHideToolBarButton" href="#" title="{% translate 'Hide toolbar' %}">{% translate "Hide" %} »</a></li>
+          <li>
+            <a id="djToggleThemeButton" href="#" title="{% translate 'Toggle Theme' %}">
+              {% translate "Toggle Theme" %} {% include "debug_toolbar/includes/theme_selector.html" %}
+            </a>
+          </li>
+          {% for panel in toolbar.panels %}
+            {% include "debug_toolbar/includes/panel_button.html" %}
+          {% endfor %}
+        </ul>
+      </div>
       {% for panel in toolbar.panels %}
-        {% include "debug_toolbar/includes/panel_button.html" %}
+        {% include "debug_toolbar/includes/panel_content.html" %}
       {% endfor %}
-    </ul>
-  </div>
-  <div class="djdt-hidden" id="djDebugToolbarHandle">
-    <div title="{% translate 'Show toolbar' %}" id="djShowToolBarButton">
-      <span id="djShowToolBarD">D</span><span id="djShowToolBarJ">J</span>DT
+      <div id="djDebugWindow" class="djdt-panelContent djdt-hidden"></div>
     </div>
-  </div>
-
-  {% for panel in toolbar.panels %}
-    {% include "debug_toolbar/includes/panel_content.html" %}
-  {% endfor %}
-  <div id="djDebugWindow" class="djdt-panelContent djdt-hidden"></div>
+  {% 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

@@ -9,6 +9,13 @@ Pending
 * Added a note to the prerequisites section of the installation docs
   about requiring an up-to-date browser.
 * Dropped support for Django 4.2 and Django 5.1 .
+* 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``.
+* Note that custom themes overriding CSS variables on :root must move
+  those overrides to ``#djDebug``, and custom panels that rely on external
+  styles or DOM lookups reaching into the toolbar will need updates to
+  work with the shadow DOM.
 
 6.3.0 (2026-04-01)
 ------------------