PHPackages                             bmd/navigation-block-enhancements - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. bmd/navigation-block-enhancements

ActiveLibrary[Utility & Helpers](/categories/utility)

bmd/navigation-block-enhancements
=================================

Enhance the core navigation block

v0.4.2(1mo ago)096↓88.9%GPL-2.0-or-laterJavaScriptCI passing

Since Apr 17Pushed 1mo agoCompare

[ Source](https://github.com/bob-moore/Navigation-Block-Enhancements)[ Packagist](https://packagist.org/packages/bmd/navigation-block-enhancements)[ RSS](/packages/bmd-navigation-block-enhancements/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (10)Dependencies (11)Versions (11)Used By (0)

Navigation Block Enhancements
=============================

[](#navigation-block-enhancements)

[![Navigation Block Enhancements](assets/banner-large.webp)](assets/banner-large.webp)

[![WordPress](https://camo.githubusercontent.com/37248c7b4f293acfd4db49b12db9762dc0dc5fc99b9754d4f7d9d9a648c01018/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f576f726450726573732d362e392532422d3338353865393f6c6f676f3d776f72647072657373266c6f676f436f6c6f723d666666)](https://wordpress.org/)[![PHP](https://camo.githubusercontent.com/8da406bc1dd3dcb38541095055eef712a822936eee12a6c185a71f6e678091b2/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d3737376262343f6c6f676f3d706870266c6f676f436f6c6f723d666666)](https://www.php.net/)[![Latest Release](https://camo.githubusercontent.com/215324996b60c37263feab8fef46d3bc3e9610050d7a00b8de3776713609ea89/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f626f622d6d6f6f72652f6e617669676174696f6e2d626c6f636b2d656e68616e63656d656e74733f6c6162656c3d72656c65617365)](https://github.com/bob-moore/navigation-block-enhancements/releases/latest)[![License](https://camo.githubusercontent.com/cd781d0568c328bdea35f284d33e2b1e96675ef60910926c1dd75d5a4d46de66/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d47504c2d2d322e302d2d6f722d2d6c617465722d626c7565)](https://www.gnu.org/licenses/gpl-2.0.html)

[![Lint Assets](https://github.com/bob-moore/navigation-block-enhancements/actions/workflows/lint-assets.yml/badge.svg)](https://github.com/bob-moore/navigation-block-enhancements/actions/workflows/lint-assets.yml)[![PHPCS](https://github.com/bob-moore/navigation-block-enhancements/actions/workflows/phpcs.yml/badge.svg)](https://github.com/bob-moore/navigation-block-enhancements/actions/workflows/phpcs.yml)[![PHPStan](https://github.com/bob-moore/navigation-block-enhancements/actions/workflows/phpstan.yml/badge.svg)](https://github.com/bob-moore/navigation-block-enhancements/actions/workflows/phpstan.yml)

Enhance the WordPress Navigation block (`core/navigation`) with better vertical submenu behavior and hover/focus color controls.

Features
--------

[](#features)

### Vertical Submenus

[](#vertical-submenus)

- Improves click-open submenu behavior for vertical Navigation blocks.
- Removes Navigation block focusout handlers from vertical menu output so submenus do not collapse unexpectedly while users move through the menu.
- Styles vertical click-open submenus as in-flow accordion-style lists instead of detached flyout menus.
- Replaces the core sibling submenu icon with a clickable button pseudo-element, using `src/images/chevron-down.svg` as a CSS mask.
- Supports left, center, right, and stretch justification modes for vertical navigation layouts.

### Overlay Debugging

[](#overlay-debugging)

- Adds an opt-in development mode for inspecting responsive Navigation overlays.
- When enabled, removes the overlay container's focusout handler so the overlay stays open while browser developer tools have focus.
- Skips this processing when the Navigation block's overlay menu setting is `never`.
- Enable with the `navigation_block_enhancements_enable_dev_mode` filter:

```
add_filter( 'navigation_block_enhancements_enable_dev_mode', '__return_true' );
```

### Hover/Focus Colors

[](#hoverfocus-colors)

- Adds text and background color controls for Navigation item hover/focus states to the `core/navigation` block inspector's Color panel.
- Adds **Text - Hover** and **Background - Hover** controls with alpha support.
- Controls are clearable and integrate with "Reset All".
- Previews selected hover/focus colors in the editor.
- Applies colors on the frontend for `:hover`, `:focus`, and `:focus-visible` states.
- Outputs CSS custom properties (`--core-nav-focus-color`, `--core-nav-focus-background-color`) on the Navigation wrapper so themes can override or extend behavior.

### Architecture

[](#architecture)

- Boots through a single `Controller` that builds a small PHP-DI container and mounts all WordPress hooks.
- Splits responsibilities into focused services, providers, and transformers:
    - `AssetLoader` registers editor assets and block-scoped styles for `core/navigation`.
    - `DropDown` processes vertical Navigation block markup with `WP_HTML_Tag_Processor`.
    - `Modal` optionally removes responsive overlay focusout behavior for development/debugging.
    - `Colors` adds frontend classes and CSS custom properties for hover/focus colors.
    - `FilePathResolver` and `UrlResolver` keep package paths configurable for plugin and Composer usage.
- Scopes bundled runtime dependencies in release zips to avoid conflicts with other plugins.
- Ships release zips with optional compiled container cache support.
- Ships plugin banner and icon assets for release/update metadata.
- Surfaces GitHub release updates in WordPress admin through the bundled updater.
- Can be embedded in other plugins or themes via Composer.

Requirements
------------

[](#requirements)

- WordPress 6.9+
- PHP 8.2+

Installation
------------

[](#installation)

### Install as a plugin

[](#install-as-a-plugin)

1. Download the latest release zip from GitHub releases.
2. In WordPress admin, go to Plugins -> Add New Plugin -> Upload Plugin.
3. Upload the zip and activate Navigation Block Enhancements.

### Install from source

[](#install-from-source)

If you are building this repository directly:

```
npm run build
npm run plugin-zip
```

Then upload the generated release zip in WordPress admin.

### Install via Composer (library usage)

[](#install-via-composer-library-usage)

If you are embedding this into your own project:

```
composer require bmd/navigation-block-enhancements
```

Then bootstrap:

```
use Bmd\NavBlockEnhancements\Controller;

$dependency_url  = plugin_dir_url( __FILE__ ) . 'vendor/bmd/navigation-block-enhancements/';
$dependency_path = plugin_dir_path( __FILE__ ) . 'vendor/bmd/navigation-block-enhancements/';

$plugin = new Controller(
    $dependency_url,
    $dependency_path,
    false
);

$plugin->mount();
```

The constructor expects the public URL and filesystem path pointing to the Navigation Block Enhancements dependency root, not the file where you call it. The third argument enables PHP-DI container compilation; leave it `false` for Composer-embedded usage unless your project manages its own cache lifecycle.

Usage
-----

[](#usage)

### Use Vertical Submenus

[](#use-vertical-submenus)

1. Add a Navigation block.
2. Set the layout orientation to vertical.
3. Configure submenus to open on click.
4. Save and view the page.

The plugin adjusts the rendered Navigation block markup and styles so vertical click-open submenus behave like in-flow menu sections.

### Set Hover/Focus Colors

[](#set-hoverfocus-colors)

1. Add or select a Navigation block.
2. Open the block sidebar.
3. Open the **Color** panel.
4. Use **Text - Hover** and **Background - Hover** to choose hover/focus colors.
5. Save and view the post or template.

CSS Custom Properties
---------------------

[](#css-custom-properties)

The following CSS custom properties are available for theming:

PropertyDefaultDescription`--core-nav-submenu-indicator-size``1rem`Width and height of the generated submenu chevron`--core-nav-focus-color`-Navigation item text color on hover/focus (set per block)`--core-nav-focus-background-color`-Navigation item background color on hover/focus (set per block)Changelog
---------

[](#changelog)

### 0.4.1

[](#041)

- Hardened package slug injection before it is used in WordPress hook names.
- Switched asset registration to fixed, explicit handles for safer loading.
- Fixed plugin URL resolution when running as the standalone plugin.
- Renamed navigation markup processors to transformers to better match their role.

### 0.4.0

[](#040)

- Rebuilt the plugin around a focused PHP-DI controller and provider/processor services.
- Added editor controls for Navigation item hover/focus text and background colors.
- Added editor preview and frontend rendering for Navigation hover/focus colors.
- Added CSS custom properties for Navigation hover/focus colors.
- Improved vertical click-open submenu behavior for the core Navigation block.
- Added an opt-in dev-mode filter for keeping responsive Navigation overlays open while inspecting them.
- Replaced the core sibling submenu icon with a generated chevron on the clickable Navigation toggle.
- Added GitHub release update support and plugin directory-style image assets.
- Scoped release dependencies to reduce conflicts with other plugins.

License
-------

[](#license)

GPL-2.0-or-later. See the [GNU General Public License](https://www.gnu.org/licenses/gpl-2.0.html).

###  Health Score

35

—

LowBetter than 77% of packages

Maintenance89

Actively maintained with recent releases

Popularity9

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity30

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~4 days

Total

10

Last Release

53d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/adf6af151397e0b108508ed9a8554fa09dc00f90864873446e76fa5b17463e23?d=identicon)[bobjutsu](/maintainers/bobjutsu)

---

Top Contributors

[![bob-moore](https://avatars.githubusercontent.com/u/1745619?v=4)](https://github.com/bob-moore "bob-moore (20 commits)")

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP\_CodeSniffer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/bmd-navigation-block-enhancements/health.svg)

```
[![Health](https://phpackages.com/badges/bmd-navigation-block-enhancements/health.svg)](https://phpackages.com/packages/bmd-navigation-block-enhancements)
```

###  Alternatives

[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.7k38.9k](/packages/matomo-matomo)[moodle/moodle

Moodle - the world's open source learning platform

7.2k88.5k114](/packages/moodle-moodle)[azuracast/azuracast

The AzuraCast self-hosted web radio station management suite.

3.9k27.8k](/packages/azuracast-azuracast)[phlak/directory-lister

PHP directory lister

2.5k1.4k](/packages/phlak-directory-lister)[infinum/eightshift-libs

WordPress libs developed by Eightshift team to use in modern WordPress.

63125.5k3](/packages/infinum-eightshift-libs)[drupal-code-builder/drupal-code-builder

Code generator for Drupal

27253.3k1](/packages/drupal-code-builder-drupal-code-builder)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)