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 6 hours ago by theoretic

[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.