Theming & Dark Mode

Dark mode is built on Bootstrap 5.3's data-bs-theme. The ColorModeProvider (mounted automatically inside DashboardLayout) sets the theme on <html>, resolves auto from the OS preference, and persists the user's choice to localStorage.

How it works

The provider supports three modes — light, dark, auto.
On auto it resolves to the OS preference via prefers-color-scheme and keeps tracking it live with a matchMedia listener.
The resolved mode is written to document.documentElement as data-bs-theme="light|dark".
The selected mode is persisted under localStorage['lte-theme'] — the same key shared with the Vue, Symfony and Angular ports.

Setting the starting mode

Pass initialColorMode to DashboardLayout (it forwards to the provider). On mount, any persisted lte-theme value wins over this default:

<DashboardLayout menuItems={menuItems} initialColorMode="dark">
  {children}
</DashboardLayout>

Or mount the provider directly (e.g. for an auth area outside the dashboard):

import { ColorModeProvider } from '@adminlte/react'

<ColorModeProvider initialMode="dark">{children}</ColorModeProvider>

The toggle

The topbar's light/dark toggle is on by default (colorModeToggle prop). To place one elsewhere, use the exported ColorModeToggle, or drive the mode yourself from a client component via the context hook:

'use client'
import { useColorModeContext } from '@adminlte/react'

function ThemeButtons() {
  const { colorMode, setColorMode, resolvedMode } = useColorModeContext()
  return (
    <div className="btn-group">
      <button className="btn btn-sm" onClick={() => setColorMode('light')}>Light</button>
      <button className="btn btn-sm" onClick={() => setColorMode('dark')}>Dark</button>
      <button className="btn btn-sm" onClick={() => setColorMode('auto')}>Auto</button>
      <span className="ms-2">current: {colorMode} → {resolvedMode}</span>
    </div>
  )
}

useColorModeContext() returns { colorMode, setColorMode, resolvedMode }, where resolvedMode is the concrete 'light' | 'dark' after resolving auto.

Customizing colors

AdminLTE 4 is built on Bootstrap 5.3 CSS variables, so override theme colors with standard Bootstrap custom properties — scope per-theme where needed — in your globals.css:

:root {
  --bs-primary: #6610f2;
  --bs-primary-rgb: 102, 16, 242;
}
[data-bs-theme="dark"] {
  --bs-body-bg: #14181f;
}

Import order matters: import @adminlte/react/css before your own stylesheet so your overrides win.

Because the provider applies data-bs-theme in a client effect, plan for an SSR-safe default. Pick a sensible initialColorMode for your app; the persisted choice is read on mount and takes over on subsequent renders. Keep overrides valid for both [data-bs-theme="light"] and [data-bs-theme="dark"] so switching never mismatches.

AdminLTE 4 · React port Edit on GitHub