Using jQuery in a WordPress Theme

written by William Patton on March 23, 2013 in JQuery and WordPress Custom with one Comment

← older posts newer posts →

There are good ways and bad ways to use jQuery in a WordPress theme and there’s a few things you need to know to make sure you’re doing it right. The ordinary method of pasting a link to jQuery in your <head> and then your custom script afterwards isn’t quite how it’s done with WordPress. There’s 3 main things to note when using jQuery in WordPress.

Scripts should be registered with WordPress and added to the front end using wp_enqueue_script.
WordPress already includes a local copy of the jQuery library and it’s already registered, you just need to enqueue it.
WordPress implements noConflict() as standard so you need to define your objects ever so slightly different than you normally would.

Including the jQuery Library in Your Theme

You might just be tempted to paste something like <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script> into your header.php file. That would be the wrong way of doing it. It’s wrong mostly because there’s a better way.

What if a plugin used jQuery and also included it? Then you would have 2 copies in your header – that means 2 lookups and 2 downloads of the same script. That means one overridign or conflicting with the other. Increasing the lookup times and download size of your page as well as causing possible conflicts for no reason is just silly so let’s learn how to do it the right way.

Enqueuing jQuery

To include the jQuery library in your theme’s <head> section you should to enqueue the script. Enqueueing it ensures that it’s only included in the code once. No matter how many different plugins/pages try to include it WordPress will still only include it the one time, and because it’s using wp_enqueue_script it will only be included on the front-end – where it’s needed.

As WordPress already includes a local copy of the jQuery library and it’s already registered we can skip over a few of the parameters that wp_enqueue_script accepts and do everything in a single line of code.

wp_enqueue_script( 'jquery' );

Just so you can see a full call, with all parameters, here’s what it would look like if everything was passed.

wp_enqueue_script( 'jquery', '//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js', array(), '1.9.1', true);

In the second code we are giving a name to our script (jquery) the address of it (on googleapis.com), an empty array is passed for dependancies here to be loaded first (I’ll talk about that in the next section) and a version string.

The final parameter is boolean and is the toggle that says if you want the script in the footer or the default location in the header. Setting it to true includes it in the footer there while setting it as false, or not including it at all, places the script in the head.

Adding scripts to the footer relies on wp_footer() being present. Similarly adding it to the head requires wp_head(). Both of those hooks should be included in all WordPress themes, so you likely don’t even need to think about them but if your scripts aren’t being included look to see if you have those hooks present in header.php and footer.php.

The second code block is enqueueing and registering the script at the same time, but as WordPress already registers its local copy of the script under the name ‘jquery’ you can just tell it to enqueue.

So all we need in our functions.php file is the first code block wp_enqueue_script( 'jquery' ); and jquery will be included in the head of our script. Simply change it to wp_enqueue_script( 'jquery', true ); if you want it in the footer.

Writing your custom jQuery script for WordPress

WordPress includes the jQuery library in noConflict() mode by default for a couple of reasons. Mostly to prevent conflicts arising from other JavaScript libraries WordPress can use, and because if one plugin uses jQuery and a second uses it too there is a chance of the second getting data from the first, causing a conflict, and leading to some crazy results.

The fact that noConflict() mode is on causes problems for some people because not knowing, and not programming accordingly, will make their scripts simply not work.

jQuery for WordPress

I have a very small piece of jQuery in my Theme-Dev framework that controls opening and closing the responsive nav on smaller screen devices.

/*! Responsive Nav */ jQuery(document).ready(function($){ $("#nav-toggle").click(function(){ $("#responsive-nav").toggle(800); }); });

I have it in an external file and enqueue it, like the example above, and it works fine but when I programmed it I done it directly in the head section using a <script type="text/javascript"></script> tag.

I wrote it like this:

/*! Responsive Nav */ $(document).ready(function(){ $("#nav-toggle").click(function(){ $("#responsive-nav").toggle(800); }); });

It worked when I tested it in a static file locally but when I moved it to an external file and enqueued it within my WordPress theme it did not. I was like WTF! But then I remembered the noConflict() mode enabled by default and facepalmed lol

I had referenced the jQuery object using the shortcut ‘$‘ just as I normally do but when noConflict() mode is enable that reference is to something that doesn’t exist, or another library altogether. There’s a couple of ways around this but a really quick fix it to change the first reference to ‘$‘ to ‘jQuery‘ and then reassign it to a variable named ‘$‘. You can do all that in the first line of the code changing $(document).ready(function(){ to jQuery(document).ready(function($){. After that you can reference jQuery within the function simply with ‘$‘.

Or you can create a variable to reference the jQuery object with like this

$j = jQuery

As I discovered when trying to write this post it’s pretty hard to put into words how this all works so if you still have trouble understanding it then there’s some pretty useful documentation on using jQuery with WordPress on the WordPress.org wp_enqueue_script page.

Once you have the jQuery library included, and you have written your custom script you can register it and enqueue it with wp_enqueue_script the same as I showed above with the jQuery snippet. You should use get_template_directly_uri() to point to your theme location. My script is called ‘responsive-nav.js‘ and is in the ‘js‘ folder of my theme.

wp_enqueue_script( 'responsive-nav', get_template_directory_uri() . '/js/responsive-nav.js', array('jquery'), '1.0', true);

I’ve given my custom script the name ‘responsive-nav‘, pointed to the address of it, told WordPress it depends on ‘jquery‘, it’s version 1.0 of the script and we want it to be included in the footer instead of the header.

Telling WordPress that our script depends on ‘jquery‘ means that our script will be added after the jQuery library is loaded and if it doesn’t get loaded, neither does our custom script – because it won’t work without the jQuery library.

In Conclusion

Using jQuery with WordPress isn’t quite the same as using it within static pages however once you understand the basics of it you can then make use of it the same way you would on any other page. Sure, it might take a little bit of time to get the hang of but once you do you shouldn’t need to treat it any differently than you do elsewhere.

PattonWebz