KO – Nav Icon Takeover

Replaces a Divi menu icon visually with an accessible two-bar control that morphs into a close icon while preserving Divi's fullscreen navigation interactions.

Description

KO – Nav Icon Takeover provides a persistent, accessible navigation toggle for Divi headers. A two-bar hamburger morphs smoothly into an X when the fullscreen navigation opens and reverses when it closes.

The plugin keeps Divi's existing Icon modules in the DOM as interaction controllers while hiding their visual glyphs. This preserves Theme Builder interactions without duplicating Divi's canvas animation logic.

Features include:

• Reversible two-bar hamburger-to-X animation.
• Automatic visibility synchronized with a sliding Divi header.
• Automatic horizontal alignment with the originating Divi row.
• Automatic vertical alignment with the original Divi menu trigger.
• Persistent close control above the fullscreen navigation canvas.
• Updated aria-expanded state and accessible labels.
• Escape-key closing with focus restoration.
• Reduced-motion support.
• Filterable toggle and Divi trigger selectors.
• Neutral lifecycle events for optional menu enhancements.
• Keyboard and assistive-technology suppression for the visually hidden Divi triggers.
• A bounded close-wait fallback so a faulty enhancement cannot hold the menu open forever.

Installation

1. Upload the ko-nav-icon-takeover folder to /wp-content/plugins/ or install the ZIP through WordPress Admin > Plugins > Add New > Upload Plugin.
2. Activate KO – Nav Icon Takeover.
3. Keep the existing Divi open and close Icon modules in the Theme Builder header.
4. Add the custom toggle markup to the normal header using a Divi Code module.

Required Markup

Add this markup to a Code module in the normal header:

<button class="ko-menu-toggle" type="button" aria-label="Open menu" aria-expanded="false"><span class="ko-menu-toggle__bar"></span><span class="ko-menu-toggle__bar"></span></button>

The default Divi trigger selectors are:

• Open: .et_pb_icon_0_tb_header
• Close: header[data-canvas="Fullwidth Nav"] .et_pb_icon_1_tb_header

Custom Selectors

Use the ko_nav_icon_takeover_settings PHP filter if the Divi module classes or canvas name change.

The filtered settings also include closeWaitTimeoutMs, which defaults to 30000. The JavaScript assigns a neutral class to whichever trigger elements the filter resolves, so custom trigger selectors receive the same hidden presentation.

Lifecycle Events

The plugin dispatches these events on document whenever its toggle or a connected Divi trigger changes the menu state:

• ko-menu:before-open
• ko-menu:opened
• ko-menu:before-close
• ko-menu:closed

Each event's detail includes source, toggle, openTrigger, closeTrigger, restoreFocus, and closeWaitTimeoutMs. The source is toggle, escape, or divi-trigger. Close-animation listeners can use the timeout value to keep their sequence inside the same safety budget.

An enhancement can postpone the Divi close trigger by synchronously passing a Promise to event.detail.waitUntil() during ko-menu:before-close. The menu closes after every registered Promise settles, whether fulfilled or rejected. With no registered waiters, closing remains immediate.

The toggle remains an expanded X while the fullscreen menu is visibly closing. It is marked busy/unavailable during that short interval, then changes back to the Open state only after Divi's close trigger runs. A 30-second safety timeout guarantees recovery from a Promise that never settles.

These events report the icon control's state transition and Divi trigger handoff; they do not attempt to measure the completion of Divi's canvas animation.

Changelog

1.1.0

• Focused the plugin exclusively on the navigation icon, positioning, accessibility, and Divi trigger bridging.
• Added neutral menu lifecycle events for independently managed enhancements.
• Added waitUntil() support so external enhancements can defer the Divi close trigger until their work settles.
• Exposed the close-wait budget to lifecycle listeners.
• Preserved immediate closing when no enhancement requests a delay.
• Removed hidden Divi triggers from keyboard and assistive-technology navigation.
• Applied hidden-trigger styling through runtime classes so filtered selectors remain supported.
• Added a bounded waiter timeout and kept expanded/label semantics accurate until the visible menu closes.
• Added guarded fallback for invalid custom selectors.

1.0.2

• Aligned the takeover toggle vertically with the original Divi menu trigger.
• Preserved hidden trigger dimensions so Divi header spacing controls remain effective.

1.0.1

• Aligned the persistent toggle to the live right edge of its original Divi row.
• Added automatic repositioning when the row or viewport width changes.

1.0.0

• Initial release.
• Added the two-bar hamburger-to-X morph.
• Added Divi interaction bridging and sliding-header visibility synchronization.
• Added keyboard and reduced-motion support.