From 4ce47e778b5fec8bbc71e1a4f6b1b25c9d5024ed Mon Sep 17 00:00:00 2001
From: Jeremy Stretch <jstretch@netboxlabs.com>
Date: Wed, 6 Aug 2025 11:47:06 -0400
Subject: [PATCH] Closes #18006: Dispatch event when toggling color mode &
 document for plugin use (#20031)

---
 docs/plugins/development/user-interface.md |  14 ++++++++++++++
 mkdocs.yml                                 |   1 +
 netbox/project-static/dist/netbox.js       | Bin 382185 -> 382279 bytes
 netbox/project-static/dist/netbox.js.map   | Bin 1733459 -> 1733684 bytes
 netbox/project-static/src/colorMode.ts     |   5 +++++
 netbox/project-static/src/global.d.ts      |   3 +++
 6 files changed, 23 insertions(+)
 create mode 100644 docs/plugins/development/user-interface.md

diff --git a/docs/plugins/development/user-interface.md b/docs/plugins/development/user-interface.md
new file mode 100644
index 000000000..a918eb185
--- /dev/null
+++ b/docs/plugins/development/user-interface.md
@@ -0,0 +1,14 @@
+# User Interface
+
+## Light & Dark Mode
+
+The NetBox user interface supports toggling between light and dark versions of the theme. If needed, a plugin can determine the currently active color theme by inspecting `window.localStorage['netbox-color-mode']`, which will indicate either `light` or `dark`.
+
+Additionally, when the color scheme is toggled by the user, a custom event `netbox.colorModeChanged` indicating the new scheme is dispatched. A plugin can listen for this event if needed to react to the change:
+
+```typescript
+window.addEventListener('netbox.colorModeChanged', e => {
+  const customEvent = e as CustomEvent<ColorModeData>;
+  console.log('New color mode:', customEvent.detail.netboxColorMode);
+});
+```
diff --git a/mkdocs.yml b/mkdocs.yml
index 4e5f484c7..585c8448c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -144,6 +144,7 @@ nav:
             - Search: 'plugins/development/search.md'
             - Event Types: 'plugins/development/event-types.md'
             - Data Backends: 'plugins/development/data-backends.md'
+            - User Interface: 'plugins/development/user-interface.md'
             - REST API: 'plugins/development/rest-api.md'
             - GraphQL API: 'plugins/development/graphql-api.md'
             - Background Jobs: 'plugins/development/background-jobs.md'
diff --git a/netbox/project-static/dist/netbox.js b/netbox/project-static/dist/netbox.js
index 9e2d6b383c2f22e003900f3bd894ce5d117a9676..ed5971014525535a6d15447b11dc1e9f17494bec 100644
GIT binary patch
delta 123
zcmaF4QvCQT@rD-07N#xC%2Q%>$}{s)^2_y7GK&imOOi8O%Tn`7H1bl*6`V_pOY(Ce
ze5Jh9lBE0!z2y9y{374{lvL-8#Ju#>6eXSNl+=>M%p9v~hze(z0;{~*TFrK)Da=63
LvR!Ek>v0DFkDxC5

delta 29
jcmX@UO8n(Y@rD-07N#xC%2V1Kr!WIC%l5`8tj8Pxy`Kz0

diff --git a/netbox/project-static/dist/netbox.js.map b/netbox/project-static/dist/netbox.js.map
index 0ba7a62d196c16b438f603fcc2e4ccad2acccbf2..295f03aca260fd788895bc1bf2de46f6aca69dba 100644
GIT binary patch
delta 335
zcmccoEOX0?%!U@m7N!>F7M2#)7Pc1l7LFFq7OocVEj$J6^$H5*nRzMs<$5WZ#RZ8a
z$r-L?sd*(DF?k9=ke6Dn;9Oc<lAj9}wQ<hR$uIKFPf2x2EJ?J}P|r&(Ny@L#ONI$M
zXC&sOr>3auC{#lXP*6xoElJGGu~Mi88U|7fH^NFG7if@xLah!&X{{!h(VoN31H`;Q
z%m>8$Kr8^nf<P<;#KJ%<0>q-*bJ)dtt_Qn1I_Ej*_&YlK>m)lm`{;N&I(q6vIyxFT
z=@>YHDQ8FL3Kx)yKpkgCM^~M6pm3&>BZ%V-B%E`cK}-<g>;WR&w*S2+_MV9;&!hd_
SLopy02V#ls?;c8~P6Pl2>~6gP

delta 112
zcmdn;BJ=XI%!U@m7N!>F7M2#)7Pc1l7LFFq7OocVEj$J6?aUlJK+Frod_c?(!~#Gp
z2*g4_EDXdVKrFhQnM17OI;*pzbCJ{bd-uiOGcj4Zx1WC`2E^h(EV2FkBgxc>09Fws
AJ^%m!

diff --git a/netbox/project-static/src/colorMode.ts b/netbox/project-static/src/colorMode.ts
index 453617740..1d05c955d 100644
--- a/netbox/project-static/src/colorMode.ts
+++ b/netbox/project-static/src/colorMode.ts
@@ -43,6 +43,11 @@ function updateElements(targetMode: ColorMode): void {
 export function setColorMode(mode: ColorMode): void {
   storeColorMode(mode);
   updateElements(mode);
+  window.dispatchEvent(
+    new CustomEvent<ColorModeData>('netbox.colorModeChanged', {
+      detail: { netboxColorMode: mode },
+    }),
+  );
 }
 
 /**
diff --git a/netbox/project-static/src/global.d.ts b/netbox/project-static/src/global.d.ts
index d7244339a..5b75be1ca 100644
--- a/netbox/project-static/src/global.d.ts
+++ b/netbox/project-static/src/global.d.ts
@@ -79,3 +79,6 @@ type FormControls = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
 
 type ColorMode = 'light' | 'dark';
 type ColorModePreference = ColorMode | 'none';
+type ColorModeData = {
+  netboxColorMode: ColorMode;
+};