DEV Community: Ryo

When WordPress Admin Menu Items Overflowed, I Built a Plugin to Folder Them

Ryo — Fri, 25 Sep 2026 15:00:00 +0000

When running a WordPress site, there comes a moment when you suddenly realize something.

"Wait... is my side menu way too long?"

Wait...

In its initial state, the WordPress admin menu neatly arranges essential items in a compact list: Posts, Media, Pages, Appearance, Plugins, Settings, and so on. But as you run the site longer—adding features, integrating external services, and beefing up SEO and security—it swells to a daunting length that makes you weary just looking at it.

This site had fallen into that exact state.

Isn't this way too long?

Between writing sessions, whenever I'd think, "Let me tweak this one setting," or "Where was that plugin's settings menu again?", I had to scan down the endless side menu. If I couldn't spot it, I'd expand "Tools" or "Settings" to search, and still come up empty. Only upon looking very carefully would I find it sitting all alone near the bottom of the sidebar—.

As these repeated micro-stresses accumulated, my patience was wearing thin. What's more, the number of plugins is only likely to grow further from here.

Can We Just Delete Unnecessary Plugins?

"By the way, just how many plugins are installed on this site right now?"

Thinking this, I counted the list of plugins in the admin screen, and here are the ones that were active at the time:

Click to view the plugin list

APCu Manager
Better Search Replace
Block AI Crawlers
CompressX - AVIF & WebP Converter
Contact Form 7
Database Manager - WP Adminer
Dev Favicon Switcher
Duplicate Page
Enable Media Replace
GenerateBlocks
Highlighting Code Block
Kadence Blocks — Page Builder Toolkit for Gutenberg Editor
KU Sticky Video for YouTube
KU Sticky Video for YouTube Pro
Lazy Load for Videos
Lemon Squeezy — Sell Digital Products, Subscriptions, and Licenses
LH Archived Post Status
Lightbox with PhotoSwipe
LightStart - Maintenance Mode, Coming Soon and Landing Page Builder
Mail logging - WP Mail Catcher
Permalink Manager Lite
Polylang
Sassy Social Share
Secondary Title
Simple CAPTCHA with Cloudflare Turnstile
Simple Local Avatars
Site Kit by Google
User Switching
Wordfence Security
WPS Hide Login
WPvivid Backup Plugin
WP Dark Mode
Zoho Mail

33 plugins. You might think that is quite a lot. In reality, though, running a full-fledged site often leaves you with no choice but to install around this many.
At first, I wondered, "Couldn't I delete a few plugins to simplify the side menu?" In the end, I gave up on that idea.

Most of them handle caching, image conversion, security, backups, email delivery, and other indispensable daily functions that simply cannot be removed. Furthermore, switching one or two plugins to a "keep them uninstalled and only install when needed" workflow is a hassle in itself. And removing just one or two wouldn't make the side menu noticeably shorter anyway.

Which means:
If we cannot reduce the plugins, our only option is to rethink how the menu is presented.

Hopes for Existing Menu Management Plugins. But...

Naturally, there are already several plugins available on WP.org (the official WordPress directory) and elsewhere designed to organize side menus. Of course, I researched them and tested them in a staging environment. Unfortunately, none of them made the cut.

I won't name names since this might sound a bit critical, but roughly speaking, they suffered from the following issues (those who have tried them might recognize which ones I'm talking about):

Overly complex UI that isn't intuitive
Aiming for high functionality is commendable, but the settings screen becomes correspondingly bloated. When all you want to do is move a single menu item, you're left wondering what to click.
Relies on a three-tier side menu that is labeled "experimental" and lacks reliability
To properly categorize menus into folders, you have to enable a three-tier menu option labeled as an "experimental feature." However, the standard WordPress side menu architecture was only ever designed for two tiers. As a result, layouts break, hover behavior gets glitchy, and it leaves too much uncertainty for production use (which is probably why it's labeled "experimental" in the first place!).
Resorting to the extreme measure of replacing the entire side menu with a custom UI
The most aggressive plugins threw out WordPress's standard menu rendering mechanism entirely, replacing the whole side menu with custom markup. While this looks modern, it carries significant risks: conflicts with badges and scripts added by other plugins, unpredictable fallout when WordPress core updates, and so on. In the end, I concluded that I wouldn't feel comfortable using it myself, let alone in client work.

Why Such a Heavy-Handed Approach?

The more I examined the source code and behavior of existing plugins, the more a question grew in my mind.

"Why does every single one of them resort to such heavy-handed measures?"

If all you want is to declutter the WordPress admin side menu, there should be a much more natural and safer way. In fact, I had a very clear concept in mind of how to do it.
That said, it was a straightforward design that any engineer familiar with WordPress internals could easily come up with. That was precisely why I assumed a plugin doing "exactly that" had to exist in the official directory—and that's what I went looking for.

Strange as it was, it didn't exist. Once again, no matter how much I searched, I couldn't find "that exact thing."

"If it doesn't exist, I'll build it myself."

And that is how I came to develop my new Karasunouta Admin Menu Folder plugin.

We Don't Need a 3-Tier Menu

The principle is extremely simple. To begin with, there is no need to force a three-tier side menu structure that disregards WordPress's native design.

By default, WordPress's plugin menu structure is designed so that when you access a root (parent) menu, its submenu (child) items automatically expand beneath it. Within the scope of two tiers, WordPress officially provides standard hooks to organize menu items. In that case, the solution is simple. You just do this:

Before Configuration

After Configuration

Remove root menus of infrequently used plugins from the side menu, and
Display them instead as submenus within a newly added Menu Folder in the side menu.

That's really all it does.

Behavior of Stowed Plugins: The Case of LightStart

Take the LightStart plugin, for instance, which provides maintenance mode protection for your site. It is an extremely useful, indispensable plugin for me, but it's only needed during major maintenance work—just a few times a year.
There is no reason for such a plugin's root menu to sit permanently in the side menu all year round. It was the very first candidate I stowed into the Karasunouta Admin Menu Folder.

Here it is

The root menu of the LightStart plugin stowed in the Menu Folder appears as shown in the image above. You can open the LightStart settings page from here, so there is never any issue when you want to use its primary maintenance mode feature.

What About Submenus?

However, what about LightStart's submenu item, "About Us"? You might wonder: "What if I really want to open that, but the side menu only has 'Menu Folder > LightStart' and no 'Menu Folder > LightStart > About Us'? I can't access it—what now?!"
Such a concern might cross your mind.

Don't we really need a 3-tier menu after all?

Don't worry. Remember what I wrote earlier:

By default, WordPress's plugin menu structure is designed so that when you access a root (parent) menu, its submenu (child) items automatically expand beneath it.

Let's look at the actual behavior.

The moment you click "Menu Folder > LightStart" and the LightStart settings page opens, the LightStart root menu reappears in the side menu. At this point, because the LightStart settings page is naturally "currently active," the LightStart root menu is automatically expanded by WordPress (= its submenu items become visible).

If you actually navigate to the LightStart plugin settings page, you will see the side menu look like the image below.

The "About Us" submenu is clearly visible too!

As you can see, the moment the LightStart settings page opens, the LightStart root menu appears in the left side menu and expands. As a result, you can seamlessly access the "LightStart > About Us" menu item.

Summary: How to Access Submenus

In other words, even if you want to access a submenu item of a stowed plugin, all it takes is:

First, open the stowed menu item in the Menu Folder (e.g., "Menu Folder > LightStart")
Next, open the temporarily expanded submenu in the side menu (e.g., "LightStart > About Us")

—allowing reliable access in just two clicks. After all, the Menu Folder is meant for "rarely used plugin root menus," which means their submenus are accessed even less frequently. If you can reach them in two clicks, I believe it is safe to say accessibility is not an issue.

We Don't Need Risky Hacks, Either

The crucial point here is that throughout this process, not a single fragile or heavy-handed trick was used—such as the approaches seen in some other plugins, like completely replacing the side menu with React or shoehorning in an unsupported three-tier structure. Everything follows WordPress specifications. It simply toggles the display state of the side menu in a completely natural way, using only standard filter hooks provided officially by WordPress.

Because it does not fight against WordPress's native architecture, the operation remains fast and stable, and the risk of conflicts with other plugins is kept to an absolute minimum.

The Impact: Before and After

While the approach is very simple, the results are striking.

Before Installation

After Installation

...Can you see the difference? Just grouping infrequently accessed root menus into a single "Menu Folder" makes the admin interface so much cleaner.
With a clear view of the side menu, you can instantly navigate to frequently used items like "Posts," "Pages," and "Appearance" without hesitation.

A pleasant and somewhat unexpected byproduct was that finding "infrequently used menus" actually became faster too.
My mind naturally adapted to the rule: "Don't use it often = probably in Menu Folder." As a result, I started checking the Menu Folder first. And more often than not, it was right there, easily found. Truly. At least that was my experience, so I encourage you to try it for yourself.

Consequently, whether an item is used constantly or rarely, accessibility to every menu item across the site improved dramatically.

A Modest Setting You Won't Want to Live Without

While the usability of my admin dashboard improved dramatically, there was one additional small feature I wanted as I used it in day-to-day work. That is the "Show link to settings page in toolbar" option.

Checking this box adds a direct link to "Admin Menu Folder" in the toolbar (admin bar) at the top of the admin screen. It is a simple setting, but when you add a new plugin and feel the side menu getting cluttered again, or wonder, "Did I stow that menu in the folder yet?", being able to jump to the settings page in a single click from the admin bar is surprisingly convenient.

Conclusion

Although this plugin was only recently released, I personally believe it should be a must-have plugin for future WordPress site builds. In fact, I now install and use it on all WordPress sites I handle, including client work as well as my own site. Going back to that previously cluttered side menu environment is something I can hardly imagine anymore.

In particular, if you:

Are suffering from scroll hell due to an overwhelming number of plugins
Want to deliver a clean, well-organized admin dashboard to your clients

—please give it a try. It should make your day-to-day site management surprisingly comfortable!

Official Plugin Page (WordPress.org)
Karasunouta Admin Menu Folder – WordPress plugin

(If you find it useful, leaving a 5-star review would mean a lot to me!)

How to Safely Integrate the YouTube API in Lazy-Loading Environments Using MutationObserver

Ryo — Mon, 20 Jul 2026 14:00:00 +0000

In the recently published article “How to Load the YouTube IFrame Player API Without Breaking Other Plugins,” we discussed how to prevent conflicts in environments where multiple plugins attempt to initialize the YouTube API simultaneously by incorporating a spirit of mutual concession (polling, sharing existing players, and random jitter) into the code.

The WordPress plugin “KU Sticky Video for YouTube,” which incorporates this design, had been operating smoothly on this site without any conflict issues. However, a user reported that the sticky video feature stopped working when used in combination with lazy-loading (LazyLoad) plugins. Upon verification, this was indeed the case!

The polling method discussed in the previous article assumes that the video player (iframe) itself already exists in a static state within the DOM at the time of page load. However, in a lazy-loading environment where video players are loaded dynamically in response to user actions such as scrolling or clicking, the target iframe has not yet been generated at page load. Admittedly, this was a blind spot.

This article explains a dynamic and asynchronous binding design for the YouTube API using MutationObserver to overcome the new challenge of coexisting with LazyLoad plugins.

Why Does It Not Work? The YouTube API Under LazyLoad

To improve initial page load performance, LazyLoad plugins delay the loading of images and iframes using approaches such as the following:

Attribute rewriting: The plugin assigns a placeholder or empty value to the src attribute, moving the actual URL to a separate attribute such as data-src. Once the element approaches the viewport during scrolling, JavaScript writes the actual URL back to the src attribute.
Dynamic DOM insertion: The iframe element itself is not generated in the DOM until it enters the viewport. Instead, a placeholder image of the video player is displayed. When the play button on the placeholder image is clicked, the iframe is dynamically generated and displayed in its place.

In contrast, many YouTube-related plugins, including KU Sticky Video for YouTube, execute document.querySelectorAll('iframe') at timings such as DOMContentLoaded to perform initialization and register event listeners on the elements existing at that moment. However, when LazyLoad is enabled, the iframe elements for embedded YouTube videos are either not yet generated at this timing, or are intentionally generated in an incomplete state.

Plugins dependent on the YouTube API attempt to search for target iframes under these conditions. However, no matching iframes are found. As a result, the initialization process is skipped, and the plugin’s functionality—in the case of KU Sticky Video for YouTube, the sticky video feature that follows the scroll—never triggers.

The polling-based countermeasure implemented in the previous article was also largely ineffective against LazyLoad plugins. Since polling begins immediately after page load, the delay in execution is at most a few seconds. Meanwhile, it is impossible to predict when a reader will scroll down the article. While one could theoretically poll indefinitely, polling requires periodic timer events, making indefinite waiting impractical.

After all, a reader might step away to the restroom immediately after opening the page, bump into a colleague in the hallway on the way back, chat for a while, and only begin scrolling the article after finally returning to their seat. If setInterval continues to run for minutes, or potentially over an hour, while waiting for them, the browser cannot enter an idle state. Especially on mobile devices, this would result in the birth of a “mysteriously battery-draining page.” We would certainly like to avoid that.

The Solution: Dynamic Binding Using MutationObserver

Detecting Videos and Preventing Double Initialization with MutationObserver

To accommodate various lazy-loading approaches, we configure the MutationObserver to monitor two types of mutation events simultaneously: the dynamic addition of DOM nodes and changes to the src attribute of existing elements.

function initMutationObserver() {
    const observer = new MutationObserver(function(mutations) {
        const detectedIframes = [];

        mutations.forEach(function(mutation) {
            // Pattern A: Monitor the dynamic addition of DOM nodes
            if (mutation.type === 'childList') {
                mutation.addedNodes.forEach(function(node) {
                    if (node.nodeType === Node.ELEMENT_NODE) {
                        if (node.tagName === 'IFRAME') {
                            detectedIframes.push(node);
                        } else {
                            // Extract nested iframes as well
                            const nested = node.querySelectorAll('iframe');
                            nested.forEach(iframe => detectedIframes.push(iframe));
                        }
                    }
                });
            } 

            // Pattern B: Monitor changes to the src attribute of existing elements
            else if (mutation.type === 'attributes' && mutation.attributeName === 'src') {
                const node = mutation.target;
                if (node.nodeType === Node.ELEMENT_NODE && node.tagName === 'IFRAME') {
                    detectedIframes.push(node);
                }
            }
        });

        // Filter and process only YouTube iframes from the detected ones
        const youtubeIframes = detectedIframes.filter(isYouTubeIframe);
        if (youtubeIframes.length > 0) {
            handleNewIframes(youtubeIframes);
        }
    });

    observer.observe(document.body, {
        childList: true,
        subtree: true,
        attributes: true,
        attributeFilter: ['src'] // Restrict monitoring to the src attribute to minimize performance impact
    });
}

This allows the implementation to instantly capture the appearance of a video, regardless of the mechanism the LazyLoad plugin uses to delay it. Specifying attributeFilter: ['src'] limits the attribute monitoring to src, minimizing unnecessary overhead.

Furthermore, since a MutationObserver triggers frequently, detection events can occur multiple times for the same iframe. If double initialization occurs, it would hinder not only coexistence with other plugins but also the plugin’s own processing. To reliably prevent this double processing, we assign a custom data- attribute to the iframe under process to manage its state.

function isYouTubeIframe(iframe) {
    if (!iframe || iframe.tagName !== 'IFRAME') {
        return false;
    }

    // Exclude elements already processed by this plugin
    if (iframe.getAttribute('data-ku-sticky-processed') === 'true') {
        return false;
    }

    const src = iframe.getAttribute('src') || '';
    return src.indexOf('youtube.com') !== -1 || 
           src.indexOf('youtube-nocookie.com') !== -1 || 
           src.indexOf('youtu.be') !== -1;
}

function handleNewIframes(iframes) {
    iframes.forEach(iframe => {
        // Mark as processed
        iframe.setAttribute('data-ku-sticky-processed', 'true');

        // Execute initialization and binding for this iframe
        initPlayingMode([iframe]);
    });
}

Elements with the data-ku-sticky-processed attribute are immediately excluded from future MutationObserver detections, reliably avoiding unnecessary loops and conflict errors.

Dynamically Triggered Conflict Avoidance Process

This is the core of the “dynamic binding” design. While the polling and random jitter introduced in the previous article were triggered based on a static timing like page load, the current design using MutationObserver shifts to a dynamic model: every time a video appears on the page, an asynchronous process starting from conflict avoidance (mutual concession) to safe binding is initiated specifically for that video.

function initPlayingMode(iframes) {
    if (iframes.length === 0) return;

    // 1. Insert the YouTube API script if it has not been loaded yet
    if (!window.YT && !document.querySelector('script[src*="youtube.com/iframe_api"]')) {
        const tag = document.createElement('script');
        tag.src = 'https://www.youtube.com/iframe_api';
        const firstScriptTag = document.getElementsByTagName('script')[0];
        firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);
    }

    // 2. Start polling for this video, waiting for other plugins to complete initialization
    let attempts = 0;
    let apiReadyAttempts = 0;
    let setupCompleted = false;
    const checkInterval = setInterval(() => {
        attempts++;
        const isApiReady = window.YT && typeof window.YT.Player === 'function';
        if (isApiReady) {
            apiReadyAttempts++;
        }

        // Check if other plugins have already created a player instance for this iframe
        let allFound = false;
        if (isApiReady && typeof window.YT.get === 'function') {
            allFound = true;
            for (let j = 0; j < iframes.length; j++) {
                const id = iframes[j].id;
                const player = (id ? window.YT.get(id) : null) || window.YT.get(iframes[j]);
                if (!player) {
                    allFound = false;
                    break;
                }
            }
        }

        // Termination condition: shared target found or wait time limit exceeded
        const shouldStop = allFound || apiReadyAttempts >= 3 || attempts >= 30;
        if (shouldStop) {
            clearInterval(checkInterval);
            if (!setupCompleted) {
                setupCompleted = true;

                // 3. Apply random jitter (0 to 100ms delay)
                const jitterDelay = Math.random() * 100;
                setTimeout(() => {
                    setupPlayers(iframes);
                }, jitterDelay);
            }
        }
    }, 100);
}

With this asynchronous design, the following scenario executes autonomously. The actors involved are as follows:

KU Sticky Video for YouTube plugin: The subject of this article. Referred to as “this plugin.”
LazyLoad plugin: A plugin that reduces page weight by lazy-loading YouTube videos during scrolling or other actions. Examples include Lazy Load for Videos.
Other plugins dependent on the YouTube API: Third-party plugins that use the YouTube API to apply various effects to YouTube videos on the page. Referred to as “other plugins.”

The primary goal of this article is to make this plugin coexist with the lazy-loading plugin (No. 2). While coexistence with other plugins (No. 3) was achieved in the previous article, our objective here is to ensure that coexistence with other plugins remains intact even after achieving compatibility with LazyLoad plugins.

The actual execution flow is as follows:

When a visitor scrolls down the page or performs a similar action, the LazyLoad plugin loads the YouTube video (iframe).
The MutationObserver of this plugin detects its appearance, checks for the presence of the API, and starts polling.
Simultaneously, the other plugin initiates its own initialization (player creation) process for the same iframe.
This plugin polls the initialization state of the other plugin every 100ms. If it detects that the other plugin has created a player instance using YT.get(), it safely shares events with that instance.
If the other plugin does not create a player instance, this plugin creates its own player instance after a random jitter delay.

By keeping the process for each video completely independent, the necessary processing is executed at the exact moment the video appears, regardless of how long the reader waits before scrolling. This implementation maximizes coexistence not only with LazyLoad plugins but also with other YouTube API-dependent plugins (refer to the previous article for details on the role of random jitter).

Conclusion: Coexistence Adapting to an Expanded Time Dimension

In plugin development, conflicts with lazy loading (LazyLoad) are a common challenge. Previously, initialization order was adjusted within a tight window of a few seconds immediately after page load. LazyLoad, however, introduces an unpredictable and extended time dimension dictated by the reader’s scroll speed. The KU Sticky Video for YouTube plugin previously failed to account for this variable time frame, which was a significant oversight.

One could avoid conflicts by declaring incompatibility with LazyLoad plugins and requesting users to disable them, but this compromises the user’s desire to optimize site loading speed. Fortunately, the combination of MutationObserver and dynamic asynchronous polling implemented here allows the KU Sticky Video for YouTube plugin to operate stably while preserving the performance benefits of lazy-loading plugins.

To achieve coexistence through mutual concession, it is crucial to detect changes in the environment and trigger actions accordingly. I am reminded that this approach is an essential design pattern for ensuring that various third-party scripts coexist smoothly and perform as intended in the complex WordPress ecosystem.

The dynamic binding design introduced in this article has already been deployed in updates for the free version (v1.9.0 and later) and the Pro version (v1.4.0 and later) of “KU Sticky Video for YouTube.” The sticky video feature should now work reliably even when lazy loading is active. If you have any feedback, please feel free to let us know via the contact form!

How to Load the YouTube IFrame Player API Without Breaking Other Plugins

Ryo — Fri, 10 Jul 2026 13:39:04 +0000

When developing plugins for WordPress, one issue that almost everyone faces at least once is plugin conflicts. The other day, I was developing a plugin (KU Sticky Video for YouTube) that makes YouTube videos in posts follow the scroll to stay in the corner of the screen. It worked perfectly in a clean local testing environment, and I was proud, thinking, “All right, it’s complete!”

However, as soon as I moved the testing ground to a multi-plugin environment where another of my own YouTube-related plugins (unreleased) and other video-related plugins were active, things changed completely. The sticky feature, which had been working smoothly until just moments before, fell completely silent without moving an inch, and when I opened the browser console, there was that annoying red error text. Oh no.

But this is simply a common occurrence in plugin development. In reality, the solution varies depending on the cause of the conflict. In this article, I will explain the mechanism behind the “struggle for leadership” caused by the YouTube Iframe API, which many YouTube-related plugins depend on, in a multi-plugin environment, and introduce a JavaScript design to avoid this problem, share the ride with other scripts, and achieve coexistence.

Why the Conflict? The YouTube API Struggle for Leadership

To highly control YouTube videos from JavaScript, you need to load the official YouTube Iframe Player API. In typical tutorial articles, implementation code like the following is usually introduced:

// Load the API script
const tag = document.createElement('script');
tag.src = 'https://www.youtube.com/iframe_api';
const firstScriptTag = document.getElementsByTagName('script')[0];
firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

// Define the global function called when loading is complete
window.onYouTubeIframeAPIReady = function() {
    const player = new YT.Player('player-id', {
        events: {
            'onStateChange': onPlayerStateChange
        }
    });
};

While this code seems perfectly fine at first glance, it causes issues in environments where multiple plugins and themes run asynchronously, such as in WordPress. Put simply, what happens if another plugin defines window.onYouTubeIframeAPIReady in exactly the same way? Due to the nature of JavaScript, the initialization function defined first will be completely overwritten and lost by the plugin execution that runs later.

As a result, the plugin that loaded first cannot detect when the API has finished loading, and it will never start. This is exactly why the initial version of KU Sticky Video for YouTube stopped working.

Approaches to a Solution: How to Avoid “Fights” Between Plugins

To prevent this conflict and ensure safe operation in any environment, we decided to take the following countermeasures in the KU Sticky Video for YouTube plugin.

1. “Script Presence Check” to Fill the Gap in Asynchronous Loading

When the loading of the YouTube API script is complete, a window.YT object is automatically created in the browser’s global scope (window). This window.YT object contains all the actual functions of the API for creating and controlling the YouTube player.

The tricky part is that it is not as simple as, “I see. Then I just need to check if window.YT exists.” If you do only that, what happens if the script runs “during the network load (when window.YT is undefined) right after another plugin inserted the tag”? The script tag would be inserted twice. To prevent this, in addition to window.YT, we also check whether a script tag for the YouTube API already exists in the DOM tree.

// Search by partial match, considering URL notation variants (iframe_api / player_api)
const alreadyLoading = document.querySelector(
    'script[src*="youtube.com/iframe_api"], script[src*="youtube.com/player_api"]'
);

if ( ! window.YT && ! alreadyLoading ) {
    // Insert the script tag for the first time here
}

Why continue to check window.YT as well?

At first glance, checking only whether the script tag exists in the DOM (alreadyLoading) seems sufficient. After all, window.YT is supposed to be created after the script is loaded. However, there may be cases where a script tag for the YouTube API does not exist in the DOM—for instance, if another plugin bundles the API directly into its JS via build tools like Vite and loads it.

Therefore, it is necessary to perform a double check using both window.YT to 100% guarantee that the load is already complete, and alreadyLoading to detect via the script tag that “the asynchronous load is in progress right now.” By using both together, the risk of conflicts can be minimized.

2. “Event Sharing (Binding)” via window.YT.get()

If another plugin has already created a YT.Player instance for a YouTube iframe on the page, executing new YT.Player again on top of it will cause an error. Therefore, we use the YouTube API global method window.YT.get() to retrieve the already-created player instance, if it exists, and “share the ride” by binding only our event listeners to it.

let existingPlayer = null;

if ( window.YT && typeof window.YT.get === 'function' ) {
    const id = iframeElement.id;
    // Get by the official spec if an ID exists. Otherwise, fall back to passing the DOM element.
    existingPlayer = ( id ? window.YT.get( id ) : null ) || window.YT.get( iframeElement );
}

if ( existingPlayer ) {
    // Share the event with the existing instance if it exists
    // * Unlike standard DOM, the YouTube API's addEventListener requires the "on" prefix (onStateChange)
    existingPlayer.addEventListener('onStateChange', function(event) {
        handlePlayerStateChange(event);
    });
} else {
    // Otherwise, create a new instance
    const player = new window.YT.Player(iframeElement, { ... });
}

Although the official argument for YT.get() is the “iframe ID string,” we set up a two-step binding process using the unofficial yet highly compatible method of passing the DOM element as a fallback in case there is no ID attribute.

3. “Polling Control” to Prevent Timing Conflicts

The core of these countermeasures is timing control to determine when the API load is complete and when other plugins have finished initialization. For this purpose, we decided to adopt a technique called polling.

However, the YouTube API comes with a global callback function window.onYouTubeIframeAPIReady that is automatically executed by the API when the script loading is complete. Why was such a roundabout method like polling necessary instead of monitoring that standard event handler?

3-1. The Asynchronous Risk Inherent in Wrappers for the Standard “onYouTubeIframeAPIReady”

When considering conflicts with other plugins, a common approach introduced as a standard trick on many development blogs is to “temporarily save the existing callback function into a variable, wrap it, and execute both the other plugin’s initialization and your own in succession” as follows:

// Save the existing callback if there is one
const previousOnReady = window.onYouTubeIframeAPIReady;

// Overwrite the global callback and execute the other processes in succession
window.onYouTubeIframeAPIReady = function () {
    if ( typeof previousOnReady === 'function' ) {
        previousOnReady();
    }
    myPluginInit(); // Initialize our own plugin
};

While this seems like a perfect solution for coexistence at first glance, this implementation actually carries a fatal risk: it cannot handle cases where other plugins initialize the player with asynchronous processing in between.

For example, suppose the other plugin we want to coexist with is designed to initialize by running an asynchronous process, such as “detecting API Ready, fetching configuration data via Ajax, and then creating the player.” In this case, our plugin’s (Sticky’s) initialization process has no way of knowing that the other plugin is waiting for its background asynchronous process to finish. Therefore, at the exact moment of API Ready, it determines that “no conflicting player instance exists yet” and goes ahead to create a new player (new YT.Player) ahead of the other.

By the time the other plugin finishes its asynchronous processing and tries to create its player, our plugin’s initialization is already complete. This causes a double-initialization error for the same iframe element, causing the other plugin to fail. Therefore, if you want to write a robust implementation that accounts for conflicts, you cannot use this onYouTubeIframeAPIReady callback directly as your own initialization trigger.

Our plugin must not interfere at all, such as by overwriting or assigning to the global callback; it should simply load the API, monitor in the background to see “when the other plugin’s initialization is complete,” and then safely share the ride (bind) to it. This is precisely why we need time control using “polling,” which will be explained next.

3-2. The Solution: Controlling Initialization Timing with Polling

To cleanly link the three approaches explained so far—wrapping, double-loading prevention, and event sharing—controlling the timing of the initialization process is extremely important. This is where a design pattern called “polling” comes in handy, which periodically checks the API load status and player initialization status from the program.

In JavaScript, polling is mainly implemented using setInterval. The actual initialization code is as follows:

function initPlayingMode(iframes) {
    // 1. Load the API after checking if another script has already been inserted
    if ( ! window.YT && ! document.querySelector( 'script[src*="youtube.com/iframe_api"], script[src*="youtube.com/player_api"]' ) ) {
        const tag = document.createElement( 'script' );
        tag.src = 'https://www.youtube.com/iframe_api';
        const firstScriptTag = document.getElementsByTagName( 'script' )[ 0 ];
        firstScriptTag.parentNode.insertBefore( tag, firstScriptTag );
    }

    // 2. Poll and monitor the API load and the completion of other plugins' initialization
    let attempts = 0;
    let apiReadyAttempts = 0;
    let setupCompleted = false;
    const checkInterval = setInterval( () => {
        attempts++;
        const isApiReady = window.YT && typeof window.YT.Player === 'function';
        if ( isApiReady ) {
            apiReadyAttempts++;
        }

        // Check if other plugins have finished creating instances for all iframes
        let allFound = false;
        if ( isApiReady && typeof window.YT.get === 'function' ) {
            allFound = true;
            for ( let j = 0; j < iframes.length; j++ ) {
                const id = iframes[ j ].id;
                const player = ( id ? window.YT.get( id ) : null ) || window.YT.get( iframes[ j ] );
                if ( ! player ) {
                    allFound = false;
                    break;
                }
            }
        }

        // Determine the termination conditions
        // - Binding by other plugins is complete (allFound), or
        // - The grace period (300ms) to wait for other plugins' initialization after the API loads has passed (apiReadyAttempts >= 3), or
        // - The maximum timeout (3 seconds) has been reached (attempts >= 30)
        const shouldStop = allFound || apiReadyAttempts >= 3 || attempts >= 30;
        if ( shouldStop ) {
            clearInterval( checkInterval );
            if ( ! setupCompleted ) {
                setupCompleted = true;

                // Perform either "ride-sharing" or "new creation" for each iframe
                setupPlayers( iframes );
            }
        }
    }, 100 );
}

After the API is ready, instead of initializing the player immediately on our own, this code sets up a maximum wait time of 300ms (checking the status up to 3 times every 100ms = polling). If another plugin is attempting to asynchronously create a player at the moment of API Ready, the purpose is to wait a short while for its completion before sharing the ride, thereby preventing double-creation errors as much as possible.

However, if you wait too long and our plugin’s initialization is delayed unnecessarily, there is a risk that the event listeners will not be registered yet by the time the video starts playing. As a result of trial and error balancing this trade-off, this 300ms wait time emerged as the empirical magic number (the best practical threshold) in this development process.

This value might vary depending on the purpose of your plugin.

The Ultimate Question: When Seemingly Perfect Codes Meet

With the implementation so far, we seem to have completed a mostly perfect conflict avoidance code that “does not interfere with the loading of other plugins,” “shares the ride on players created by other plugins,” and “waits 300ms to prevent double creation.” Some readers might also have agreed, thinking, “I see, this implementation looks like it should work fine.”

Here is a question. If Plugin A and Plugin B—two separate plugins, both incorporating the “perfect implementation” explained in this article—are loaded on the same page at the same time, can they coexist?

The answer, unfortunately, is “yes, there are cases, albeit rare, where they will cause conflict errors and go silent (break down).” The cause lies in the “asynchronous registration lag” of the YouTube API. In fact, there is a tiny lag of a few milliseconds between when you execute new YT.Player() and when that player instance is registered inside the API and becomes retrievable via window.YT.get().

If Plugins A and B, which share the same “300ms wait” logic, start their timers at the exact same API Ready timing, both will execute YT.get() almost simultaneously after 300ms. At this moment, since neither has created a player yet, the return value for both will be null. Consequently, both assume that no existing player exists, and both execute new YT.Player() almost at the same time. As a result, a double-creation error occurs on the same iframe, causing both to fail.

You might think, “Then why not detect double creation inside the onReady callback and clean it up with destroy()?” However, the YouTube API’s destroy() forcibly rewrites the DOM elements and clears event handlers, carrying the fatal side effect of taking down and destroying the player that was already running normally. In other words, once a double creation has occurred, it cannot be safely removed afterward.

Introducing “Random Jitter” as the Solution

Since the YouTube API does not provide events for perfect synchronization across multiple plugins, there is no perfect code that can reduce the probability of this timing collision to 0%. However, the solution to suppress this collision probability to practically zero (an ignorable level) is the introduction of “random jitter”.

What we do is very simple. After the 300ms grace period expires, instead of creating the new player immediately, we insert a “random delay of 0 to 100ms” right before execution.

// Executed after the 300ms monitoring termination condition is met
if ( shouldStop ) {
    clearInterval( checkInterval );
    if ( ! setupCompleted ) {
        setupCompleted = true;

        // Disperse execution timing by inserting a random jitter (delay) of 0 to 100ms
        const jitterDelay = Math.random() * 100;
        setTimeout( () => {
            // Check window.YT.get() once more after the random delay expires
            setupPlayers( iframes );
        }, jitterDelay );
    }
}

By adding a random delay, there is a high probability of a discrepancy in the execution timing of Plugin A and Plugin B, which started moving at the same time.

For example, suppose the random delay is 15ms for Plugin A and 78ms for Plugin B. After 15ms, Plugin A, whose delay expired first, creates a new YT.Player. Subsequently, when Plugin B performs its YT.get() check after 78ms, the instance from Plugin A will already be detected. As a result, Plugin B cancels the creation of a new instance and safely shares the ride on Plugin A.

The beauty of this design is that “if all plugins depending on the YouTube API adopt this ‘concession via random jitter’ design, conflict-free coexistence (ride-sharing) can be achieved autonomously in almost all cases.” This is, so to speak, a piece of wisdom to achieve coexistence by writing the spirit of mutual concession into code without waiting for improvements on the API side.

We have also built this collision avoidance and coexistence design using random jitter into the sticky plugin we developed, “KU Sticky Video for YouTube” (and its paid Pro version).

Conclusion

Using the API of a major external service like YouTube in a plugin inevitably means harboring the potential for conflicts.

Users embed YouTube videos in their posts and apply various customizations to them. For this, it is naturally expected that they will use multiple YouTube-related plugins together. In anticipation of this, designing an implementation that allows the dependent API to be used without conflicts is indispensable.

The recently developed KU Sticky Video for YouTube and its paid version, KU Sticky Video for YouTube Pro, were also successfully released after identifying and resolving these issues one by one during development. If you want to showcase YouTube videos effectively alongside text, we highly recommend giving them a try.

Please also try using them alongside other YouTube plugins! They should work without any problems (but if you do run into issues, please let me know quietly via the contact form).