Use data-dark-mode attribute instead of class for dark mode toggle

Created on 30 September 2025, 26 days ago

Problem/Motivation

Currently, the module sets a class="dark" attribute on the <html> element while also relying on data attributes (e.g., data-dark-mode-source). This combines two approaches, resulting in redundancy and potential conflicts.

A cleaner, more consistent approach would be to rely solely on a custom data attribute on the <html> element (e.g., `data-dark-mode="dark"` or `data-dark-mode="light"`).

Benefits of using a dedicated data attribute:

  • Clearer semantics: communicates explicitly whether dark or light mode is active.
  • Avoids CSS selector conflicts with existing or future theme classes that may also use dark.
  • Provides a single, extensible source of truth for dark mode state (easy to query in JavaScript and CSS).
  • Makes it easier for contrib themes and custom code to extend or hook into the dark mode toggle logic.
  • Improves maintainability by reducing reliance on generic CSS classes with overloaded meaning.

Steps to reproduce

  1. Enable the Dark Mode Toggle module.
  2. Inspect the <html> element when toggling dark mode.
  3. Observe that the class="dark" attribute is added, rather than a unified data attribute.

Proposed resolution

Replace the use of class="dark" on the <html> element with a single custom data attribute, e.g., <html data-dark-mode="dark"> or <html data-dark-mode="light">

Remaining tasks

  • Update module code to set data-dark-mode instead of class="dark".
  • Update the README.md accordingly, instructing users to use the [data-dark-mode="dark"] attribute.
  • Update the FunctionalJavascript, and add Unit and Kernel tests to confirm correct behavior.

User interface changes

No visible UI changes to end users.
Developers inspecting the DOM will see data-dark-mode instead of a dark class attribute.

API changes

  • CSS/JS APIs should now target [data-dark-mode="dark"] instead of .dark.
  • Any documented references to the dark class should be updated to reference the new attribute.

Data model changes

None. No changes will be made to the stored configuration or database schema.

Feature request
Status

Active

Version

2.0

Component

Code

Created by

🇳🇱Netherlands watergate

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Merge Requests

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

Production build 0.71.5 2024