cecil / theme-darkmodetoggle

1.0.0 2026-10-09 14:19 UTC

Requires

• cecil/theme-installer: ^1.4|^2.0

MIT

• theme
• color scheme
• cecil
• dark mode

Published on Packagist.org on 2026-10-10 12:20 UTC

README

The Dark mode toggle component theme for Cecil adds an icon button to switch a website between light and dark color schemes.

Demo

Features

• Icon button: a moon in light mode, a sun in dark mode
• Follows the system preference by default, and keeps up with its changes
• Remembers the user choice (only when it differs from the system preference)
• No flash of the wrong scheme on page load
• Framework agnostic: sets a dark class, a data-theme attribute and the color-scheme property on <html> (works with Tailwind CSS, Bootstrap, Pico CSS or plain CSS)
• JavaScript API and colorschemechange event
• Accessible: aria-pressed state, translatable label (English and French included)
• No dependencies, vanilla JavaScript
• Minimal customizable style, through CSS custom properties

Installation

composer require cecil/theme-darkmodetoggle

Or download the latest archive and uncompress its contents in themes/darkmodetoggle.

Usage

Add darkmodetoggle in the theme section of the config.yml:

theme:
  - darkmodetoggle

Add the following line in the HTML <head> of the main template (as early as possible, to avoid a flash):

{{ include('partials/darkmodetoggle-head.html.twig', {site}, with_context = false) }}

Then add the button where you want it to be displayed (in the header for example):

{{ include('partials/darkmodetoggle.html.twig') }}

The button can be included several times, and accepts optional variables:

{{ include('partials/darkmodetoggle.html.twig', {class: 'ml-2', label: 'Night mode'}) }}

Styling the website

In dark mode, the <html> element looks like this:

<html class="dark" data-theme="dark" style="color-scheme: dark;">

And in light mode:

<html data-theme="light" style="color-scheme: light;">

So the dark styles of the website can be written with:

• Tailwind CSS: the dark: variant, with @custom-variant dark (&:where(.dark, .dark *)); (v4) or darkMode: 'class' (v3)
• Bootstrap: set the class option to an empty string and target [data-theme="dark"], or rely on the colorschemechange event to set data-bs-theme
• Plain CSS: :root[data-theme="dark"] { … }

Configuration

Default options:

darkmodetoggle:
  storage_key: theme # localStorage key of the user preference
  class: dark        # class added to <html> in dark mode (empty to disable)
  style: true        # minimal button style (false to style it yourself)

The button style can be customized with the following CSS custom properties:

.darkmodetoggle {
  --darkmodetoggle-size: 1.5rem;          /* icon size */
  --darkmodetoggle-padding: .25rem;
  --darkmodetoggle-radius: .375rem;
  --darkmodetoggle-color: currentColor;
  --darkmodetoggle-background: transparent;
}

Available CSS classes: .darkmodetoggle (button), .darkmodetoggle-icon-dark (moon icon) and .darkmodetoggle-icon-light (sun icon).

JavaScript API

window.colorScheme.current(); // 'light' or 'dark'
window.colorScheme.set('dark');
window.colorScheme.toggle();

document.addEventListener('colorschemechange', (event) => {
  console.log(event.detail.scheme); // 'light' or 'dark'
});

Any element with the data-darkmodetoggle attribute toggles the color scheme when clicked.

Internationalization

The button label and title are translatable (English and French included):

# translations/messages.<locale>.yml
"Dark mode": "Mode sombre"
"Toggle dark mode": "Basculer le mode sombre"

Demo

The demo directory contains a website using the theme (with Pico CSS). To run it locally:

php demo/link.php
php cecil.phar serve demo

demo/link.php links the repository as demo/themes/darkmodetoggle, so the demo uses the theme under development.

License

Dark mode toggle is a free software distributed under the terms of the MIT license.