WordPress

wp-admin-bar-overflow

1
1
1
9
JavaScript
public
View on GitHub

WP Admin Bar Overflow

Responsive overflow for plugin-added WordPress admin-bar nodes.

License: GPL-2.0+
PRs welcome

The WordPress admin bar (#wpadminbar) crowds quickly at narrow viewports. Install a handful of plugins and their admin-bar nodes start colliding with the right-side items, falling off-screen, or becoming inaccessible on mobile, exactly the cohort that needs quick access most.

WP Admin Bar Overflow is a small WordPress plugin that gives plugin-added admin-bar nodes a responsive overflow path. As the viewport narrows, plugin nodes that no longer fit overflow into a right-side Plugins dropdown. On tablet and mobile, all plugin nodes group under the dropdown unconditionally so they remain reachable on every screen size. The original DOM nodes stay in place at their registered positions (plugin JavaScript that binds to specific node IDs continues to work), and click events on the mirrored dropdown items are forwarded to the originals.

It is built incrementally on top of Core’s existing WP_Admin_Bar nested-menu pattern: a small PHP classifier reads the registered nodes, a lightweight JavaScript runtime handles the overflow detection and mirroring, and a small set of filter hooks lets host adapters customise classification, priority, and trigger placement.

Status

This is v0.1.0, an early prototype, public from day 1.

The plugin is functional and installable as an early release. The public-installable plugin shape is what this repo is for, with WPCOM integration still guarded behind a site sticker while interaction and design follow-ups continue.

Try it

The fastest way is the WordPress Playground demo (no install, no setup):

Try in WordPress Playground

The blueprint boots WordPress with Query Monitor, Yoast SEO, and this plugin active, then drops you in wp-admin/. Resize the viewport to see plugin-added admin-bar nodes move into the Plugins dropdown.

To install on your own WordPress site:

  1. Clone this repo into wp-content/plugins/wp-admin-bar-overflow/, or download a release zip and upload via wp-admin Plugins > Add New > Upload Plugin.

  2. Activate. Plugin-added admin-bar nodes overflow into the right-side Plugins dropdown as space gets tight. At tablet and mobile widths, all plugin-added admin-bar nodes live under that dropdown.

    Hosts that need finer control (per-blog, per-user, percentage rollout, host-owned admin-bar nodes) can override behavior from an adapter. See docs/host-extension-api.md.

How it works

  • Classifier. A PHP classifier reads $wp_admin_bar->get_nodes() at wp_before_admin_bar_render (after every admin_bar_menu callback has fired, including those at PHP_INT_MAX), classifies each top-level node as core, plugin, or skip, and emits a JSON nav model as an inline <script type="application/json"> block. Host adapters override classification through documented filter hooks.
  • Responsive overflow. A small ES-module runtime measures the admin bar’s available width with ResizeObserver, hides plugin-classified nodes that don’t fit at the current viewport, and mirrors them into the right-side Plugins dropdown. At tablet + mobile widths, all plugin-classified nodes mirror unconditionally.
  • Mirror + click forwarding. The dropdown shows cloned <li> elements with renamed IDs (mirror- prefix); the original DOM nodes stay at their registered positions, hidden by CSS at narrow viewports. A delegated click handler forwards clicks on a mirrored item to its original, so plugin JavaScript that binds to original node IDs (counter toggles, panel openers, badge updates) continues to work.
  • Core’s nested-menu pattern. The dropdown trigger is registered as a standard WP_Admin_Bar top-level node with a placeholder child, so Core renders the menupop + aria-expanded shell at server-render time. Desktop click is handled by a small runtime click handler (~250 bytes); desktop hover, Enter, and touch tap remain Core-driven via hoverintent, toggleHoverIfEnter, and mobileHover.
  • No core changes. The plugin runs entirely as an admin-bar overlay. It registers its own dropdown node, leaves plugin-owned original nodes in place, and decorates the rendered DOM.
  • Performance. Runtime JS ≤ 8 KB gzipped, runtime CSS ≤ 4 KB gzipped (CI gate). Plain JavaScript bundled with esbuild, no React, no @wordpress/* runtime dependencies. The classifier short-circuits when the enablement filter returns false, so non-opted-in users see no overhead beyond a sub-millisecond filter check.

For the architectural details (/src/ layout, file responsibilities, contracts), see docs/architecture.md.

For host-adapter authors: docs/host-extension-api.md documents the filter API with worked examples.

The sibling WordPress/wp-admin-sidebar project applies the same shape (public-from-day-1, classifier-driven, host-adapter API) to the wp-admin left navigation. The two plugins operate on different surfaces (#adminmenu vs #wpadminbar) and can be installed on the same site without conflict.

Contributing

Bug reports, design feedback, and host-adapter questions all welcome.

  • Engineering work: GitHub Issues + PRs. Run composer install, npm install, npm run lint, php tests/test-grep-no-wpcom-tokens.php before opening a PR. See CONTRIBUTING.md.
  • UX / design feedback / open design questions: GitHub Issues with the relevant enhancement, question, or Idea label.
  • Security issues: see SECURITY.md. Don’t open a public issue.
  • Host-adapter authoring: read docs/host-extension-api.md, then open an issue with the host-specific details you need to support.

License

GPL-2.0-or-later. Copyright the contributors. By submitting a contribution you license it under GPL-2.0+.

Maintainers

See MAINTAINERS.md. Initial maintainer set: @chriskmnds and @lucasmdo.

v0.3.3[beta]