adminlte v4.1.0 - disable ColorMode #6084

cytech · 2026-07-30T14:21:41Z

cytech
Jul 30, 2026

can anyone recommend how to disable the ColorMode in 4.1.0 (from dist, not rebuilding)?
my app has its own "themeing" mechanism and the ColorMode is overwriting the data-bs-theme that I set.
the only way i have gotten around it is to copy the node_modules/admin-lte/dist/js/adminlte.esm.js to my own resources, disable _applyTheme, and then vite the assets...

silkalns · 2026-07-30T14:44:45Z

silkalns
Jul 30, 2026
Maintainer

Hi @cytech — you're right that 4.1.0 has no supported opt-out, so your workaround isn't wrong, but you don't have to fork the bundle for it.

What ColorMode actually touches, so it's clear what has to be disabled:

on init (DOMContentLoaded, and again on every turbo:load): sets data-bs-theme and style.color-scheme on <html> from localStorage['lte-theme'], falling back to the OS preference
a delegated click listener on document for [data-bs-theme-value] → setTheme() (which also writes localStorage)
a matchMedia('(prefers-color-scheme: dark)') change listener that re-applies while the stored value is auto or unset

All three go through ColorMode.prototype._applyTheme, so a single no-op stub disables the lot — no rebuild.

ESM / Vite:

import { ColorMode } from 'admin-lte'

// 1. stop every future write: init, toggle clicks, OS changes
ColorMode.prototype._applyTheme = () => {}

// 2. undo the one write that already happened during the import (see below)
document.documentElement.setAttribute('data-bs-theme', myTheme)

That second line is the part that isn't obvious. A type="module" script — which is what Vite emits — is deferred, so document.readyState is already interactive by the time admin-lte is evaluated. AdminLTE therefore runs its init batch synchronously during the import rather than waiting for DOMContentLoaded, and a stub installed after the import statement lands one apply too late. Both statements run in the same task, so the browser never paints in between — no flash.

Classic <script> tag: here readyState is loading, init is deferred to DOMContentLoaded, and the stub on its own is enough:

<script src="/vendor/adminlte/adminlte.min.js"></script>
<script>
  adminlte.ColorMode.prototype._applyTheme = function () {}
</script>

Method names are preserved in the minified builds too (adminlte.min.js, adminlte.esm.min.js), so this works against dist exactly as shipped.

I checked all of this against the published 4.1.0 tarball in headless Chromium: with the snippet above, <html data-bs-theme="myapp-dark"> survives page load, a click on a [data-bs-theme-value] button, and an OS light→dark flip.

Simpler alternative if your themes are plain light/dark: skip the patching and keep the storage key in sync instead — localStorage.setItem('lte-theme', 'dark') before AdminLTE loads, and ColorMode resolves to the value you already wanted. Doesn't help for custom theme names, obviously.

One more thing to check: if your layout started from the demo HTML, there's also a small inline no-flash script in <head> that writes data-bs-theme before first paint (added in #6043). It's not part of the bundle, so the stub won't stop it — delete it if it's in your markup.

This should be first-class, though, not a prototype patch. I'll add an opt-out in 4.1.1 as an attribute on <html>, so it works straight from dist with no load-order concerns and no JS at all:

<html data-lte-color-mode="off">

ColorMode would skip its init pass, the toggle click handler, and the matchMedia listener; the no-flash head snippet in the demo layout would honor it too. Does that cover your case, or do you also need to call setTheme() programmatically from your own switcher?

0 replies

cytech · 2026-07-30T16:33:34Z

cytech
Jul 30, 2026
Author

thank you very much for the explanation.
I will give it a shot.

yes, i think your opt-out option would work for me.

I currently set a variable in laravel and pass that to the master.blade template.
i.e.
<html lang="{{ app()->getLocale() }}" dir="{{ app()->getLocale() == 'ar' ? 'rtl' : 'ltr' }}" data-bs-theme="{{$headBackground}}">
where $headBackground is something like "purple-light", "orange-dark", etc.
thanx again for quick answer
dave

0 replies

cytech · 2026-08-05T15:25:45Z

cytech
Aug 5, 2026
Author

follow up..
no-op stub in my app.js and then vite works fine for this release.
i'll keep an eye out for the <html data-lte-color-mode="off"> opt-out in 4.1.1
thank you

0 replies

puikinsh · 2026-08-05T19:12:10Z

puikinsh
Aug 5, 2026
Maintainer

Thanks for flagging this, @cytech — you were right that 4.1.0 gives you no way out, so forking the bundle wasn't a misuse of it. We've fixed it properly in #6095 rather than leaving you on a patch.

From the next release, applications with their own theming turn ColorMode off with one attribute:

<html data-lte-color-mode="off">

It never writes data-bs-theme after that — not on load, not when a [data-bs-theme-value] toggle is clicked, not when the OS preference changes — and the pre-paint snippet in <head> honours it too, so nothing touches your theme before first paint either. That also covers custom Bootstrap theme names like data-bs-theme="myapp-dark", which ColorMode can't resolve and would previously overwrite with light/dark.

Related, in case it suits you better than opting out: a theme you render server-side is now respected as a default. <html data-bs-theme="dark"> survives load and OS preference changes, and is only superseded once a visitor clicks a toggle themselves.

For 4.1.0 today, without forking the file — everything routes through ColorMode.prototype._applyTheme, so one stub disables all of it:

import { ColorMode } from 'admin-lte'

// 1. stop every future write: init, toggle clicks, OS changes
ColorMode.prototype._applyTheme = () => {}

// 2. undo the one write that already happened during the import (see below)
document.documentElement.setAttribute('data-bs-theme', myTheme)

That second line is the non-obvious part, and probably what pushed you to fork. A type="module" script — which is what Vite emits — is deferred, so document.readyState is already interactive when admin-lte is evaluated, and AdminLTE runs its init batch synchronously during the import rather than waiting for DOMContentLoaded. A stub installed after the import statement lands one apply too late. Both statements run in the same task, so the browser never paints in between — no flash.

With a classic <script> tag it's simpler, since readyState is loading and init is deferred to DOMContentLoaded:

<script src="/vendor/adminlte/adminlte.min.js"></script>
<script>
  adminlte.ColorMode.prototype._applyTheme = function () {}
</script>

Method names survive minification, so both work against dist as shipped.

One thing to check either way: if your layout started from the demo HTML, there's a small inline no-flash script in <head> that writes data-bs-theme before first paint. It isn't part of the bundle, so the stub above won't stop it — delete it, or upgrade and use the opt-out, which it now respects.

0 replies

cytech · 2026-08-05T19:52:47Z

cytech
Aug 5, 2026
Author

awesome
thanx

0 replies

Navigation Menu

Uh oh!

Uh oh!

adminlte v4.1.0 - disable ColorMode #6084

Uh oh!

{{title}}

Uh oh!

Replies: 5 comments

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

Uh oh!

adminlte v4.1.0 - disable ColorMode #6084

Uh oh!

cytech Jul 30, 2026

Replies: 5 comments

Uh oh!

silkalns Jul 30, 2026 Maintainer

Uh oh!

cytech Jul 30, 2026 Author

Uh oh!

cytech Aug 5, 2026 Author

Uh oh!

puikinsh Aug 5, 2026 Maintainer

Uh oh!

cytech Aug 5, 2026 Author

cytech
Jul 30, 2026

silkalns
Jul 30, 2026
Maintainer

cytech
Jul 30, 2026
Author

cytech
Aug 5, 2026
Author

puikinsh
Aug 5, 2026
Maintainer

cytech
Aug 5, 2026
Author