Documentation v8.1.9


Metronic supports dynamic theme mode switching to both Dark  and Light  modes by storing the user's preference in the browser's local storage or user'f profile in the server side database.

Quick Setup

The theme mode can be set through data-bs-theme-modeattribute on the page's root <html> tag. The theme mode accepts dark, lightor system. If this attribute is not set then user's selected theme mode will be stored in the browser storage.
<html data-bs-theme-mode="light">
Refer to src/js/layout/theme-mode-user.jsscript to submit the selected theme mode value to backend for saving it in database so users always use prefered theme mode when logged in from different devices.
The theme mode can be set individually for particular page blocks despite having different mode for the page:
Instagram Social Media
Instagram Social Media
<!-- Dark mode -->
<div data-bs-theme="dark">

<!-- Light mode -->
<div data-bs-theme="light">


To enable remembering user's selected theme mode in the browser storage the below inline Javascript code must be placed as the first child of the body element so the code is executed right after the body element's creation in the DOM. The default theme mode defaultThemeModevariable can be set to system, darkor light:
if (document.documentElement) {
    const defaultThemeMode = "system";
    const name = document.body.getAttribute("data-kt-name");
    let themeMode = localStorage.getItem("kt_" + (name !== null ? name + "_" : "") + "theme_mode_value");
    if (themeMode === null) {
        if (defaultThemeMode === "system") {
            themeMode = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
        } else {
            themeMode = defaultThemeMode;
    document.documentElement.setAttribute("data-bs-theme", themeMode);

Switch Menu

The theme mode can be switched through unified Theme Mode Switcher opened by the sun or moon icons click in the page's header block. The theme mode switch feature is handled by KTThemeModejavascript class and allows saving user's preference in the browser's local storage.

Flip Elements

Use .theme-light-showand .theme-dark-showutility classes to flip an element for particular theme mode:
<!-- Show for light mode only-->
<div class="theme-light-show">

<!-- Show for dark mode only-->
<div class="theme-dark-show">

Flip Images

Use .theme-light-showand .theme-dark-showutility classes to flip image for required mode:
<!-- Show for light mode only -->
<img alt="Logo" src="assets/logos/default.svg" class="theme-light-show h-35px"/>

<!-- Show for dark mode light-->
<img alt="Logo" src="assets/logos/default-dark.svg" class="theme-dark-show h-35px"/>
Use a custom class defined inside <style>tag for background image flip support:
<!--begin::Image placeholder-->
 .image-placeholder {
  background-image: url('assets/example.svg');

 [data-bs-theme="dark"] .image-placeholder {
  background-image: url('assets/example-dark.svg');
<!--end::Image placeholder-->

<!-- Dark and light background image support -->
<div class="image-placeholder">

API Methods

The API methods of KTThemeModeclass defined in src/js/layout/theme-mode.js:
Name Description
getMode() Returns current theme mode as string
// Returns "dark" or "light" string value.
var mode = KTThemeMode.getMode();
getMenuMode() Returns the theme switcher menu's current selection mode as string
// Returns "dark", "light" or "system" string value.
var mode = KTThemeMode.getMenuMode();
getSystemMode() Returns the browser's mode as string
// Returns "dark" or "light" string value.
var mode = KTThemeMode.getSystemMode();
setMode(String mode) Sets a mode to change the theme mode

API Events

The API events of KTThemeModeclass defined in src/js/layout/theme-mode.js:
Event Type Description
kt.thememode.init This event fires on the theme mode initialization right after the page load.
// Register an event handler
var handlerId = KTThemeMode.on("kt.thememode.init", function() {
    console.log("Initialized init:" + KTThemeMode.getMode());
kt.thememode.change This event fires on previous navigation button click.
// Register an event handler
var handlerId = KTThemeMode.on("kt.thememode.change", function() {
    console.log("Theme mode is changed:" + KTThemeMode.getMode());

// Unregister the event handler after 10 seconds
setTimeout(function() {"kt.thememode.change", handlerId);
}, 1000 * 10);