How to Customize AdminLTE 4: Colors, Layout, and Dark Mode

AdminLTE 4 (currently at release candidate 7) ships with a completely revamped customization system compared to version 3. Gone are the old skin classes and rigid color schemes. In their place, AdminLTE 4 uses CSS custom properties with a --lte- prefix, SCSS variables with a $lte- prefix, and Bootstrap 5.3’s native color mode system for dark mode support. If you’ve customized AdminLTE 3 before, you’ll find the new approach more flexible and far more maintainable.

This guide covers everything you need to customize AdminLTE 4 for your project — from changing brand colors and sidebar skins to enabling dark mode, adjusting layout options, and even building runtime-switchable themes with CSS custom properties. Whether you’re building an internal dashboard or a SaaS admin panel, these techniques will help you make AdminLTE look and feel like your own product.

---

Setting Up Your Development Environment

Before customizing anything, you need a working AdminLTE 4 development environment. Install the latest release candidate via npm:

npm install [email protected]

AdminLTE 4 includes a built-in development server powered by Vite. Start it with:

npm start

This launches a dev server at localhost:3000 with hot module replacement, so your changes appear instantly in the browser.

SCSS Source Structure

The SCSS source files live in src/scss/ and follow a well-organized structure:

src/scss/
  _bootstrap-variables.scss   # Sits between Bootstrap's functions and variables
  _variables.scss             # All AdminLTE-specific $lte- variables
  _variables-dark.scss        # Dark mode overrides
  _layout.scss                # Sidebar, header, footer layout
  _sidebar.scss               # Sidebar-specific styles
  _components.scss            # Cards, widgets, UI components
  adminlte.scss               # Main entry point that imports everything

The key file to understand is _bootstrap-variables.scss. It loads after Bootstrap’s _functions.scss but before Bootstrap’s _variables.scss, which means it can override Bootstrap’s default values before they cascade through the rest of the framework. This is how AdminLTE maps its own color system onto Bootstrap’s.

Creating a Custom SCSS File

The recommended approach is to create your own SCSS entry point that overrides variables before importing AdminLTE:

// custom.scss

// 1. Override AdminLTE variables BEFORE importing
$lte-primary: #1a73e8;
$lte-sidebar-bg: #1e293b;
$lte-header-bg: #ffffff;

// 2. Import AdminLTE (which imports Bootstrap internally)
@import "admin-lte/src/scss/adminlte";

Compile it with Sass:

npx sass custom.scss dist/css/custom-adminlte.css

This gives you a single CSS file with your branding applied throughout the entire framework.

---

Customizing Colors with SCSS Variables

AdminLTE 4 exposes dozens of SCSS variables that control every color in the interface. They all use the $lte- prefix to avoid collisions with Bootstrap’s own variables. Here are the most important ones from _variables.scss:

// Brand colors
$lte-primary:       #0d6efd;
$lte-secondary:     #6c757d;
$lte-success:       #198754;
$lte-info:          #0dcaf0;
$lte-warning:       #ffc107;
$lte-danger:        #dc3545;

// Sidebar
$lte-sidebar-bg:                  #343a40;
$lte-sidebar-color:               #c2c7d0;
$lte-sidebar-hover-bg:            rgba(255, 255, 255, 0.1);
$lte-sidebar-hover-color:         #ffffff;
$lte-sidebar-active-color:        #ffffff;
$lte-sidebar-submenu-bg:          transparent;
$lte-sidebar-submenu-color:       #c2c7d0;

// Header
$lte-header-bg:                   #ffffff;
$lte-header-color:                #343a40;
$lte-header-border-bottom:        1px solid #dee2e6;

// Footer
$lte-footer-bg:                   #ffffff;
$lte-footer-color:                #343a40;
$lte-footer-border-top:           1px solid #dee2e6;

Creating a Custom Color Scheme

Here is a complete example that transforms AdminLTE into a branded dashboard with a teal primary color and a dark navy sidebar:

// my-brand.scss

// Brand palette
$brand-navy:    #0f172a;
$brand-teal:    #0d9488;
$brand-slate:   #334155;
$brand-light:   #f1f5f9;

// Override AdminLTE variables
$lte-primary:                     $brand-teal;
$lte-sidebar-bg:                  $brand-navy;
$lte-sidebar-color:               #94a3b8;
$lte-sidebar-hover-bg:            rgba(255, 255, 255, 0.08);
$lte-sidebar-hover-color:         #e2e8f0;
$lte-sidebar-active-color:        #ffffff;
$lte-sidebar-submenu-color:       #64748b;
$lte-header-bg:                   #ffffff;
$lte-header-border-bottom:        1px solid #e2e8f0;
$lte-footer-bg:                   $brand-light;

// Import AdminLTE
@import "admin-lte/src/scss/adminlte";

With roughly ten variable overrides, you get a completely different-looking dashboard that still benefits from all of AdminLTE’s layout and component styles.

The _bootstrap-variables.scss file is worth examining if you need deeper control. It maps AdminLTE’s $lte- variables to Bootstrap’s $ variables (like $primary, $body-bg, etc.), so overriding an AdminLTE variable automatically flows through to every Bootstrap component that references the corresponding value.

---

Sidebar Skins

AdminLTE 4 supports both light and dark sidebars. The approach uses Bootstrap 5.3’s color mode system rather than the old sidebar-dark / sidebar-light classes from v3.

Light vs Dark Sidebar

To create a dark sidebar, add data-bs-theme="dark" to the .app-sidebar element:

<aside class="app-sidebar" data-bs-theme="dark">
  <!-- Sidebar content -->
</aside>

For a light sidebar, either omit the attribute or set it to "light":

<aside class="app-sidebar" data-bs-theme="light">
  <!-- Sidebar content -->
</aside>

This approach is powerful because the data-bs-theme attribute scopes the color mode to just the sidebar. The rest of your page can remain in light mode while the sidebar uses dark mode — or vice versa.

Custom Sidebar Colors

For a fully branded sidebar, override the $lte-sidebar-* variables. Here is an example that creates a deep purple branded sidebar:

// Purple branded sidebar
$lte-sidebar-bg:                  #1e1033;
$lte-sidebar-color:               #b8a9cc;
$lte-sidebar-hover-bg:            rgba(167, 139, 250, 0.15);
$lte-sidebar-hover-color:         #e9d5ff;
$lte-sidebar-active-color:        #ffffff;
$lte-sidebar-active-bg:           rgba(167, 139, 250, 0.2);
$lte-sidebar-submenu-bg:          rgba(0, 0, 0, 0.15);
$lte-sidebar-submenu-color:       #9f8bbd;
$lte-sidebar-submenu-hover-color: #e9d5ff;

@import "admin-lte/src/scss/adminlte";

Pay attention to hover and active states — they are what make a sidebar feel polished. Subtle background shifts (using rgba() values) tend to look more refined than solid color changes. And don’t forget submenu colors, which should be slightly muted compared to top-level items to create visual hierarchy.

---

Layout Options

AdminLTE 4 provides several layout configurations through CSS classes and data attributes on the <body> element and specific components.

Fixed Sidebar, Header, and Footer

The sidebar is fixed (sticky) by default in AdminLTE 4. The header and footer can be made fixed by adding classes to the body:

<!-- Fixed header -->
<nav class="app-header navbar navbar-expand sticky-top">
  <!-- Header content -->
</nav>

<!-- Fixed footer -->
<footer class="app-footer sticky-bottom">
  <!-- Footer content -->
</footer>

Sidebar Mini (Collapsed Icon-Only Mode)

The sidebar mini mode collapses the sidebar to show only icons. Add the sidebar-collapse class to the <body> to trigger it:

<body class="sidebar-collapse">

When collapsed, the sidebar shows only the icons from your nav links. On hover, it expands temporarily to reveal the full text. This is controlled automatically by AdminLTE’s JavaScript.

Responsive Sidebar Behavior

Use the sidebar-expand-{breakpoint} class on the .app-sidebar to control when the sidebar switches between full and collapsed modes:

<!-- Sidebar expands at lg breakpoint (992px) -->
<aside class="app-sidebar sidebar-expand-lg" data-bs-theme="dark">

Available breakpoints follow Bootstrap’s system: sm, md, lg, xl, xxl. Below the specified breakpoint, the sidebar becomes an off-canvas overlay.

Sidebar State Persistence

AdminLTE 4 can remember whether the user collapsed or expanded the sidebar across page loads. Enable it with a data attribute:

<aside class="app-sidebar sidebar-expand-lg"
       data-enable-persistence="true">

This stores the sidebar state in localStorage, so the user’s preference persists between sessions.

Sidebar Without Hover Expand

New in rc7, you can disable the hover-to-expand behavior on the collapsed sidebar. This keeps the sidebar in its icon-only state even when the user hovers over it:

<body class="sidebar-collapse sidebar-no-expand">

This is useful for dashboards where screen real estate is critical and users primarily navigate via the icon-only sidebar.

Compact Mode

AdminLTE 4 includes a compact mode that reduces padding and font sizes throughout the interface, fitting more content on screen:

<body class="compact-mode">

Compact mode is particularly useful for data-heavy dashboards where users need to see as many rows and widgets as possible without scrolling.

---

Dark Mode

AdminLTE 4 builds on Bootstrap 5.3’s native color mode system, giving you three options out of the box: light, dark, and auto.

Enabling Dark Mode

Set the data-bs-theme attribute on the <html> element to switch the entire interface:

<!-- Light mode (default) -->
<html data-bs-theme="light">

<!-- Dark mode -->
<html data-bs-theme="dark">

Auto Mode with prefers-color-scheme

Auto mode respects the user’s operating system preference. You can implement it with a small JavaScript snippet:

function applyAutoTheme() {
  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
  document.documentElement.setAttribute('data-bs-theme', prefersDark ? 'dark' : 'light');
}

// Apply on load
applyAutoTheme();

// Listen for OS theme changes
window.matchMedia('(prefers-color-scheme: dark)')
  .addEventListener('change', applyAutoTheme);

The _variables-dark.scss File

AdminLTE’s _variables-dark.scss defines color overrides that activate when data-bs-theme="dark" is set. It adjusts background colors, text colors, border colors, and component-specific values to ensure readability and visual comfort in dark mode. If you need to customize dark mode colors specifically, override variables in this file’s scope:

@include color-mode(dark) {
  --lte-sidebar-bg: #0f172a;
  --lte-header-bg: #1e293b;
  --lte-card-bg: #1e293b;
}

Adding a Dark Mode Toggle

Here is a practical dark mode toggle button that cycles through light, dark, and auto modes:

<button id="theme-toggle" class="btn btn-outline-secondary btn-sm"
        type="button" aria-label="Toggle color mode">
  <i id="theme-icon" class="bi bi-circle-half"></i>
</button>

<script>
const themeToggle = document.getElementById('theme-toggle');
const themeIcon = document.getElementById('theme-icon');
const modes = ['light', 'dark', 'auto'];
let currentMode = localStorage.getItem('theme') || 'auto';

function setTheme(mode) {
  currentMode = mode;
  localStorage.setItem('theme', mode);

  if (mode === 'auto') {
    const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
    document.documentElement.setAttribute('data-bs-theme', prefersDark ? 'dark' : 'light');
  } else {
    document.documentElement.setAttribute('data-bs-theme', mode);
  }

  // Update icon
  const icons = { light: 'bi-sun-fill', dark: 'bi-moon-stars-fill', auto: 'bi-circle-half' };
  themeIcon.className = 'bi ' + icons[mode];
}

themeToggle.addEventListener('click', function () {
  const nextIndex = (modes.indexOf(currentMode) + 1) % modes.length;
  setTheme(modes[nextIndex]);
});

// Listen for OS changes when in auto mode
window.matchMedia('(prefers-color-scheme: dark)')
  .addEventListener('change', function () {
    if (currentMode === 'auto') setTheme('auto');
  });

// Apply saved theme on load
setTheme(currentMode);
</script>

Dark Mode Design Tips

A few practical tips for getting dark mode right:

• Reduce saturation. Bright, saturated colors that look great on a white background can feel harsh in dark mode. Desaturate your accent colors slightly or use lighter tints.
• Avoid pure black. A #000000 background creates excessive contrast and causes visual fatigue. Use dark grays like #1e293b or #0f172a instead.
• Rethink shadows. Box shadows are essentially invisible against dark backgrounds. In dark mode, use subtle borders or slightly lighter background tones to create depth and separation between elements.
• Test with real content. Dark mode issues tend to surface with charts, images with white backgrounds, and third-party embeds. Test with your actual dashboard content, not just placeholder text.

---

CSS Custom Properties for Runtime Theming

One of the most powerful features in AdminLTE 4 is its use of CSS custom properties (variables) with the --lte- prefix. While SCSS variables are compiled away at build time, CSS custom properties exist at runtime — meaning you can change them with JavaScript without recompiling anything.

The –lte- Prefix System

AdminLTE maps its SCSS variables to CSS custom properties during compilation. This means every $lte- SCSS variable has a corresponding --lte- CSS property that you can manipulate in the browser:

/* These are set by AdminLTE's compiled CSS */
:root {
  --lte-primary: #0d6efd;
  --lte-sidebar-bg: #343a40;
  --lte-sidebar-color: #c2c7d0;
  --lte-header-bg: #ffffff;
}

Changing Theme Colors at Runtime

You can override these properties with JavaScript to create user-selectable themes without any build step:

function applyTheme(theme) {
  const root = document.documentElement;
  root.style.setProperty('--lte-primary', theme.primary);
  root.style.setProperty('--lte-sidebar-bg', theme.sidebarBg);
  root.style.setProperty('--lte-sidebar-color', theme.sidebarColor);
  root.style.setProperty('--lte-header-bg', theme.headerBg);
}

// Example: apply a blue corporate theme
applyTheme({
  primary: '#1a73e8',
  sidebarBg: '#1e293b',
  sidebarColor: '#94a3b8',
  headerBg: '#ffffff'
});

// Example: apply a green nature theme
applyTheme({
  primary: '#059669',
  sidebarBg: '#064e3b',
  sidebarColor: '#a7f3d0',
  headerBg: '#f0fdf4'
});

This technique is ideal for SaaS applications where each customer needs their own branding, or for dashboards with a theme selector in the settings panel. Store the user’s chosen theme in localStorage or your database, and apply it on page load.

---

RTL Support

AdminLTE 4 includes built-in RTL (right-to-left) support via rtlcss. This is essential for languages like Arabic, Hebrew, Farsi, and Urdu.

To enable RTL, add the dir attribute to your HTML element and use the RTL version of the stylesheet:

<html lang="ar" dir="rtl">
<head>
  <link rel="stylesheet" href="dist/css/adminlte.rtl.css">
</head>

The RTL stylesheet is generated automatically during AdminLTE’s build process. It mirrors all directional properties — margins, paddings, floats, text alignment, and positioning — so your layout reads correctly from right to left without any manual CSS adjustments.

---

Useful Tools

Customizing a dashboard theme is easier with the right tools in your workflow:

• Coolors.co — Generate cohesive color palettes quickly. Start with your brand’s primary color and let it suggest complementary shades for your sidebar, header, and accent colors.
• WebAIM Contrast Checker — Verify that your text colors meet WCAG accessibility standards against your chosen backgrounds. Aim for at least a 4.5:1 ratio for body text and 3:1 for large text.
• Browser DevTools — Open the Elements panel and edit --lte- CSS custom properties in real time to preview color changes instantly. This is the fastest way to experiment before committing to SCSS variable overrides.
• Nord Theme — A well-regarded arctic color palette that works beautifully for dark mode dashboard designs. Its muted tones reduce eye strain while maintaining visual clarity.

---

Conclusion

AdminLTE 4 gives you a layered customization system that scales from quick color tweaks to full white-label theming. SCSS variables let you define your brand at build time, CSS custom properties enable runtime theme switching, and Bootstrap 5.3’s color mode system provides dark mode with minimal effort. Combined with layout options like sidebar mini, compact mode, and state persistence, you have everything you need to tailor the dashboard to your project’s requirements.

For the complete list of available variables and layout classes, check the official AdminLTE 4 documentation. You can also browse the source code and report issues on the AdminLTE GitHub repository. If you are starting a new project, grab the latest release candidate and start experimenting — the customization system is stable and the upgrade path to the final 4.0 release will be straightforward.