jQuery is commonly used in WordPress themes and plugins to add interactive features, handle events, and manipulate page elements. However, you may notice that a jQuery script works on a regular website but produces an error when you use it in WordPress.
One common error is:
TypeError: $ is not a function
This usually happens because WordPress runs jQuery in no-conflict mode. In this mode, WordPress does not allow jQuery to use the $ shortcut globally, since other JavaScript libraries may also use the same variable.
Fortunately, you can still use the familiar $ sign in your jQuery code by using a small wrapper function. This guide explains the different ways to do it.
1. Why Does the $ Sign Not Work in WordPress?
On many websites, you can write jQuery code like this:
$(document).ready(function() {
// Your jQuery code goes here.
});
However, this may produce an error in WordPress because the global $ variable is not automatically assigned to jQuery.
WordPress uses jQuery’s no-conflict mode to avoid conflicts with other JavaScript libraries. This means you should use jQuery instead of $ in the global scope, or define a local $ alias inside a function.
2. Use jQuery(document).ready() to Use the $ Sign
The simplest solution is to pass $ as a parameter to the document-ready callback. This makes the jQuery object available through the $ shortcut inside that function.
Use the following code:
jQuery(document).ready(function($) {
// You can use $ as the jQuery object here.
var body = $('body');
body.addClass('custom-class');
});
In this example, jQuery(document).ready() waits until the document is ready. The $ parameter creates a local alias for jQuery, so you can use the usual jQuery syntax inside the callback.
3. Use an Immediately Invoked Function Expression (IIFE)
Another way to use the $ sign is to wrap your code in an immediately invoked function expression (IIFE).
This approach passes the global jQuery object into a function and assigns it to the local $ parameter.
(function($) {
// Use $ as the jQuery object here.
var body = $('body');
body.addClass('custom-class');
})(jQuery);
The function runs immediately, and the $ shortcut is available only inside it. This is useful when writing jQuery code for WordPress plugins or themes.
If your code also needs to wait until the document is ready, combine the IIFE with the ready callback:
(function($) {
$(document).ready(function() {
// Your jQuery code goes here.
$('body').addClass('custom-class');
});
})(jQuery);
4. Use jQuery.noConflict() to Create a Different Alias
You can also use the jQuery.noConflict() method to assign jQuery to another variable. This is helpful if you want to use a custom alias instead of $.
var jq = jQuery.noConflict();
jq(document).ready(function() {
alert('jQuery is working without using the $ alias.');
jq('selector').show();
});
In this example, jq becomes the variable used to access jQuery. The code uses jq instead of $ for selecting elements and running jQuery methods.
Replace selector with the CSS selector of the element you want to target.
5. Make Sure jQuery Is Loaded Properly in WordPress
Even if you use the correct no-conflict syntax, your code will not work if jQuery has not been loaded on the page.
When adding a custom JavaScript file to a WordPress theme, enqueue it with jQuery as a dependency. Add this PHP code to your child theme’s functions.php file:
/**
* Load a custom script with jQuery as a dependency.
*/
function geekerhub_enqueue_custom_jquery_script() {
wp_enqueue_script(
'geekerhub-custom-script',
get_stylesheet_directory_uri() . '/js/custom-script.js',
array( 'jquery' ),
'1.0.0',
true
);
}
add_action(
'wp_enqueue_scripts',
'geekerhub_enqueue_custom_jquery_script'
);
Create a JavaScript file at /js/custom-script.js inside your child theme directory and add your jQuery code there.
For example:
jQuery(document).ready(function($) {
$('.my-button').on('click', function() {
alert('Button clicked!');
});
});
The array( 'jquery' ) dependency tells WordPress to load jQuery before your custom script. This is the recommended way to load scripts in a WordPress theme or plugin.
You can read more about this method in the official WordPress documentation for wp_enqueue_script().
6. How to Troubleshoot jQuery Errors in WordPress
If you still see the $ is not a function error, check the following points:
- Check the jQuery syntax: Make sure you use
jQuery(document).ready(function($) { ... })or an IIFE when using the$shortcut. - Check whether jQuery is loaded: Open your browser’s developer console and look for errors related to missing scripts.
- Check script dependencies: If you enqueue a custom script, include
jqueryin its dependency array. - Check the script loading order: Your custom script must load after its dependencies.
- Check for JavaScript conflicts: Another theme or plugin script may be causing an error. Test with other scripts temporarily disabled if necessary.
- Clear caches: Clear browser, plugin, and server-side caches after changing JavaScript files.
If you are troubleshooting other WordPress issues, you may also find our guide on common WordPress errors and how to fix them useful.
Conclusion
WordPress uses jQuery in no-conflict mode, which is why the $ shortcut may not work in the global scope. You can solve this by using jQuery(document).ready(function($) { ... }), wrapping your code in an IIFE, or assigning jQuery to a different variable with jQuery.noConflict().
Also, make sure jQuery is loaded as a dependency when you enqueue your custom JavaScript file. This helps prevent loading-order issues and makes your scripts work more reliably in WordPress.
