Home » Web Tutorials » WordPress » How to Fix jQuery Problems in WordPress?

How to Fix jQuery Problems in WordPress?

jQuery is a free open-source, lightweight JavaScript library that simplifies HTML document manipulation and event handling. It plays an important role in WordPress sites by enhancing interactivity in elements like sliders, form validations, pop-up, etc. However, jQuery issues in WordPress are common, especially after updating and installing plugins. A broken jQuery script can lead to malfunctioning elements, browser console errors or even a completely unusable site. In this article, we will explain how to identify and fix jQuery related problems in WordPress.

Identifying the Problem

It is always a good practice to routinely test your website, especially after updating WordPress core, themes, or plugins. If you notice issues such as a non-functional slider, search box not working or distorted layout, the problem could potentially be related to jQuery. Before attempting to fix the issue, check your browser console to identify the source of the error.

  • Open your browser and press F12 key (in Windows) or right-click and select “Inspect” or “Inspect Element” option to open Developer Tools section.
  • Go to “Console” tab and check for jQuery related errors. You can look for messages like “$ is not defined” or “Uncaught TypeError”.
  • Check the source of the issue to find whether it’s from a plugin, theme, or WordPress core.

As you can see in the below example screenshot, there are two script errors related to the theme.

Browser Console jQuery Errors
Browser Console jQuery Errors

1. Update WordPress, Plugins, and Themes

The WordPress core software comes with the latest version of jQuery located in /wp-includes/js/jquery/ folder. However, most themes and plugins include their own jQuery version to support custom functionalities. So, most of the times jQuery problems arise from outdated scripts used by the theme or plugin.

  • If you are facing a problem after updating a free plugin or theme installed from WordPress repository, it is possible to revert the plugin or theme to its old version to reinstate your site.
  • On other hand, if you face problems after updating WordPress core, make sure to update theme and plugins to the latest version so that they are compatible with the latest WordPress core version.  
jQuery in WordPress
jQuery in WordPress

2. Check for jQuery Migrate Issues

WordPress core also comes with the latest jQuery Migrate plugin which you can find it under /wp-includes/js/jquery/ folder. This helps to mitigate the issues of upgrading to newer versions of jQuery. However, your theme or plugin may need older jQuery Migrate version to work properly.

In this case, follow the below steps:

  • Install the Enable jQuery Migrate Helper plugin to restore the older jQuery version for compatibility.
  • When the plugin is active, check the browser console for deprecated functions and errors.
  • Find the root cause of the errors and fix the plugin or theme that causing them and make sure there are not console errors.
  • Now, you can deactivate the plugin and test your site is working properly. If yes, then delete the plugin.

3. Test with Default Theme and No Plugins

Follow the below steps if you are not able to find the root cause:

  • First, put your site in maintenance mode.
  • Disable all the installed plugins and change your theme to one of the default WordPress themes (for example – Twenty Twenty Five).
  • Reactivate the plugins one by one to find the culprit causing the issue.

If jQuery issues appear only with a specific plugin, you may need to update that plugin or switch to an alternative.

Note: Switching your theme may change the sidebar and footer widgets which you need to manually setup again. While the latest default WordPress themes are block-based, most commercial themes are still non-block-based themes. If you are using a non-block theme, make sure to select a default non-block theme like Twenty Twenty Three.

4. Ensure jQuery is Loaded Correctly

If you are using custom jQuery version, ensure it is properly enqueued in functions.php file of your theme. You can use the following code snippet for that purpose (add in functions.php file):

function enqueue_jquery() {
wp_enqueue_script('jquery');
}
add_action('wp_enqueue_scripts', 'enqueue_jquery');

Also, avoid loading multiple jQuery versions, which can cause conflicts.

5. Use No Conflict Mode

If you read the jQuery code, it uses $ as a shortcut for jQuery. This works fine when you independently use the code. However, this may create conflicts when using with multiple plugins on your WordPress site as any other plugin code may uses same $ symbol. This can cause errors like “$ is not defined” in the browser console. To fix this, you can run jQuery in no-conflict mode as explained in the official documentation.

Summary of the options are:

  • Replace $ symbol with jQuery in functions.
  • Pass $ inside the function like jQuery( document ).ready(function( $ ) { Code Here } );
  • Check the sequence of the loaded scripts and include jQuery as a first script.

6. Defer or Async Issues

Loading jQuery with defer or async attributes can break scripts. Most caching and optimization plugins like WP Rocket, Autoptimize, Speed Optimizer, and Perfmatters, will apply these attributes when you defer JavaScript. If this causes issues, consider adding jQuery in the exception list. This will help to defer all other script files on your site except jQuery thus allowing the functionalities to work properly.

As you can see in the below screenshot, WP Rocket will automatically add exclusion rule to avoid deferring any script file that contains a word jQuery.

Defer JavaScript in WP Rocket
Defer JavaScript in WP Rocket

7. Delayed JavaScript Issues

This problem is same as the previous point. Caching and optimization plugins have an option for delaying JavaScript execution to improve the initial page loading speed. However, this can cause jQuery-dependent scripts to break. If you notice issues, try disabling JavaScript delay in your optimization plugin settings or exclude jQuery from being delayed.

Below is the screenshot of “Delay JavaScript” settings page from Perfmatters plugin. You can easily exclude jquery.js and jquery.min.js files while delaying all other scripts on the site.

Delay JS in Perfmatters
Delay JS in Perfmatters

9. Debug Errors and Fix Them

If you are not able to understand the error from browser console, you can try the default WordPress debugging option to get more details. Add the following lines in your wp-config.php file:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Now, open your site and find if there any errors displayed on the frontend. You can also check the /wp-content/debug.log for finding error logs. Once you found the details, make sure to remove the above code from your wp-config file to disable the debug mode.

10. Use a Different jQuery Version

WordPress will use the latest jQuery version automatically updated from version 5.6. However, some themes or plugins require older jQuery versions to work properly. If you do not know which version if needed, use Version Control for jQuery plugin. This plugin will help you to switch versions (jQuery as well as jQuery Migrate) safely so that you can find which version is working on your site.

You can use this as a temporary measure to restore your site or broken functionality till the time fixing the issue. After fixing the issue, you can safely deactivate / delete the plugin with no further action needed.   

Final Words

If you are using updated WordPress core, plugins and theme, most jQuery related problems come from optimization techniques used to speed up your site. It is better to exclude jQuery in any JavaScript related features like minifying, delaying, and deferring. Unfortunately, sometimes the solution needs more technical approach like using no-conflict mode. If you are not able to resolve the problem, avoid messing up with your code and reach out to plugin/theme developers or WordPress support forums with error logs and console messages to find a solution. Till the time of fixing issue, you can use old jQuery version using a plugin as explained in method 10.

Leave a Comment

Your email address will not be published. Required fields are marked *