DF Dark Mode for PrestaShop 8 and 9 — Documentation

DF Dark Mode adds a complete dark mode to your PrestaShop 8 or 9 store, with no theme modification at all. The module detects the visitor’s system preference, remembers their choice, and generates the dark theme server-side.

Installation

1. In the back office, open Modules > Module Manager.
2. Click Upload a module and drop the dfdarkmode-1.1.0.zip file.
3. Once the installation is complete, click Configure.

The module is active immediately with its default settings: smart filter engine, auto mode and a floating button in the bottom right corner. No configuration is required for correct operation.

Choosing the rendering engine

The module offers two engines. The choice is made in the Rendering engine field of the configuration screen.

Smart filter (recommended)

This engine inverts the whole page, then counter-inverts every medium (images, videos, iframes, canvas, backgrounds) so that your product photos keep their natural colors. It works on any theme, with no configuration and no extra CSS.

Two settings let you fine-tune the result:

• Brightness (50 to 150%, default 100) — lower it slightly, to 92 for instance, if the dark rendering feels too bright.
• Contrast (50 to 150%, default 100).

Generated palette

This engine computes a complete dark range from two colors of your choosing: a background color and an accent color. Nine CSS variables are derived from them automatically:

• --df-bg — the page background
• --df-surface, --df-surface-2, --df-surface-3 — three surface levels (cards, headers, hovers)
• --df-border — borders
• --df-text, --df-text-muted — primary and muted text
• --df-accent, --df-accent-hover — the accent and its hover state

The button text color is chosen automatically (light or dark) based on the relative luminance of your accent, to guarantee readable contrast. This engine produces a cleaner result than the filter, but may require a few CSS tweaks depending on your theme.

Default mode

The Default mode field determines what a visitor sees when they have never used the button yet:

• Auto — the module follows the visitor’s operating system preference (the prefers-color-scheme setting). If the visitor switches their device to dark mode while browsing, the storefront follows live, with no reload.
• Light — the storefront stays light until the visitor asks for dark mode.
• Dark — the storefront is dark for everyone by default.

As soon as the visitor clicks the button, their choice is stored in their browser and takes precedence over the default mode, for all their subsequent visits.

Placing the button

The Toggle placement field offers two modes.

Floating button

A round button overlaid on the page, in one of the four corners (top/bottom, left/right). You can hide it on mobile through the dedicated setting.

Theme hook

The button is rendered inline, inside your theme’s layout. Pick the target hook from the list:

• displayNav1, displayNav2 — top bars of the header (displayNav2 is the top-right area on most themes)
• displayTop, displayNavFullWidth, displayBanner
• displayFooter, displayFooterAfter

The inline variant of the button is more compact and transparent: it inherits the colors of its container and blends into your header or footer.

Custom hook

If your theme executes a hook of its own, simply type its name into the Custom hook name field. The module registers it automatically when you save the form — no code to write. This field takes precedence over the list above.

The name must start with a letter and contain only letters, digits and underscores. Example: displayMySwitcher.

From a template

Integrators can render the button anywhere in a theme .tpl file with the PrestaShop widget syntax:

{widget name='dfdarkmode'}

This call always renders the button, whatever placement mode is configured.

Three-state cycle button

Enable the 3-state toggle option to make the button cycle between light, dark and auto instead of a simple light/dark switch. A small “A” badge appears on the button when auto mode is active.

Excluding elements

The Excluded CSS selectors field accepts a list of selectors, one per line or comma-separated. Matching elements keep their original light rendering — handy for a logo, a partner banner or a third-party widget.

.my-logo
#partner-banner
.reviews-widget

Selectors containing braces, angle brackets or semicolons are discarded on save.

You can also add the df-no-invert class directly to an element of your theme: it will be preserved automatically.

Custom CSS

The Custom CSS field is injected only when dark mode is active. Prefix your rules with html.df-dark:

html.df-dark .header-banner {
    background: var(--df-surface);
    color: var(--df-text);
}

The CSS variables (--df-surface, --df-text, and so on) are only available with the generated palette engine.

JavaScript API

The module exposes a public API for your own integrations:

// Configured mode: "light", "dark" or "auto"
DFDarkMode.get();

// Mode actually displayed: "light" or "dark"
DFDarkMode.effective();

// Force a mode (stored in the browser)
DFDarkMode.set('dark');

// Toggle
DFDarkMode.toggle();

An event is dispatched on the document on every mode change:

document.addEventListener('dfdarkmode:change', function (e) {
    console.log(e.detail.mode);  // "light" | "dark" | "auto"
    console.log(e.detail.dark);  // true | false
});

Finally, any element carrying the data-df-darkmode-toggle attribute automatically becomes a trigger, with no extra code.

How it works

No flash on load

A synchronous script, injected into the page head, reads the stored preference and applies the df-dark class to the root element before the browser’s first paint. A visitor in dark mode therefore never sees the light version, not even briefly.

Media counter-inversion

With the filter engine, CSS filters compose when nested: they do not cancel each other. An image placed inside an already counter-inverted picture element would therefore be inverted twice. The module neutralises this case with a guard rule that resets the filter of any medium nested inside an already counter-inverted ancestor.

Memorization

The visitor’s choice is stored in their browser’s localStorage, under the dfdm key. No personal data is collected or sent to any server: the module uses neither cookies nor network calls, and therefore has no GDPR implications.

Troubleshooting

Product photos appear as negatives

Make sure you are running version 1.1.0 or higher, then clear the PrestaShop cache (Advanced Parameters > Performance > Clear cache). If a specific element remains inverted, add its selector to the excluded selectors field.

The button does not appear on the chosen hook

Some themes do not execute every standard hook. Check under Design > Positions that the module is indeed hooked to the target hook, and that this hook is actually called by your theme. As a last resort, use the widget syntax in the .tpl file of your choice.

An element stays unreadable in dark mode

Add a rule to the custom CSS field, prefixed with html.df-dark. If the issue affects a whole block, excluding it through the CSS selectors is often simpler.

Uninstallation

Uninstalling removes the module’s entire configuration. Preferences saved in your visitors’ browsers are not affected, but they become inert once the module is removed.