docs(theming): document THEME_DEFAULT_MODE config setting

The theming.mdx config reference covers THEME_DEFAULT/THEME_DARK but was never updated for THEME_DEFAULT_MODE, added in #41007, which lets operators default the instance to dark/light instead of following the system preference. Follow-up to #41007. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-27 18:41:20 +00:00 · 2026-08-27 09:09:29 -07:00
1 changed files with 16 additions and 0 deletions
@@ -88,6 +88,22 @@ THEME_DARK = {
 # - OS preference detection is automatically enabled
 ```

+### Default Theme Mode
+
+By default, Superset mimics the visitor's OS/browser preference (light or dark) for
+sessions that don't have a saved user preference. Use `THEME_DEFAULT_MODE` to override
+that starting point instance-wide:
+
+```python
+# Default theme mode for sessions without a saved user preference.
+# One of "default" (always light), "dark" (always dark), or "system" (mimic OS preference).
+THEME_DEFAULT_MODE = "dark"
+```
+
+- `"system"` (the default) preserves the existing behavior of following the OS/browser preference.
+- `"default"` or `"dark"` forces that starting mode for first-time visitors; users can still switch themes manually afterward if both `THEME_DEFAULT` and `THEME_DARK` are available.
+- A user's own saved preference, once they toggle the theme switcher, always takes precedence over `THEME_DEFAULT_MODE`.
+
 ### App Branding

 The application name shown in the browser title bar and navigation can be