Theming & Dark Mode

The bundle ships SSR-safe dark mode built on Bootstrap 5.3's data-bs-theme. The theme is applied before the body paints (no flash), persisted to localStorage, and follows the OS preference while on auto.

How it works

A tiny inline script is included in <head> by the base layout (from _color_mode_script.html.twig). Before anything renders, it reads the stored preference and sets data-bs-theme on <html>. The key points:

The persisted value lives under localStorage['lte-theme'] — the same key shared with the Vue, React and Angular ports.
The initial default comes from color_mode in your config (light, dark or auto).
On auto, the script resolves to the OS preference via prefers-color-scheme and keeps tracking it until the user makes an explicit choice.
Toggling dispatches an adminlte:color-mode DOM event with the new value, so you can react to theme changes.

The toggle component

Drop <twig:Adminlte:ColorModeToggle /> anywhere inside the layout (it is already in the default topbar). It flips the theme by calling the global the head script exposes:

<twig:Adminlte:ColorModeToggle />

Programmatically, call the same function from any of your own controls:

if (window.adminlteToggleColorMode) {
    window.adminlteToggleColorMode();
}

A Stimulus alternative ships at assets/controllers/color-mode_controller.js if you prefer a controller-driven toggle over the inline global.

Setting the default mode

admin_lte:
    color_mode: dark   # light | dark | auto

This becomes the fallback the head script uses when nothing is stored yet. Once a user toggles, their explicit choice in localStorage wins on every subsequent visit.

Customizing colors

AdminLTE 4 is built on Bootstrap 5.3 CSS variables, so override theme colors with standard Bootstrap custom properties — scoped to a theme if needed:

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

The bundle exposes its stylesheet through the ./css package export, so you can import the AdminLTE CSS into your own SCSS/CSS build and layer your overrides on top. Add your custom CSS via the layout's stylesheets block (use {{ parent() }} to keep the base styles).

Because the theme is set on <html> before the body paints, your overrides must be valid for both [data-bs-theme="light"] and [data-bs-theme="dark"] to avoid a mismatch when users switch.

AdminLTE 4 · Symfony port Edit on GitHub