Migrate to AdminLTE 4 / Bootstrap 5

[PromoFaux]

Summary

Migrates the web interface from AdminLTE 2.4.18 / Bootstrap 3.4.1 to AdminLTE 4 / Bootstrap 5, and upgrades the other frontend dependencies that no longer had a Bootstrap-3-era version to pair with (bootstrap-select → Tom Select, bootstrap-toggle → bootstrap5-toggle, icheck-bootstrap → native .form-check, DataTables/select2 to their -bs5 builds, plus Font Awesome and remaining vendor bumps).

• Layout shell (49f6bd0d): .wrapper/.main-header/.main-sidebar/.content-wrapper → AdminLTE4's .app-wrapper/.app-header/.app-sidebar/.app-main/.app-content.
• Box → Card (b0d95fcd): mechanical but reviewed conversion across all 19 affected templates, including collapse widgets and color variants.
• Checkboxes/radios (6657d28a): dropped icheck-bootstrap for Bootstrap 5's native .form-check/.form-switch.
• JS plugin swaps (6deb2e79): DataTables/select2 to -bs5 builds, bootstrap-select rewritten against Tom Select, bootstrap-toggle swapped for the maintained bootstrap5-toggle fork, jquery-confirm/daterangepicker/bstreeview class names updated for BS5.
• Font Awesome v7 + theme rename (42646493).
• Tab-switching fix (b049ef9a): Bootstrap 5's Tab component tracks the active state on the link itself, not the surrounding <li>.
• Regression fixes from manual QA (9f1d2155, afd69379, 075921f4): boxed layout, badge alignment, settings/tools sidebar submenus navigating away instead of expanding, white flash between page loads on the auto theme, day theme rendering dark, a bootstrap5-toggle initialization deadlock that silently broke the Basic/Expert and All/Modified settings toggles, the All Settings tab bar's layout, and several CSP img-src 'self' violations from Bootstrap 5 (and its plugins') inline data: URI icons — re-hosted as local SVGs so nothing is blocked by FTL's webserver CSP.

Why

AdminLTE's maintainers are explicit that v3→v4 has no incremental upgrade path, so this necessarily touches nearly every .lp template. Bootstrap 3 is long past EOL and several of the jQuery plugins we depended on (bootstrap-select, bootstrap-toggle) have no Bootstrap-5-compatible fork from their original maintainers, so those needed replacement rather than a version bump.

Test plan

• npm run test (prettier + xo) passes with only pre-existing warnings, no new errors
• Manually verified via Docker + browser walkthrough across dashboard, query log (filters, live update, on-disk toggle), groups (clients/domains/lists), network, settings (DNS/DHCP/API/system/teleporter/privacy/all settings), in both light and dark theme
• Verified zero browser console errors across all pages after the CSP icon fixes
• Additional community/maintainer testing on real hardware, given the size of this change

Notes for reviewers

This is a large, mechanical-but-reviewed diff by nature of the v3→v4 jump. Opening as a draft for early feedback on direction before final polish.

[yubiuser]

early feedback on direction before final polish.

I love that you made a step in this direction. It's a good thing to modernize our code base. Reviewing will take some time, but this can be Pi-hole v7 (web) one day

[PromoFaux]

It wasn't going to happen any time soon without some heavy AI legwork! It's clearly not perfect - I've not looked at all the themes, and some of the elements are going to need a bit of polish

[rdwebdesign]

There are other differences between v2.4 and the new v4, not described above.

Examples:

• v2.4 (and bootstrap 3) use float property for layout and positioning elements.
  v4 (and bootstrap 5) remove CSS float rules for layout, replacing them with CSS Flexbox.
  This will probably require a lot of changes to the margins, padding and fine adjustments to the position of some elements.

• v4 has no concept of "boxed-layout".
  Do we really need it?
  If used, should it be the default one? or should we use the expanded layout as default?
  Recently I found out that some users don't even know the theme can use the whole screen width.

• The original v4 theme has a dark mode (v2.4 had only a light theme and we manually created the other themes).
  This is probably not an issue, but maybe we can adjust/simplify the themes if we use the correct classes for dark themes, reducing the number of CSS rules on each theme.

• v4 uses CSS custom properties (CSS variables).
  This will simplify a lot all the themes.
  We will just need to change the variables (instead of adding many new rules). Anyway, we will need to rewrite the themes.
  Another possibility would be to edit the Sass files to generate our themes, but I think it will be easier if we keep using pure CSS files.

[darkexplosiveqwx]

I tried to do some migrations individually and step-by-step, starting with #3663, but the amount of strange breaking changes ended up too much for me.
Doing all of those migrations at one seems very logical to me.
Will close #3663 and much rather help testing this approach.

[github-actions]

This pull request has conflicts, please resolve those before we can evaluate the pull request.

[github-actions]

Conflicts have been resolved.

[DL6ER]

Merged current development in and resolved the conflicts, so the Merge Conflicts label should clear now.

The only real overlap was Font Awesome: both branches had independently bumped it to v7 (development to 7.0.0 via #3573, this branch to 7.3.0). I kept 7.3.0 here, since that is what the rest of the migration was built and tested against, and took its vendored CSS/webfonts. package.json/package-lock.json otherwise keep this branch's AdminLTE 4 / Bootstrap 5 dependency set.

While I was at it I went back over the whole UI on the merged branch to make sure nothing regressed:

• Every page in the day and midnight themes, plus deep-midnight, both high-contrast themes and LCARS - no console errors and no CSP or asset failures anywhere.
• The plugin swaps that carried the most risk all behave: the Tom Select group selectors (open, select, remove, select-all/none), the bootstrap5-toggle Basic/Expert and All/Modified switches, the Bootstrap 5 collapse cards, and the tab switching on the domains page.
• npm run test passes (prettier clean, xo with only the pre-existing complexity/max-params warnings, no new ones).

Nothing functional left blocking from my side. The remaining polish - leaning the themes harder on AdminLTE 4's CSS variables, and whether boxed should stay the default - reads more like discussion than blockers to me, so I have left those as they are for now.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[DL6ER]

Marking this ready. I have merged current development in and gone back over the whole UI on the merged branch - every page in all themes, and the plugin swaps that carried the most risk (Tom Select, bootstrap5-toggle, the collapse cards and tab switching) - and I am happy with where it is.

Approving from my side. Leaving the actual merge for now so we get a chance for wider testing, and for @rdwebdesign's remaining theme/boxed points to be settled.

[darkexplosiveqwx]

Marking this ready. I have merged current development in and gone back over the whole UI on the merged branch - every page in all themes, and the plugin swaps that carried the most risk (Tom Select, bootstrap5-toggle, the collapse cards and tab switching) - and I am happy with where it is.

Approving from my side. Leaving the actual merge for now so we get a chance for wider testing, and for @rdwebdesign's remaining theme/boxed points to be settled.

I have checked out this web branch on my local install and think that there are quite a few things needing refinement.
Would you consider this stable enough from large changes that I can do some testing?

Some inital testing feedback (will provide more context, if testing is wanted):

• login page shows 2FA, even when disabled
• if no diagnostics are available, it still shows the orange notification bubble, just without any number

[DL6ER]

Would you consider this stable enough from large changes that I can do some testing?

Yes, that's also what I meant: ready for going into development (this branch is allowed to break, jus not heavily) - I didn't mean it like production-ready for release. From there, smaller refinements seem easier than working in an ever growing monolith PR where individual stuff becomes really hard to review.

[rdwebdesign]

I think we could add more adjustments before merging this PR.

I'll take a look at it over the next few days, but I see no reason to rush it.

[DL6ER]

True, I will prepare a few polishing commits and push it to this branch. Should give a better basis for discussion.

[DL6ER]

It should look nicer now. My sweep for improvements for this PR is through now and I'd be good to merge into development for further refinements.

[darkexplosiveqwx]

It should look nicer now. My sweep for improvements for this PR is through now and I'd be good to merge into development for further refinements.

The two obvious issues I raised are fixed.
I now mainly notice: a few misalignments and that a some colors look a bit off
I won't consider this a blocker.

[rdwebdesign]

Search Lists page is broken.

Fixed by 3c68d2c

[rdwebdesign]

I fixed some issues on the top bar and sidebar layout:

[yubiuser]

Disabling is not possible once activated

[rdwebdesign]

@yubiuser

Thanks for testing.

Make it look 1:1 like the old interface, or accept small visual changes but still make it visual appealing?

Personally, I think we shouldn't try to achieve the exact same visual. It is a new theme. It will have a different visual.

Also, some of the small differences will be handled before thee migration is completed.

• the colors are different because AdminLTE changed the default colors. We can (and should) add our own colors, but this can be done later.
• The font size is bigger because the new theme uses a different font and the new default size for web: 16px. I changed it to 15px. Bigger fonts are better on phones (easier to click , even with fat fingers).
• The buttons are bigger because the new theme uses different margins and padding sizes. We can adjust some of them.
• the buttons on the bottom (you called boxes) are not inverted. They are just using the new colors.
  We need to use a different classes to select the desired colors. Also, we will adjust the colors for all themes.
  This will be done later, too.

The sidebar now opens not only on click, but also on mouse over - do we want to keep this?

This is how the new theme works.

Maybe we could disable the "open on hover" effect. We need to test the alternatives.

---

The layout for datatables elements (number of entries per page, search, pagination) needs a separated PR, after this one is merged.

Disabling is not possible once activated

Actually, these buttons are working (they will work if you try to click on the minute button and then submit). The issue are the styles: the colors are not changing.
We need to check, but I guess this is related to different class names used by the new theme.

[yubiuser]

Ok, how does the team continue with this PR. Merge soon and fix things piece by piece in separate PRs or fix the most obvious issues before?

[yubiuser]

The text next to the input fields is broken on mobile.

[yubiuser]

On the sidebar:

1. Old behavior was that submenus collaps when a new submenu is opened. Now all submenus stay open
2. On mobile there is a glitch: when you open a long submenu you can scroll down on the sidebar, but not until the end (Donate is hidden). One must first scroll down on the page which will show a truncated sidebar that is then rendered completely until the bottom.

[rdwebdesign]

Ok, how does the team continue with this PR

I'm pinging you in our MM conversation.

[rdwebdesign]

On the sidebar:

1. Old behavior was that submenus collaps when a new submenu is opened. Now all submenus stay open

2. On mobile there is a glitch: when you open a long submenu you can scroll down on the sidebar, but not until the end (Donate is hidden). One must first scroll down on the page which will show a truncated sidebar that is then rendered completely until the bottom.

This is how the new AdminLTE sidebar works.

Some differences:

• when the old sidebar is collapsed, you can use the mouse to open just a single submenu:
  
  Now, the whole new sidebar opens if you use the mouse pointer.

• the old sidebar only keeps one submenu open at a time. The new one doesn't close the other submenus.

• the old sidebar used indented submenus with a different background color:
  
  The new version uses only different icons for different levels, same background:
  
  I intend to create a different style for multilevel items.

[rdwebdesign]

@yubiuser

I think we can change the submenu layout to something like this:
or

Just a quick example. It needs fine tuning for borders, padding, margin, etc.

What do you think?

[yubiuser]

What do you think?

I think your right example (having two lighter colors) would improve the situation. I still prefer the indention for sub-menus.

---

I tried to allow/block a domain from the query log but the buttons don't work at all.

[yubiuser]

Dashboard bar graphs:

• pinch gesture on mobile does not work anymore
• pan does not work (but seems broken on development as well

Client/Domains/Lists

• Assigning a group to a Client: when only one non-default group exists, and client is already part of "Default", the non-default group can't be selected

Settings/API

• 2FA QR code not shown on generation

[rdwebdesign]

Thanks.

The Graphics zoom can be checked later, but the group selector is broken. I tested and when I removed all groups, I couldn't re-add groups anymore.

[darkexplosiveqwx]

The popup when flushing the network table cannot be closed:

Screencast.From.2026-07-27.23-17-43.mp4

(You cannot see my mouse, but you can see the buttons reacting and it not closing)

The "Yes, ..." button does in fact trigger the API action.

[github-actions]

This pull request has conflicts, please resolve those before we can evaluate the pull request.

[github-actions]

Conflicts have been resolved.