upassist / neos-ui-thememode
Light, dark and auto theme mode for the Neos CMS backend (content UI and backend modules)
Package info
github.com/UpAssist/neos-ui-thememode
Language:JavaScript
Type:neos-package
pkg:composer/upassist/neos-ui-thememode
Requires
- neos/neos: ^8.3 || ^9.0
- neos/neos-ui: ^8.3 || ^9.0
Requires (Dev)
None
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-19 15:17:58 UTC
README
Light, dark and auto theme mode for the Neos CMS backend: the content UI and the backend modules (Media, Workspaces, User management, ...).
A toggle in the top toolbar cycles auto → light → dark. Auto follows the operating system (prefers-color-scheme) and switches live. The choice is stored per browser in localStorage and shared between the content UI, the modules and other open tabs.
Works with Neos 8.3+ and Neos 9, with no build step.
Light mode in Neos 9: the content UI and the Media module.
Compatibility
| Version | Neos |
|---|---|
| 1.0.x | 8.3, 8.4, 9.0, 9.1, 9.2 |
Installation
composer require upassist/neos-ui-thememode
Then flush the caches and publish the resources:
./flow flow:cache:flush ./flow resource:publish
For local development against a checkout, add a path repository to the distribution's composer.json:
{"type": "path", "url": "../neos-ui-thememode", "options": {"symlink": true}}
How it works
Neos ships one dark design with hardcoded colours and hashed CSS-module class names, so there is nothing stable to override with plain CSS. Instead, ThemeMode.js builds the light theme at runtime:
- It reads every loaded stylesheet through the CSSOM.
- For each rule it copies only the colour declarations (
color,background-*,border-*-color,box-shadow,fill, custom properties, ...) and maps the colours:- neutral greys are mapped along a lightness curve anchored on the Neos palette (
#141414,#222,#323232,#3f3f3f,#999,#fff, ...); - saturated accents (brand blue, warning, error, success) keep their value;
- translucent black (shadows, backdrops) stays as it is;
- text on an accent background in the same rule stays as it is;
- light surfaces in the dark design (a focused field, the date picker, the content canvas) and widgets with their own light design (CodeMirror, CKEditor content) keep their colours; only near-black text in them is softened;
- the darkest text is anthracite (
#3c3c3c), not black. Muted text stays at a contrast of at least 4.5:1.
- neutral greys are mapped along a lightness curve anchored on the Neos palette (
- The resulting "twin" sheet is inserted directly after its source. Selectors, specificity and source order are unchanged, so each twin wins exactly where its original rule applied.
- Switching theme only flips the twins'
mediaattribute (all/not all). In dark mode the original Neos styles are untouched.
Twins are generated the first time light mode is needed, cached in localStorage (keyed by URL plus a fingerprint of the sheet), and stylesheets added later (plugins, CKEditor) are picked up through a MutationObserver.
Rules whose selector mentions data-neos-theme are skipped by the engine. Use that for hand-written fixes, as in Resources/Public/Styles/ThemeMode.css:
html[data-neos-theme="light"] .my-plugin-thing { color: rgb(30, 30, 30); }
Scope and limits
- The content iframe (your site) is never touched. The inline editing toolbar that Neos renders inside the iframe stays dark.
- Colours set inline (
style="..."or SVGfillattributes) are not in a stylesheet and are not mapped. Such cases can be fixed with adata-neos-themerule. - In light mode the Neos logo in the top bar is replaced with the original primary logo (
Resources/Public/Images/neos-logo-primary.svg, from the Neos brand assets). The Neos name and logo are trademarks of the Neos project and are not covered by this package's MIT license. - Cross-origin stylesheets cannot be read and are skipped.
- The login page and the splash screen are not themed.
JavaScript API
UpAssistThemeMode.getMode(); // 'light' | 'dark' | 'auto' UpAssistThemeMode.getEffectiveTheme(); // 'light' | 'dark' UpAssistThemeMode.setMode('light'); const unsubscribe = UpAssistThemeMode.subscribe((mode, theme) => { /* ... */ });
The effective theme is also set on <html data-neos-theme="light|dark" data-neos-theme-mode="light|dark|auto">.
Files
| File | Purpose |
|---|---|
Resources/Public/JavaScript/ThemeMode.js |
Theme engine and API, loaded in the content UI and in the modules |
Resources/Public/JavaScript/Toggle.js |
Toolbar toggle for the Neos UI (host plugin API, React from the host) |
Resources/Public/JavaScript/ModuleToggle.js |
Toggle in the top bar of the backend modules |
Resources/Public/Styles/ThemeMode.css |
Toggle styles and explicit light fixes (logo) |
Resources/Public/Images/neos-logo-primary.svg |
Original Neos logo for light backgrounds |
Configuration/Settings.yaml |
Registers the resources for the UI and for all modules |
License
MIT

