AdminThemeBridge – a native web-component admin that keeps your existing modules working (beta)

[theoretic]

AdminThemeBridge – a native web-component admin that keeps your existing modules working (beta)

Hi friends! And, traditionally, thanks for ProcessWire 😉

For a while I've been building something bigger than my usual in-house modules, and it's ready for other eyes now. Bridge (a working name) is an admin theme for ProcessWire that renders the admin with native web components and a small TypeScript runtime, without jQuery — while every existing Inputfield and Process module keeps working unchanged.

 

The goal

A better and faster admin. Faster: far less to download and run on every screen (numbers below). Better: an admin that feels current, in light and dark, with the small daily annoyances fixed. The name says how it gets there: Bridge is a bridge between the jQuery-era admin and the modern web stack. Everything that can be native already is, and your modules stay on their side of the bridge, working exactly as before.

Bridge against Uikit and AdminThemeBoss at a glance; the full table with all six themes is further down

The idea in one paragraph

The admin carries a lot of history: jQuery, jQuery UI, inputfields.js, WireTabs, Magnific. Thousands of modules rely on exactly that, so simply removing it is not an option. Bridge does it the other way round: the shell and the core screens are native, and the whole legacy stack is loaded only on the screens that need it — with the same globals ($, jQuery, ProcessWire.config, Inputfields) and the same reloaded event. A page whose fields are all native loads no jQuery at all; a page with a jQuery-era field gets the classic stack, and that field works as before.

What's native today

• the admin frame: masthead, navigation, notices, light and dark scheme
• most core fields: text, select, checkboxes, datetime, file, image (incl. crop and variations), repeater, page table, language tabs
• core screens: page tree, page editor (save without reload), Lister, Modules, Fields, Templates, Users, Roles, Permissions, Profile, Logs, Trash and the rest

Small things that got better

• Multi-level dropdown menus: a submenu stays open while you move the pointer to it, fits the screen height and opens to the left at the right edge. On a phone or tablet the first tap opens a menu instead of following its link, and menus work from the keyboard too.
• Long content scrolls where it is: a deep page-tree branch or a long menu scrolls inside itself instead of running off the bottom of the screen.
• Notices never cover the Save button. They have their own place above the content, so showing or closing one doesn't move the page, and a long one pushes the content down instead of overlapping it.
• Save without reload in the page editor, and in the field, template, module, user, role and profile editors (Shift+click still saves the classic way).
• No jumping content while the Lister loads, and no stacked tab panels flashing before the tabs are set up.
• The dark scheme reaches CKEditor, TinyMCE and the other field widgets. Focus rings and button text stay readable in every colour preset, and the top bar turns into a drawer when its items don't fit.

What stays exactly as it is

• wire/ is never edited or patched. Bridge is a regular module.
• DOM ids and classes, AJAX endpoints (?modal=1, ?render=JSON, renderInputfieldAjax), module class names and hookable methods are kept as upstream emits them, so your modules and hooks find what they expect.
• It's per user: Uikit stays installed, and anyone can switch back under Profile > Admin Theme.

How it's tested

A conformance suite renders every admin screen under Uikit and under Bridge and compares what modules see. On copies of nine real sites that's 1,434 screens with no differences caused by the theme, covering 41 of the 45 third-party modules installed there (FieldtypeMatrix, PageTableNext, VersionControl, Fluency, BatchChildEditor, SettingsFactory, AdminThemeBoss, ProcessWireUpgrade and others; the other four have admin screens that already fail the same way under Uikit on those copies, so there was nothing to compare). Behaviour checks run in Chromium and Firefox. It's also running on two live sites.

 

CKEditor and TinyMCE run through the legacy stack and still follow the dark scheme

Lighter and faster: the numbers

Lighthouse 12 (desktop preset), logged in, cold cache, median of 3 runs, on a copy of a real site. Average over four screens: page tree, page editor, Lister, Modules. Bridge 0.9.3.

	Bridge	Uikit	Uikit (2025 look)	AdminThemeBoss	Reno	Default
Lighthouse performance	98	69	66	81	83	77
Largest Contentful Paint	0.9 s	3.6 s	3.9 s	1.8 s	1.8 s	1.6 s
JavaScript (gzip)	38 kB	272 kB	273 kB	190 kB	186 kB	184 kB
CSS (gzip)	55 kB	118 kB	150 kB	59 kB	74 kB	70 kB
jQuery loaded	no	yes	yes	yes	yes	yes
Fonts	71 kB	237 kB	458 kB	75 kB	75 kB	75 kB

 

The same table as a picture; the forum editor's tables are fiddly

Fonts include Font Awesome 6 in full: Bridge serves the icons in common use from small subsets built at release time, and any other icon from the full font, so nothing goes missing. These are localhost numbers, so absolute times will be higher on a real server — the differences between themes are the point. On a screen with a jQuery-era field, that field brings its stack with it, as it should.

Want to check on your own site? Chrome DevTools → Lighthouse → Navigation, Desktop, Performance, and untick "Clear storage" in its settings (otherwise it logs you out and measures the login page).

Installation

Requires ProcessWire 3.0.227+ and PHP 8.1+ (developed against 3.0.274 dev).

1. Download the module from https://github.com/theoretic/AdminThemeBridge (Code > Download ZIP) into site/modules/AdminThemeBridge/, or git clone it there. It's the module only; development happens in https://github.com/theoretic/bridge. The modules directory listing is on its way.
2. Modules > Refresh, then install Bridge.
3. Select it under Profile > Admin Theme. Other users stay on their theme.

On a live site please back up the database first and read docs/install-live.md. Two things I learned the hard way: AdminThemeBoss's "activate for all users" must be off (it resets everyone to Uikit on each request), and a plain Modules > Refresh must complete before you install — a site module that loops during the cache rebuild has to be updated first.

For module authors

There is a small component contract (docs/contract.md) . Implement one interface and your Inputfield or Process runs natively too. If you don't, nothing breaks — your module simply gets the legacy stack, as today.

Known limits

• Beta (0.9.3). The contract is version 1 and may still change before 1.0.
• Pro modules (ProFields, FormBuilder, ListerPro) are not tested — I have no licences to test with, so I make no claims there.
• The name is a working name and may change.

What I'd love to hear

• Does your favourite module behave under Bridge? Screens that look or work differently are exactly what I'm looking for.
• Module authors: is the contract understandable, and what would you need from it?
• Anything about the look and the dark scheme.

Thanks

Bridge is mostly inspired by the perfect AdminThemeBoss by Noël Bossart, which was my default admin theme in every ProcessWire project before Bridge existed. Its colour presets (blue, vibrant, black, pink, green) are Bridge's colours, and its extended breadcrumbs are here too. Thank you, Noël!

Module: https://github.com/theoretic/AdminThemeBridge . Development, docs and changelog: https://github.com/theoretic/bridge (MIT; files derived from ProcessWire keep their MPL 2.0 header).

Advice and critics are welcome 😉

Edited Thursday at 05:01 AM by theoretic
layout imperfections; content unchanged

[adrian]

@theoretic - I absolutely love the idea of removing all those huge layers of cruft from the PW core, but I'll say what I have said whenever someone releases a new AdminTheme - it won't get used unless it's the core theme. But given the way you've built it so that it only loads legacy components as needed by other modules, perhaps it really could become the new core theme. I haven't tested it yet, but if it works flawlessly in that regard, I'd love to get behind it.

[theoretic]

7 hours ago, adrian said:

@theoretic - I absolutely love the idea of removing all those huge layers of cruft from the PW core, but I'll say what I have said whenever someone releases a new AdminTheme - it won't get used unless it's the core theme. But given the way you've built it so that it only loads legacy components as needed by other modules, perhaps it really could become the new core theme. I haven't tested it yet, but if it works flawlessly in that regard, I'd love to get behind it.

@adrian, thank You for Your kind words! I totally agree with You, and the whole Bridge project (not only the AdminBridge theme) is exactly about how to get rid of that JQuery era legacy code. I like how the Processwire core is made, and I think it truely deserves this. At admin level, the main problem will be the compatibility with modules (both native and 3rd-party), and, being fair, a huge part of Bridge is a compatibility layer allowing to run both legacy and modern (no JQuery / JQuery UI) modules. Of course I cannot test every module (thousands of them!), and actual Bridge is proved to run those I use in my own Processwire projects. Feel free to try Bridge with any module You have... and please don't smack me with a shovel if some of them will appear broken under Bridge 😉 Will appreciate any feedback!

[Jonathan Lahijani]

I've had this idea for a while now and thrilled to see this module.  Can't wait to play with it.  I agree that PW needs an admin modernization under the hood.

[diogo]

Well done! The theme feels great to use! A couple of issues that I noticed:

• Debug tools are always visible on some pages.
• Third level of the nav is hidden.
• "Add new template" button doesn't do anything.

👇 see screenshots

Spoiler

 

 

 

[theoretic]

AdminThemeBridge 0.9.5 is out

Thanks to everyone who tried the beta in its first day and sent reports, here in the thread and by PM. Every report below was reproduced on a clean ProcessWire install with the module in question, then fixed and covered by a test.

Modules that use UIkit now work

Some modules use UIkit directly, because AdminThemeUikit loads it on every page: grids, cards, modals, UIkit.notification(). Under Bridge there was no UIkit, so those screens looked broken. Special thanks to Matjaž Potočnik, who reported it for his ProcessShowcase module. Its UIkit page compares the admin theme with stock UIkit side by side, which made it the perfect test for this release.

Bridge now has a UIkit layer, built the same way as its jQuery bridge: it loads only on the pages that need it. A page needs it when its content uses UIkit markup, when a module script calls UIkit, or when a module adds UIkit's files. Core screens never load it.

• UIkit's own stylesheet, recoloured with Bridge's colours, so it follows the light and dark scheme, and it can never restyle Bridge's own parts.
• Core's own UIkit script, so modules get the same UIkit version as under Uikit.
• A UIkit.something() call made before the layer has loaded still works: the layer loads and the call runs.
• A new setting in the module's config, "UIkit for modules written for AdminThemeUikit": load only on pages that use UIkit (the default), always, or never.
• Module authors can ask for it explicitly with $adminTheme->needUikit('YourModule'), and the reasons are hookable (uikitReasons()).

Fixes

• Third-level menus (Pages > Tree > a page with children) opened inside their parent menu instead of beside it.
• The Add New button at the top of Setup > Templates did nothing. The same went for other list screens with an Add New button.
• With $config->debug on, the Debug Mode Tools panel didn't work on most pages. It now opens in a dialog on every page.
• TracyDebugger's bar ran off the left edge of the screen on a phone.
• In the page editor, the View tab's menu sometimes showed open below the form.

Updating

Replace site/modules/AdminThemeBridge/ with the new version from https://github.com/theoretic/AdminThemeBridge (or git pull there), then Modules > Refresh. The full changelog is in the development repo at https://github.com/theoretic/bridge .

Still open

• The UIkit layer doesn't support right-to-left layouts yet.
• I've tested it with ProcessShowcase and the modules on my own sites. If a module that uses UIkit still looks wrong, please post a screenshot and the module's name.

Keep the reports coming. A module that misbehaves under Bridge is exactly what I'm looking for 😉

Edited Thursday at 06:58 PM by theoretic

[MSP01]

Nice work. I've long thought that the admin interface is the weakest part of Processwire.

Are you planning on adding any UX functionality or just more or less showing same things with faster UI?

[theoretic]

@MSP01, a big elephant can be eaten part by part only 😉 Any idea is welcome, and I have my own ideas on new admin functionality. But the first goal is to get the basic implementation working well and moving it from beta stage to something anyone can use in everyday work. After that, new functionality time will come.