jQuery Migration

Current State

As of v4.8.1, ArchitectUI ships jQuery 3.7.1 as a compatibility layer for plugins that haven't yet been replaced. Roughly 76% of the original jQuery plugin dependency footprint has been removed, leaving four remaining holdouts (MetisMenu, Slick Carousel, Fancytree, Bar Rating) where vanilla alternatives don't yet match the feature set.

Replacements Already Shipped

The following plugins have been removed from package.json and replaced with native or vanilla alternatives. Use the replacement when adding new code — do not reintroduce the deprecated plugins.

What Still Depends on jQuery

Four plugins still require jQuery at runtime:

Additionally, src/app.js still uses jQuery for selectors and event delegation in many places — the file is on the migration roadmap but hasn't been touched yet.

The Custom Dropdown Portal

ArchitectUI's biggest custom JavaScript is the dropdown portal logic in src/app.js (lines 139–234). It replaces Bootstrap's native dropdown plugin with a delegation-based handler that "portals" page dropdowns to document.body to escape parents with overflow: hidden or transform stacking contexts.

Header dropdowns (anything inside .app-header, .header-megamenu, .header-dots, or .header-btn-lg) are left in place because they need to inherit header styling.

Implementation Pattern

document.addEventListener('click', function(event) {
                    var trigger = event.target.closest('[data-bs-toggle="dropdown"]');
                
                    if (trigger) {
                        event.preventDefault();
                        event.stopPropagation();
                
                        // Close any other open dropdowns first
                        // ...
                
                        var menu = trigger.nextElementSibling;
                        var isHeaderDropdown = trigger.closest(
                            '.app-header, .header-megamenu, .header-dots, .header-btn-lg'
                        );
                
                        if (isHeaderDropdown) {
                            // In-place show
                            menu.classList.add('show');
                        } else {
                            // Portal to body with position: fixed
                            var triggerRect = trigger.getBoundingClientRect();
                            menu._originalParent = menu.parentNode;
                            menu._originalNextSibling = menu.nextSibling;
                            document.body.appendChild(menu);
                            menu.style.position = 'fixed';
                            menu.style.top = (triggerRect.bottom + 2) + 'px';
                            menu.style.left = triggerRect.left + 'px';
                            menu.style.zIndex = '99999';
                            menu.classList.add('show');
                        }
                    }
                    // ...
                });

Writing New Code: Vanilla First

When adding new feature initializers under src/scripts-init/, prefer vanilla DOM APIs over jQuery. The pattern:

// src/scripts-init/my-feature.js
                
                document.addEventListener("DOMContentLoaded", function () {
                    const triggers = document.querySelectorAll("[data-my-feature]");
                    if (!triggers.length) return;     // safe no-op on pages without the trigger
                
                    triggers.forEach((trigger) => {
                        trigger.addEventListener("click", function (event) {
                            event.preventDefault();
                            // your code here
                        });
                    });
                });

API Mapping Cheat Sheet

Why jQuery Is Still Around

Two reasons:

• The four remaining plugins (MetisMenu, Slick, Fancytree, Bar Rating) require jQuery. Removing jQuery means replacing all four with vanilla alternatives, each of which is its own migration project.
• src/app.js has many jQuery callsites that still need to be ported — sidebar toggle, drawer toggle, search-icon click, popover initialization, etc. This is straightforward but tedious work that hasn't been scheduled yet.

Once both are resolved, jQuery can be removed entirely — ProvidePlugin entries cleaned out of webpack.config.js, the jquery dependency dropped from package.json, and the vendor bundle gets ~30 KB smaller.

Suppressing jQuery on a Specific Page

If you have a page that doesn't use any of the jQuery-dependent plugins, you can theoretically skip loading the main bundle. In practice this is rarely worth the complexity — HtmlWebpackPlugin's default behavior is to inject every entry into every page, and customizing per-page chunk selection requires touching webpack.config.js.

The cleaner answer is to wait until jQuery is fully removed.