Color Scheme Switcher
This module allows site visitors to switch between light, dark, or system-default color schemes without reloading the page. It integrates with themes and saves the user's preference locally so it persists across visits.
The Color Scheme Switcher module provides a frontend API and a ready-made block to let visitors switch between Light, System (Auto), and Dark color schemes on a Drupal 11 site — without a page reload.
Features
- Injects an inline
<style>tag early in<head>to set the CSScolor-schemeproperty on:root, minimising flash-of-unstyled-content. - Adds a configurable CSS class to the
<html>element (e.g.color-scheme-dark) so themes can target the active scheme with plain CSS selectors. - Persists the visitor's choice in
localStorageso it survives page loads and hard refreshes. - Optionally hides elements with a "hide class" (e.g.
color-scheme-only-dark) when the opposite scheme is active — useful for scheme-specific images or banners. - Ships a placeable block with two widget types: Buttons (one per state) and Dropdown.
- All CSS variable names and HTML classes are configurable per active frontend theme.
Use this module when you want visitors to manually override the system color-scheme
preference and the active theme applies styles via the CSS color-scheme
property or HTML classes on <html>.
Post-Installation
- Go to Administration → Configuration → Color Scheme Switcher (
/admin/config/cosesi/theme-settings) and configure the CSS variable name and the HTML classes for each active frontend theme. - Go to Administration → Structure → Block layout and place the Color Scheme Switcher block in a region of the active theme. In the block settings choose the widget type (Buttons or Dropdown) and the per-state labels and icon sizes.
- Export the new
cosesi.theme_settingsconfig with the rest of the site config.
Additional Requirements
- PHP
>=8.4 - Drupal
^11.3 - A frontend theme that applies styles based on the
color-schemeCSS property or the HTML classes configured in the module settings.
Recommended modules/libraries
No additional modules are required.
Similar projects
- Dark Mode Switch — provides a toggle for dark/light mode but does not expose a three-state (Light / System / Dark) API or per-theme CSS class configuration.
Known issues and limitations
- Batch process pages: The switcher block is not rendered on batch process pages (e.g.
/batch) by default, because Drupal's batch system uses a minimal page that does not invoke the normal block-placement layer. - #3500895: Regression: Third party settings for simple config impossible due config schema validation
- #3402885: olivero.settings config schema is wrong
Depends on
Dependencies of the latest stable release
No dependencies recorded for this project.
Required by
Tracked projects that depend on this one
No tracked projects depend on this one yet.
Activity
Releases
| Version | Type | Core | Notes | Release date | |
|---|---|---|---|---|---|
| 1.x-dev | Dev | 11 | Apr 19, 2026 | ||
| 1.0.0-alpha1 | Pre-release | 11 | Basic implementation | Apr 19, 2026 |