maikschneider/login-color-scheme

Color-scheme aware TYPO3 backend login: adds a dark mode variant for the login background image.

1.0.0 2026-08-07 15:29 UTC

Requires

• php: ^8.2
• psr/http-message: ^1.1 || ^2.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0
• typo3/cms-backend: ^13.4 || ^14.0
• typo3/cms-core: ^13.4 || ^14.0

Requires (Dev)

• armin/editorconfig-cli: ^2.1
• ergebnis/composer-normalize: ^2.45
• friendsofphp/php-cs-fixer: ^3.12
• move-elevator/composer-translation-validator: ^1.3
• phpstan/extension-installer: ^1.3
• phpunit/phpunit: ^11.5 || ^12.0
• saschaegerer/phpstan-typo3: ^3.0
• typo3/testing-framework: ^9.5

GPL-2.0-or-later

• Maik Schneider

• backend
• login
• typo3
• typo3-cms-extension
• color-scheme
• dark-mode

Published on Packagist.org on 2026-08-07 16:01 UTC

README

The TYPO3 backend login screen follows the visitor's preferred color scheme, but the core setting [BE][loginBackgroundImage] accepts only one image. This extension adds a second setting for the image to use while the dark color scheme is active.

Related: forge issue #106760.

Requirements

TYPO3	PHP
13.4 LTS	≥ 8.2
14.x	≥ 8.3

Installation

composer require maikschneider/login-color-scheme

Configuration

The extension adds a single setting, backgroundImageDark. Set it in Admin Tools → Settings → Extension Configuration → login_color_scheme, or in config/system/settings.php:

'EXTENSIONS' => [
    'backend' => [
        // light color scheme, handled by TYPO3 core
        'loginBackgroundImage' => 'EXT:my_sitepackage/Resources/Public/Images/login.jpg',
    ],
    'login_color_scheme' => [
        // dark color scheme, handled by this extension
        'backgroundImageDark' => 'EXT:my_sitepackage/Resources/Public/Images/login-dark.jpg',
    ],
],

The value accepts the same formats as the core setting: an EXT: path, a path relative to the project root such as fileadmin/login-dark.jpg, or an absolute URL.

Configuring only the dark image is valid. Light mode then falls back to the plain background color, as it does in an unconfigured TYPO3.

How it works

A backend middleware adds one inline CSS block to every route that renders the login layout — login, login refresh, password reset and MFA:

@media (prefers-color-scheme: dark) {
    :root:not([data-color-scheme="light"]) .typo3-login { background-image: url("…"); }
}
:root[data-color-scheme="dark"] .typo3-login { background-image: url("…"); }

Two rules are needed because the backend has three color scheme states. The authentication screens carry no data-color-scheme attribute and therefore follow the operating system, while a logged-in user reaching the login refresh dialog may have pinned light or dark in their user settings.

The selectors are more specific than the core .typo3-login rule, so the override applies regardless of render order. The URL is escaped with GeneralUtility::sanitizeCssVariableValue(), the same helper core uses, and the block is emitted with a CSP nonce.

Limitations

The extension covers the background image only. The login logo (loginLogo) and the highlight color (loginHighlightColor) are not color scheme aware either, but the logo is inlined by a ViewHelper and needs a different approach — see forge issue #107558.

Development

composer install
composer sca      # composer normalize, editorconfig, php lint, php-cs-fixer, phpstan, xliff
composer tests    # unit tests

Bug reports and pull requests are welcome, see CONTRIBUTING.md.

License

GPL-2.0-or-later